Period Preset Service - API Contract

GET /api/v1/organizations/api/v1/organizations/:org_id/period-presets

Retrieve all available 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,
      "record_count": 312
    },
    {
      "id": "preset-002",
      "org_id": "org-bufdir-42",
      "name": "Full Year 2025",
      "preset_type": "annual",
      "start_date": "2025-01-01",
      "end_date": "2025-12-31",
      "is_active": true,
      "record_count": 1847
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

GET /api/v1/organizations/api/v1/organizations/:org_id/period-presets/current-cycle

Get the active preset for the current reporting cycle

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,
  "days_remaining": 5,
  "cycle_progress_pct": 96
}

POST /api/v1/organizations/api/v1/organizations/:org_id/period-presets/resolve-range

Resolve a preset definition into a concrete DateTimeRange

Public

Request Example

{
  "preset_id": "preset-002",
  "preset_type": "semi_annual",
  "reference_date": "2026-03-26"
}

Response Example

{
  "preset_id": "preset-002",
  "resolved_range": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-06-30T23:59:59Z"
  },
  "duration_days": 181,
  "label": "H1 2026"
}

Additional Metadata

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