# API Contract

The machine-readable OpenAPI draft is in `schemas/openapi.yaml`.

## Core endpoints

### Create trip

`POST /v1/trips`

Creates a trip shell from user inputs.

### Plan route

`POST /v1/routes/plan`

Input:

- start/end/imported GPX,
- profile,
- constraints,
- preferred providers.

Output:

- route id,
- geometry,
- distance/elevation,
- scores,
- warnings,
- candidate alternatives.

### Plan stages

`POST /v1/stages/plan`

Input:

- route id,
- day count/date range,
- daily constraints,
- sleep preferences.

Output:

- stage cards,
- Plan A/B endpoints,
- sleep/food/water/repair/bailout candidates,
- stage warnings.

### Corridor POIs

`GET /v1/routes/{route_id}/pois?category=water&buffer_km=5`

Returns route-relevant POIs with distance along route, detour distance, confidence, and source.

### Critical gaps

`GET /v1/routes/{route_id}/gaps`

Returns computed gaps for water, food, sleep, repair, bailout, and charging.

### Rule cards

`GET /v1/rules?bbox=minLon,minLat,maxLon,maxLat&route_id=...`

Returns route- or area-specific advisory cards.

### Offline pack

`POST /v1/offline-packs`

Generates a manifest and download URLs for cached trip data.

### Export

`GET /v1/routes/{route_id}/export?format=gpx`

MVP: GPX. Later: TCX and FIT.

### Local report

`POST /v1/reports`

Submits a dated, location-bound structured report. The MVP response includes `moderationStatus`, `trustScore`, and `queuedOffline` when an offline client id is supplied.

### Report sync

`POST /v1/reports/sync`

Future endpoint. The current MVP queues reports client-side while offline and resubmits them through `POST /v1/reports`.

## Error handling

Errors should include:

- machine-readable code,
- human-readable message,
- remediation suggestion,
- provider/source if relevant.

Example:

```json
{
  "error": "PROVIDER_UNAVAILABLE",
  "message": "routing provider \"openrouteservice\" is not available in this MVP runtime. Set ROUTING_PROVIDER=mock for fixture mode or configure the selected provider adapter and credentials.",
  "details": {
    "providerName": "openrouteservice",
    "providerType": "routing",
    "setupHint": "Set ROUTING_PROVIDER=mock for fixture mode or configure the selected provider adapter and credentials."
  }
}
```

## Current MVP notes

- `schemas/openapi.yaml` reflects implemented response fields including route segments, surface breakdown, attribution, stage POI buckets, offline manifest metadata, and report queue ids.
- `format=gpx` is implemented. TCX/FIT are reserved for future `DeviceExportProvider` adapters.
- Mock providers are deterministic and require no external keys.
- Rule cards and access/protected-area warnings are advisory and confidence-scored.