Operations
Last verified: 2026-06-20 (Task #390 — User APIs documentation).
Timeline mutations go through a single endpoint that applies one atomic, revision-tracked operation at a time. This requires a mutating role (owner / planner / editor).
POST /v1/trips/{tripId}/ops
Compare-and-set with base_revision
Every mutation must carry the base_revision you last observed (from the
itinerary read or a previous op result). The server only applies the
operation if the trip is still at that revision; otherwise it rejects with
409 and a STALE_REVISION code. This makes concurrent edits safe: read,
mutate, and on conflict re-read and retry.
Request
curl -s -X POST "https://api.travelmode.ai/v1/trips/42/ops" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"base_revision": 7,
"type": "move_event",
"payload": { "event_id": 901, "date": "2026-07-02", "time": "20:00" }
}'
| Field | Type | Notes |
|---|---|---|
base_revision | integer | The revision you last saw. Required. |
type | string | Operation type, e.g. add_event, move_event, update_event, remove_event, reorder. The accepted set is enforced by the timeline engine. |
payload | object | Operation-specific fields. Shape depends on type. |
Success
{
"success": true,
"trip_id": 42,
"new_revision": 8,
"operation": "move_event",
"result": { "affected_event_ids": [901] }
}
Use new_revision as the base_revision for your next operation.
Conflicts (409)
{
"error": "Revision conflict",
"code": "STALE_REVISION",
"current_revision": 9,
"base_revision": 7
}
On STALE_REVISION, re-read the itinerary (or call the
diff endpoint with your old revision),
re-apply your change against the new state, and retry. A 409 can also
indicate the operation failed validation against the current timeline; the
error message describes why.
Other statuses
400 for a malformed body, 401/403 for auth/role failures, 404 for
an unknown trip. See errors.md.