Getting started
Mint a token, fire your first call from the Explorer, parse the response.
You should have access to the Tourical operator dashboard.
1. Create an API token
In the operator dashboard, go to Settings → Developer access and, under API tokens, click Create token. (No account yet? Create one — API access needs a plan that includes it.)
- Give it a descriptive name (e.g.
Zapier — bookings sync). - Pick the scopes the integration needs. Smallest possible set; you can always rotate to a wider one later.
- Optionally set an expiry. Rotation is cheap; leaks are expensive.
You'll see the plaintext token exactly once. It looks like:
tk_live_a3f9bc4n7vqzr2k8mp5tx9w1Store it immediately in your secrets manager. The dashboard only ever shows the prefix afterwards. We store a SHA-256 hash; we cannot recover the plaintext for you.
2. Fire your first call
Paste the token below. It stays in your browser: by default in sessionStorage, so it lives in this tab only and is gone when you close it. Every Explorer on every page picks it up while the tab is open. Tick Remember this token on this device to move it to localStorage instead — convenient across tabs, and readable by any script on this origin.
/api/v1/tripsTry itLists the trips visible to your token. The cheapest call you can make.
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.
Query parameters
limitGET /api/v1/trips3. Read the response
Every list endpoint returns a cursor envelope:
| Field | Notes |
|---|---|
data | Array of resource objects. |
meta.cursor | Pass back as ?cursor=… to get the next page. null means you've reached the end. |
meta.hasMore | true if a next page exists. |
Every response — success or failure — also carries headers worth observing:
| Header | Notes |
|---|---|
X-RateLimit-Limit | Sustained-bucket cap (600/min). |
X-RateLimit-Remaining | Calls remaining in the current window. |
X-RateLimit-Reset | Seconds until the window resets. |
Tourical-Request-Id | Echo back to us in any bug report. |
4. Handle errors
Every non-2xx response is a problem+json document. Branch on status and on type — never on the shape of data. type is the stable machine identifier; title and detail are prose and can be reworded:
{
"type": "https://developers.tourical.com/errors/scope-required",
"title": "Missing required scope",
"status": 403,
"detail": "This endpoint requires the `trips:write` scope.",
"required_scope": "trips:write"
}What's next
- Authentication — token format, scopes, rotation, leak response.
- Endpoint reference — every resource, every method.
- API Explorer — send arbitrary requests.
- Webhooks — react to events instead of polling.
- Rate limits — stay inside the budget at high traffic.