Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.travelbase.ai/llms.txt

Use this file to discover all available pages before exploring further.

ā€‹
Overview

Travelbase is strongly consistent for single-resource operations and eventually consistent for derived data such as aggregates, search indexes, and usage metrics. Understanding this distinction will save you from writing unnecessary polling logic ā€” and from missing the cases where it actually matters.

Strong Consistency

Any resource you create or update is immediately readable by its ID on the very next request ā€” on any server, in any region.

Eventual Consistency

Aggregates, list filters, search indexes, and usage counters may lag by up to a few seconds after a write before reflecting the latest state.

ā€‹
What Is Consistent When

OperationConsistencyTypical Lag
GET /v1/bookings/:id after a create or updateStrongImmediate
GET /v1/customers/:id after a create or updateStrongImmediate
List endpoints (GET /v1/bookings)EventualUp to 5s
Search & filter queriesEventualUp to 5s
Usage metrics & countersEventualUp to 30s
Webhook delivery after an eventEventualUp to 10s
After a write, always redirect to or reference the resource by ID rather than reloading a list. The list may not yet include the new record ā€” the individual resource always will.

ā€‹
Idempotency

All mutating requests (POST, PATCH, DELETE) accept an Idempotency-Key header. Sending the same key twice within 24 hours returns the original response without creating a duplicate or triggering a second side-effect. 
curl -X POST "https://api.travelbase.ai/v1/bookings" \
  -H "Authorization: Bearer tb_live_xxxx" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
Always use idempotency keys for any request that moves money or creates a booking. A network timeout does not mean the request failed ā€” retrying without a key can result in duplicate bookings.

ā€‹
Conflicts

When two requests attempt to update the same resource simultaneously, Travelbase uses optimistic concurrency control. Every mutable resource exposes a version field. Pass it on updates ā€” if the version has moved on since you read the record, the request is rejected. 
{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "detail": "Resource version mismatch. Re-fetch the resource and retry."
  }
}
The correct response to a 409 Conflict is always: re-fetch ā†’ apply changes ā†’ retry.
The version field increments by 1 on every successful mutation. You can use this to detect whether a record changed between two reads without comparing all of its fields.