Period Selection BLoC - API Contract

GET /api/v1/period-selections/api/v1/period-selections

List active period selection sessions for an organization

Public

Response Example

{
  "data": [
    {
      "session_id": "sel-session-001",
      "org_id": "org-bufdir-42",
      "state": "preset_selected",
      "selected_preset_id": "preset-001",
      "selected_range": {
        "start": "2026-01-01T00:00:00Z",
        "end": "2026-03-31T23:59:59Z"
      },
      "is_confirmed": false,
      "created_at": "2026-03-26T10:00:00Z",
      "updated_at": "2026-03-26T10:05:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

GET /api/v1/period-selections/api/v1/period-selections/:id

Get the current state of a period selection session

Public

Response Example

{
  "session_id": "sel-session-001",
  "org_id": "org-bufdir-42",
  "state": "preset_selected",
  "selected_preset_id": "preset-001",
  "selected_range": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "is_confirmed": false,
  "created_at": "2026-03-26T10:00:00Z",
  "updated_at": "2026-03-26T10:05:00Z"
}

POST /api/v1/period-selections/api/v1/period-selections

Open a new period selection session for an organization

Public

Request Example

{
  "org_id": "org-bufdir-42"
}

Response Example

{
  "session_id": "sel-session-002",
  "org_id": "org-bufdir-42",
  "state": "idle",
  "selected_preset_id": null,
  "selected_range": null,
  "is_confirmed": false,
  "created_at": "2026-03-26T11:00:00Z",
  "updated_at": "2026-03-26T11:00:00Z"
}

PUT /api/v1/period-selections/api/v1/period-selections/:id

Dispatch an event to the BLoC session — maps to add(PeriodSelectionEvent) and onPresetSelected(SelectPresetEvent)

Public

Request Example

{
  "event_type": "select_preset",
  "payload": {
    "preset_id": "preset-001"
  }
}

Response Example

{
  "session_id": "sel-session-002",
  "org_id": "org-bufdir-42",
  "state": "preset_selected",
  "selected_preset_id": "preset-001",
  "selected_range": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "is_confirmed": false,
  "event_processed": "select_preset",
  "updated_at": "2026-03-26T11:02:00Z"
}

DELETE /api/v1/period-selections/api/v1/period-selections/:id

Close and clean up a period selection session (maps to close())

Public

Response Example

{
  "closed": true,
  "session_id": "sel-session-002"
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}