Period Record Count Service - API Contract

GET /api/v1/period-record-counts/api/v1/period-record-counts

List record count summaries for multiple ranges (paginated)

Public

Response Example

{
  "data": [
    {
      "id": "count-snapshot-001",
      "org_id": "org-bufdir-42",
      "range_start": "2026-01-01T00:00:00Z",
      "range_end": "2026-03-31T23:59:59Z",
      "record_count": 312,
      "is_complete": false,
      "snapshot_at": "2026-03-26T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

GET /api/v1/period-record-counts/api/v1/period-record-counts/:id

Get a specific record count snapshot by ID

Public

Response Example

{
  "id": "count-snapshot-001",
  "org_id": "org-bufdir-42",
  "range_start": "2026-01-01T00:00:00Z",
  "range_end": "2026-03-31T23:59:59Z",
  "record_count": 312,
  "is_complete": false,
  "snapshot_at": "2026-03-26T08:00:00Z"
}

POST /api/v1/period-record-counts/api/v1/period-record-counts

Count records for an org within a specified DateTimeRange

Public

Request Example

{
  "org_id": "org-bufdir-42",
  "range": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  }
}

Response Example

{
  "org_id": "org-bufdir-42",
  "range": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "record_count": 312,
  "is_complete": false,
  "computed_at": "2026-03-26T10:45:00Z"
}

PUT /api/v1/period-record-counts/api/v1/period-record-counts/:id

Force-refresh a count snapshot for an existing range

Public

Request Example

{
  "range": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  }
}

Response Example

{
  "id": "count-snapshot-001",
  "org_id": "org-bufdir-42",
  "range_start": "2026-01-01T00:00:00Z",
  "range_end": "2026-03-31T23:59:59Z",
  "record_count": 318,
  "is_complete": false,
  "snapshot_at": "2026-03-26T11:00:00Z"
}

DELETE /api/v1/period-record-counts/api/v1/period-record-counts/:id

Delete a count snapshot

Public

Response Example

{
  "deleted": true,
  "id": "count-snapshot-001"
}

GET /api/v1/period-record-counts/api/v1/period-record-counts/stream

Server-sent events stream of live record counts for a range (getCountStream)

Public

Response Example

data: {"org_id":"org-bufdir-42","record_count":318,"is_complete":false,"timestamp":"2026-03-26T11:01:00Z"}

Additional Metadata

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