pikebacker/docs/09_api_contract.md

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:

{
  "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.