Trips
List, fetch, create, and partially update trips in your tenant's catalog.
A trip is an itinerary — a multi-day plan with days, segments, stops, and pricing. Trips become bookable on the storefront once published.
| Method | Path | Scope |
|---|---|---|
| GET | /api/v1/trips | trips:read |
| POST | /api/v1/trips | trips:write |
| GET | /api/v1/trips/{id} | trips:read |
| PATCH | /api/v1/trips/{id} | trips:write |
The Trip object:
| Field | Type | Notes |
|---|---|---|
id | string | Opaque, cuid-style. |
tripNumber | string | Per-tenant human-friendly reference, e.g. "TR-2026-00042". Not a counter — never parse it as a number. |
title | string | 1–200 chars. |
status | enum | draft, active, sent, accepted, rejected, archived. |
tripMode | enum | tailor_made or template. |
dateMode | enum | departure_based or range_based. |
publicSlug | string | null | Set when the trip is published to the storefront. |
publishedAt | ISO 8601 | null | When the trip became publicly bookable. |
unpublishedAt | ISO 8601 | null | When publishing was revoked. |
startDate | ISO 8601 | null | Start of the trip window. |
endDate | ISO 8601 | null | End of the trip window. |
daysCount | integer | Trip duration in days. |
startCityId | string | Library city id for departure. |
endCityId | string | Library city id for return. |
transportMode | enum | own_fleet or outsourced. |
pricingDisplayMode | enum | per_person, per_couple, total_group. |
shortDescription | string | null | ≤ 500 chars. |
longDescription | string | null | ≤ 8000 chars. |
clientId | string | null | When the trip is built for a specific CRM contact. |
notes | string | null | Operator notes — never shown to travellers. |
createdAt | ISO 8601 | |
updatedAt | ISO 8601 |
GET /api/v1/trips
List trips visible to the tenant. Cursor-paginated, default order by id ascending.
Required scope — trips:read
Query parameters
| Name | Type | Default | Notes |
|---|---|---|---|
limit | integer | 50 | Max 100. |
cursor | string | — | From a previous response's meta.cursor. |
status | string | — | Filter to one of the trip statuses. Unknown values are ignored. |
publishedAt[gte] | ISO 8601 | — | Only trips published at or after this time. |
Response 200 — application/json
{
"data": [ /* Trip[] */ ],
"meta": { "cursor": "trp_a1b2c3" | null, "hasMore": true | false }
}Errors — 401 unauthorized, 403 (scope-required, or plan-required when the plan has no API access), 429 rate-limited.
/api/v1/tripsTry itRequests are proxied through this docs site so CORS doesn't block the call. Use a sandbox token if you don't want test calls hitting live data.
Query parameters
limitcursorstatuspublishedAt[gte]GET /api/v1/tripsPOST /api/v1/trips
Create a new trip. The token's creator becomes the audit "actor" for the new row.
Required scope — trips:write
Request body — application/json
| Field | Type | Required | Notes |
|---|---|---|---|
title | string | yes | 1–200 chars. |
startDate | string (YYYY-MM-DD) | yes | |
endDate | string (YYYY-MM-DD) | no | Must be ≥ startDate. |
daysCount | integer | yes | 1–365. |
startCityId | string | yes | Library city id. |
endCityId | string | yes | Library city id. |
transportMode | enum | no | own_fleet (default) or outsourced. |
pricingDisplayMode | enum | no | per_person (default), per_couple, total_group. |
notes | string | no | ≤ 2000 chars. |
shortDescription | string | no | ≤ 500 chars. |
longDescription | string | no | ≤ 8000 chars. |
clientId | string | no | Must belong to your tenant. |
Response 201 — application/json
{ "data": /* Trip */ }Errors — 401 unauthorized; 403 — scope-required, plan-required, or forbidden when the plan's trip quota is full; 422 validation-failed (schema failures, and clientId does not belong to this tenant); 429 rate-limited.
/api/v1/tripsTry itCreates a new trip in your tenant. Returns 201 with the Trip object.
Requests are proxied through this docs site so CORS doesn't block the call. Use a sandbox token if you don't want test calls hitting live data.
POST /api/v1/tripsGET /api/v1/trips/{id}
Fetch a single trip by id.
Required scope — trips:read
Path parameters
| Name | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Trip id. |
Response 200 — application/json
{ "data": /* Trip */ }Errors — 401, 403 scope-required, 404 not-found.
/api/v1/trips/{id}Try itRequests are proxied through this docs site so CORS doesn't block the call. Use a sandbox token if you don't want test calls hitting live data.
Path parameters
idrequiredGET /api/v1/trips/{id}PATCH /api/v1/trips/{id}
Partial update. Fields omitted from the body are left unchanged.
Required scope — trips:write
Path parameters
| Name | Type | Required | Notes |
|---|---|---|---|
id | string | yes | Trip id. |
Request body — application/json (all fields optional)
| Field | Type | Notes |
|---|---|---|
title | string | 1–200 chars. |
startDate | string (YYYY-MM-DD) | |
endDate | string (YYYY-MM-DD) | null | Null to clear. Must be ≥ startDate. |
daysCount | integer | 1–365. |
notes | string | null | ≤ 2000 chars. |
shortDescription | string | null | ≤ 500 chars. |
longDescription | string | null | ≤ 8000 chars. |
clientId | string | null | Must belong to your tenant, or null to detach. |
Response 200 — application/json
{ "data": /* Trip */ }Errors — 401, 403 scope-required, 404 not-found, 422 validation-failed, 429 rate-limited.
/api/v1/trips/{id}Try itRequests are proxied through this docs site so CORS doesn't block the call. Use a sandbox token if you don't want test calls hitting live data.
Path parameters
idrequiredPATCH /api/v1/trips/{id}