Local Distance Cache - API Contract

GET /api/v1/distance-cache/api/v1/distance-cache

List all entries in the local distance cache (admin/debug view).

Public

Response Example

{
  "data": [
    {
      "user_id": "usr_abc123",
      "distance_km": 42.5,
      "written_at": "2026-03-25T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

GET /api/v1/distance-cache/api/v1/distance-cache/:userId

Read a single user's cached distance value.

Public

Response Example

{
  "user_id": "usr_abc123",
  "distance_km": 42.5,
  "written_at": "2026-03-25T14:30:00Z"
}

POST /api/v1/distance-cache/api/v1/distance-cache

Write a distance value to the local cache for a user.

Public

Request Example

{
  "user_id": "usr_abc123",
  "distance_km": 42.5
}

Response Example

{
  "user_id": "usr_abc123",
  "distance_km": 42.5,
  "written_at": "2026-03-25T14:30:00Z"
}

PUT /api/v1/distance-cache/api/v1/distance-cache/:userId

Overwrite the cached distance value for a user.

Public

Request Example

{
  "distance_km": 55
}

Response Example

{
  "user_id": "usr_abc123",
  "distance_km": 55,
  "written_at": "2026-03-25T15:45:00Z"
}

DELETE /api/v1/distance-cache/api/v1/distance-cache/:userId

Remove a user's entry from the local distance cache.

Public

Response Example

{
  "user_id": "usr_abc123",
  "removed": true,
  "removed_at": "2026-03-25T16:00:00Z"
}

Additional Metadata

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