ReferenceAPI Reference

OpenAPI

The machine-readable OpenAPI 3.1 specification for the Tripistic REST API, and how to use it for clients, mocks, and contract tests.

July 1, 20262 min read

Status: beta — the callable Worker surface is live. The current contract covers health, version, tours, availability, bookings, customers, departures, guides and vehicles on api.tripistic.com. The full workspace design remains a forward-looking contract and is labelled as such.

The deployed beta contract is generated from the Cloudflare Worker route schemas. Use it for the callable surface; do not infer that every planned workspace route is available.

The document

Live /v1/openapi.json — the beta Worker contract.

The older /openapi.json file remains the design contract for the wider workspace API and is intentionally marked planned.

curl https://api.tripistic.com/v1/openapi.json -o tripistic-openapi.json

The info.version field tracks the platform version. Pin a downloaded copy in your repository so a specification change never silently alters your generated client — upgrade deliberately.

What it covers

Section	Contents
`servers`	Production base URL
`security`	Bearer token scheme
`paths`	Bookings, tours, availability, customers, and the public booking endpoints
`components.schemas`	Booking, Participant, Tour, Availability, Customer, Error, Pagination
`components.parameters`	`workspaceId`, `cursor`, `limit`, date filters
`components.responses`	Shared 400 / 401 / 403 / 404 / 409 / 429 responses

Generate a client

# TypeScript types
npx openapi-typescript https://api.tripistic.com/v1/openapi.json -o src/tripistic.d.ts

# Python
openapi-python-client generate --url https://api.tripistic.com/v1/openapi.json

# Go
oapi-codegen -package tripistic https://api.tripistic.com/v1/openapi.json > tripistic.go

More detail, plus a hand-rolled client, in SDKs & Clients.

Explore it interactively

Postman — Import → Link → paste the URL. You get a full collection with parameters and schemas. Add Authorization: Bearer {{apiKey}} as a collection header and store apiKey as an environment secret.

Insomnia — Create → Import From → URL.

Swagger UI / Redoc — point either at the document to browse it locally:

npx @redocly/cli preview-docs https://api.tripistic.com/v1/openapi.json

Mock server

Generate a mock from the specification to build against before writing integration code:

npx @stoplight/prism-cli mock https://api.tripistic.com/v1/openapi.json

Your client then talks to http://localhost:4010 with schema-valid responses. This is the fastest way to build a UI against the API without touching a real workspace.

Contract testing

Validate that your integration still matches the contract in CI:

# Lint the spec itself
npx @redocly/cli lint https://api.tripistic.com/v1/openapi.json

# Validate recorded responses against the schema
npx @stoplight/prism-cli proxy https://api.tripistic.com/v1/openapi.json https://api.tripistic.com/v1 \
  --errors

Running the proxy in --errors mode during integration tests surfaces any response that drifts from the schema.

Compatibility rules

The specification evolves under the same rules as the API:

Additive changes — new paths, new optional fields, new enum values — ship without a version bump. Generated clients must tolerate unknown fields.
Breaking changes get a new major version and at least 90 days' notice, published in the Changelog and Release Notes.
Deprecated operations are marked deprecated: true before removal.

Reporting a discrepancy

If the specification and the API disagree, that is a bug worth reporting. Send the endpoint, the request, the expected schema, and the actual response to [email protected].

REST API · SDKs & Clients · Authentication · Examples