Period Configuration Repository - API Contract

GET /api/v1/period-presets/api/v1/period-presets

List all period presets for an organization

Public

Response Example

{
  "data": [
    {
      "id": "preset-001",
      "org_id": "org-bufdir-42",
      "name": "Q1 2026",
      "preset_type": "quarterly",
      "start_date": "2026-01-01",
      "end_date": "2026-03-31",
      "is_active": true,
      "created_at": "2025-12-01T09:00:00Z",
      "updated_at": "2025-12-01T09:00:00Z"
    },
    {
      "id": "preset-002",
      "org_id": "org-bufdir-42",
      "name": "H1 2026",
      "preset_type": "semi_annual",
      "start_date": "2026-01-01",
      "end_date": "2026-06-30",
      "is_active": true,
      "created_at": "2025-12-01T09:00:00Z",
      "updated_at": "2025-12-01T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

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

Get a single period preset by ID

Public

Response Example

{
  "id": "preset-001",
  "org_id": "org-bufdir-42",
  "name": "Q1 2026",
  "preset_type": "quarterly",
  "start_date": "2026-01-01",
  "end_date": "2026-03-31",
  "is_active": true,
  "created_at": "2025-12-01T09:00:00Z",
  "updated_at": "2025-12-01T09:00:00Z"
}

POST /api/v1/period-presets/api/v1/period-presets

Create a new period preset for an organization

Public

Request Example

{
  "org_id": "org-bufdir-42",
  "name": "Q2 2026",
  "preset_type": "quarterly",
  "start_date": "2026-04-01",
  "end_date": "2026-06-30",
  "is_active": true
}

Response Example

{
  "id": "preset-003",
  "org_id": "org-bufdir-42",
  "name": "Q2 2026",
  "preset_type": "quarterly",
  "start_date": "2026-04-01",
  "end_date": "2026-06-30",
  "is_active": true,
  "created_at": "2026-03-26T10:30:00Z",
  "updated_at": "2026-03-26T10:30:00Z"
}

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

Update an existing period preset

Public

Request Example

{
  "name": "Q2 2026 (Revised)",
  "start_date": "2026-04-01",
  "end_date": "2026-06-30",
  "is_active": false
}

Response Example

{
  "id": "preset-003",
  "org_id": "org-bufdir-42",
  "name": "Q2 2026 (Revised)",
  "preset_type": "quarterly",
  "start_date": "2026-04-01",
  "end_date": "2026-06-30",
  "is_active": false,
  "created_at": "2026-03-26T10:30:00Z",
  "updated_at": "2026-03-26T11:15:00Z"
}

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

Delete a period preset by ID

Public

Response Example

{
  "deleted": true,
  "id": "preset-003"
}

GET /api/v1/period-presets/api/v1/period-presets/watch

Server-sent events stream for real-time preset changes (watchPresets)

Public

Response Example

data: {"event":"preset_updated","preset_id":"preset-001","org_id":"org-bufdir-42","timestamp":"2026-03-26T10:00:00Z"}

Additional Metadata

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