Stats Models - API Contract

GET /api/v1/stats-snapshots/api/v1/stats-snapshots

List all persisted stats snapshots

Public

Response Example

{
  "data": [
    {
      "snapshot_id": "snap_001",
      "user_id": "usr_4f8a2c",
      "total_activities": 47,
      "completed_activities": 42,
      "pending_activities": 5,
      "hours_logged": 128.5,
      "time_window": "quarterly",
      "start_date": "2026-01-01",
      "end_date": "2026-03-26",
      "generated_at": "2026-03-26T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

GET /api/v1/stats-snapshots/api/v1/stats-snapshots/:snapshotId

Get a single stats snapshot by ID

Public

Response Example

{
  "snapshot_id": "snap_001",
  "user_id": "usr_4f8a2c",
  "total_activities": 47,
  "completed_activities": 42,
  "pending_activities": 5,
  "hours_logged": 128.5,
  "time_window": "quarterly",
  "start_date": "2026-01-01",
  "end_date": "2026-03-26",
  "generated_at": "2026-03-26T10:00:00Z"
}

POST /api/v1/stats-snapshots/api/v1/stats-snapshots

Persist a new stats snapshot

Public

Request Example

{
  "user_id": "usr_4f8a2c",
  "total_activities": 47,
  "completed_activities": 42,
  "pending_activities": 5,
  "hours_logged": 128.5,
  "time_window": "quarterly",
  "start_date": "2026-01-01",
  "end_date": "2026-03-26"
}

Response Example

{
  "snapshot_id": "snap_002",
  "user_id": "usr_4f8a2c",
  "total_activities": 47,
  "completed_activities": 42,
  "pending_activities": 5,
  "hours_logged": 128.5,
  "time_window": "quarterly",
  "start_date": "2026-01-01",
  "end_date": "2026-03-26",
  "generated_at": "2026-03-26T10:07:00Z"
}

PUT /api/v1/stats-snapshots/api/v1/stats-snapshots/:snapshotId

Update an existing stats snapshot (e.g. after recalculation)

Public

Request Example

{
  "total_activities": 49,
  "completed_activities": 44,
  "pending_activities": 5,
  "hours_logged": 133
}

Response Example

{
  "snapshot_id": "snap_001",
  "user_id": "usr_4f8a2c",
  "total_activities": 49,
  "completed_activities": 44,
  "pending_activities": 5,
  "hours_logged": 133,
  "time_window": "quarterly",
  "start_date": "2026-01-01",
  "end_date": "2026-03-26",
  "generated_at": "2026-03-26T10:08:00Z"
}

DELETE /api/v1/stats-snapshots/api/v1/stats-snapshots/:snapshotId

Delete a stats snapshot

Public

Response Example

{
  "deleted": true,
  "snapshot_id": "snap_001"
}

GET /api/v1/stats-snapshots/api/v1/stats-snapshots/chart-points

List chart data points across snapshots

Public

Response Example

{
  "data": [
    {
      "date": "2026-03-01",
      "value": 3.5
    },
    {
      "date": "2026-03-08",
      "value": 5
    },
    {
      "date": "2026-03-15",
      "value": 4
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3
  }
}

Additional Metadata

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