# API contract summary

The machine-readable baseline is `contracts/openapi.yaml`.

## Authentication

The demo may use signed server-issued sessions or short-lived JWTs. Demo-role buttons create an authenticated session; they do not bypass authorization middleware.

## Required routes

### System and demo

- `GET /health`
- `GET /api/v1/system/status`
- `POST /api/v1/demo/login`
- `POST /api/v1/demo/reset` — Operations Manager only

### Dashboard

- `GET /api/v1/dashboard`

### Vehicles

- `GET /api/v1/vehicles`
- `GET /api/v1/vehicles/{public_ref}`

### Bookings and return

- `GET /api/v1/bookings`
- `GET /api/v1/bookings/{public_ref}`
- `POST /api/v1/bookings/{public_ref}/return`

Return commands require an `Idempotency-Key` header and optimistic version where relevant.

### Data quality

- `GET /api/v1/data-quality/issues`
- `GET /api/v1/data-quality/issues/{public_ref}`
- `POST /api/v1/data-quality/issues/{public_ref}/defer`
- `POST /api/v1/data-quality/issues/{public_ref}/reject`
- `POST /api/v1/data-quality/issues/{public_ref}/merge-customers`

### Knowledge

- `POST /api/v1/knowledge/questions`
- `GET /api/v1/knowledge/status`

### Automation and audit

- `GET /api/v1/workflows`
- `POST /api/v1/workflows/{event_id}/retry`
- `GET /api/v1/audit`

### MCP-provider endpoints

Service-token protected:

- `GET /api/v1/integrations/mcp/operations-summary`
- `GET /api/v1/integrations/mcp/attention-vehicles`
- `GET /api/v1/integrations/mcp/vehicles/{public_ref}`

Knowledge search may be routed by the Hub directly to RAGcore or through a narrowly scoped MobilityOps façade. Use the contract chosen in `docs/10-mcp-hub-integration.md`.

## Error shape

```json
{
  "error": {
    "code": "ODOMETER_REGRESSION",
    "message": "The submitted reading is below the current canonical odometer.",
    "correlation_id": "...",
    "details": {}
  }
}
```