MobilityOps/docs/05-api-contract.md

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

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