Tripistic API Beta
openapi.json Dashboard

Public API · v1.0.0

Build on Tripistic

Read tours and availability, then create and track bookings for your workspace — the same operations layer the Tripistic dashboard runs on. JSON in, JSON out, every response enveloped and request-traced.

https://api.tripistic.com/v1

Quickstart

List the published tours of the workspace your API key belongs to. Every authenticated call is one bearer header away.

curl -sS \
  -H "Authorization: Bearer tk_live_YOUR_KEY" \
  "https://api.tripistic.com/v1/tours?limit=20"

Authentication

Workspace API keys, created in the Tripistic dashboard, act on behalf of exactly one workspace.

Bearer API keys

Send Authorization: Bearer <key> on every call except /health and /version. Keys carry scopes (for example tours:read, bookings:write); a valid key without the right scope gets the same 403 FORBIDDEN as any other denial — the API never says which check failed.

Idempotent booking creation

POST /bookings accepts an optional Idempotency-Key header. Retrying with the same key returns the original booking instead of creating a duplicate — safe for flaky networks and checkout retries.

Endpoints

All paths are relative to https://api.tripistic.com/v1. System endpoints are open; everything else requires a workspace API key.

System

GET
/health
Liveness of the API worker. No authentication.
GET
/version
Current public API contract version.

Catalog

GET
/tours
Public, active tours of the authenticated workspace, newest first.
limit 1–999cursor opaque pagination token
GET
/tours/{tourId}
One published tour with pricing in integer minor units (cents).
tourId path · tour id
GET
/availability
Departure availability with spots left, optionally bounded by time.
tour_id filter by tourfrom ISO 8601 start ≥to ISO 8601 start ≤limit 1–999cursor pagination token
GET
/departures
Departure schedule rows.
tour_id filter by tourstatus filter by statusfrom ISO 8601to ISO 8601limit 1–999cursor pagination token

Bookings & operations

GET
/bookings
Bookings for the workspace.
status filter by statustour_id filter by tourfrom ISO 8601to ISO 8601limit 1–999cursor pagination token
POST
/bookings
Create a booking. Send Idempotency-Key to make retries safe.
body tour, departure, guests, contact
GET
/bookings/{bookingId}
One booking with its current state.
bookingId path · booking id
GET
/customers
Traveler records for the workspace.
search name or emaillimit 1–999cursor pagination token
GET
/guides
Team members who can be assigned to departures.
search name or emaillimit 1–999cursor pagination token
GET
/vehicles
Fleet vehicles available for transfers and logistics.
limit 1–999cursor pagination token

Response envelopes

Successes and errors never share a shape. Every envelope carries meta.requestId (errors inline it) — quote it when reporting a problem.

Success

{
  "data": {
    "tours": [ { "id": "tour_9f2a", "title": "Coastal Cycling & Vineyard Ride", "priceMinor": 11000, "priceCurrency": "USD" } ]
  },
  "pagination": { "nextCursor": null, "hasMore": false },
  "meta": { "requestId": "req_219dbebd-27e7-4997-bb0c-04a98c7ee24e" }
}

Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request query is not valid.",
    "details": [ { "field": "limit", "issue": "unrecognized_keys" } ],
    "requestId": "req_219dbebd-27e7-4997-bb0c-04a98c7ee24e"
  }
}

Error codes

Stable machine-readable codes on every JSON error. Retry only on 429 and 5xx, and back off.

CodeHTTPMeaning
VALIDATION_ERROR400Query or body failed schema validation — see details[].
UNAUTHORIZED401Invalid or missing API key.
FORBIDDEN403The key is valid but not allowed to perform this action.
NOT_FOUND404The requested resource does not exist in this workspace.
METHOD_NOT_ALLOWED405The endpoint exists but not for this HTTP method.
RATE_LIMITED429Too many requests — slow down and retry.
UPSTREAM_ERROR502The API could not process this request.
UPSTREAM_UNAVAILABLE503Temporary unavailability — retry shortly.
INTERNAL_ERROR500Unexpected failure on our side.