v1 API (Deterministic Timeline)

The v1 API provides a deterministic, event-sourced timeline engine for managing trip events with conflict detection and validation.

Key Concepts

• Revision Control: Each trip has a revision number that increments with changes
• Conflict Detection: Real-time detection of scheduling conflicts
• Operations Log: All mutations tracked for audit and replay

Get Itinerary

Get the full itinerary for a trip.

Endpoint: GET /api/v1/trips/{tripId}/itinerary

Response:

{
  "tripId": 1,
  "revision": 42,
  "events": [...],
  "conflicts": []
}

Get Itinerary Summary

Get a compact summary with conflicts.

Endpoint: GET /api/v1/trips/{tripId}/itinerary/summary

Get Itinerary Diff

Get changes since a specific revision.

Endpoint: GET /api/v1/trips/{tripId}/itinerary/diff?since_revision=40

Response:

{
  "fromRevision": 40,
  "toRevision": 42,
  "changes": [
    {"type": "added", "event": {...}},
    {"type": "updated", "event": {...}}
  ]
}

Apply Operation

Apply a timeline operation.

Endpoint: POST /api/v1/trips/{tripId}/ops

Operation Types

Example: Move Event

curl -X POST "https://travelmode2.replit.app/api/v1/trips/1/ops" \
  -H "Authorization: Bearer tm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "MOVE_EVENT",
    "eventId": 5,
    "newStartDateTime": "2024-06-16T14:00:00Z",
    "expectedRevision": 42
  }'

Response:

{
  "success": true,
  "newRevision": 43,
  "conflicts": []
}

Validation Modes

The timeline engine supports three validation modes:

Handling Revision Conflicts

If your expectedRevision doesn't match the current revision:

{
  "error": "Revision conflict",
  "currentRevision": 45,
  "expectedRevision": 42
}

Solution: Fetch the latest itinerary, merge changes, and retry.