Skip to main content
This guide is about calling the API of your Voyant workspace from your own website, mobile app, or backend. Your workspace exposes the catalog browse, pricing, and booking flows under a public surface, and you drive them from outside.

Mental model

The single most important thing to get right is which surface you are calling. Your workspace exposes two of them: The base URL is your workspace address plus /api, for example https://your-workspace.onvoyant.com/api, not api.voyant.travel. {workspace} is the first part of your admin address. Without /api, the address serves the admin app, not the API. The hosted Cloud, Connect, and Data APIs in the SDKs tab are the opposite case: they use api.voyant.travel with a bearer key. For which public routes need which key, see Public API. That split maps to two clients:

@voyant-travel/storefront-sdk

The public client. Safe to ship to a browser bundle with a publishable key. Carries no secret. Talks to /v1/public/*.

@voyant-travel/admin-client

The admin client. Server only. Carries a voy_ API key. Talks to /v1/admin/*. Never embed it in a client bundle.
If your website needs admin data, your own backend calls the admin client and proxies the result. The API key stays on your server, per Authentication.

Browse and book from a TypeScript app

Install the public SDK and point it at your workspace. Pass a key: only product reads work without one. In browser code, use a publishable key and list your site under Allowed websites on the key. On a server, use a secret key. This package is a final release, so check that it covers the routes you need. See SDKs overview.
The client groups operations into four facades: storefront (catalog reads), booking (the raw session lifecycle), bookingEngine (the recommended, flow-oriented wrapper), and checkout (payment collection).
1

Browse the catalog

Read settings, then departures, availability, and pricing for a product. All of these are plain reads on the storefront facade.
Marketing-style offers are also available with voyant.storefront.listProductOffers(productId) and voyant.storefront.getOfferBySlug(slug).
2

Reserve a booking session

Prefer the bookingEngine facade. reserve opens a public booking session and returns a canonical snapshot whose engine.state you can gate UI on.
When you already have a selected departure and quote and want the combined payload in one call (session, availability, repricing, payment plan, allocation, and the checkout capability attached at session.checkoutCapability), use voyant.booking.bootstrapSession(...) instead. An async bootstrap returns 428 if you do not supply an idempotency key; see the next step.
3

Follow the server's next action

Do not derive engine state on the client. The server publishes what to do next, and a host renders it rather than inventing it.Recoverable errors come back in an envelope carrying code, message, recoverable, and nextAction. nextAction is drawn from a closed set (bookingEngineNextActions):
Map each value to a recovery affordance in your UI. Because the set is closed and server-owned, what you render and what the server enforces stay one derivation instead of two that drift.
4

Collect travelers and reprice

Update travelers and reprice as the customer fills the form. Pass an idempotency key on writes so retries do not double-apply.
Every write method accepts a trailing StorefrontRequestOptions with headers and idempotencyKey. The key is sent as the Idempotency-Key header.
5

Take payment and confirm

Drive payment through the engine, gating each step on state, then confirm.
Re-read the snapshot any time with voyant.bookingEngine.getSnapshot(sessionId). Lower-level payment helpers (previewPayment, bootstrapPayment) and the checkout facade (previewCollection, initiateCollection, bootstrapCollection) are there when you need finer control.

Errors

Failed calls throw VoyantStorefrontApiError with status, body, and a normalizedError (the parsed { code, message, details } envelope). Branch on normalizedError.code, not on the message string.
There is no checkout login. The checkout surface is protected by a short-lived, server-issued checkout-capability cookie attached to the session, not a user account.

Build a React website

For a React site, layer the hooks packages on top of the same public contract. @voyant-travel/storefront-react covers the storefront and booking flows; @voyant-travel/catalog-react adds catalog search and a booking-engine hook family. Both are final releases.
Both providers re-export one shared context, so you wrap your app once with a provider and a TanStack Query QueryClientProvider (v5 is a peer dependency).
The provider takes { baseUrl, fetcher?, children }. Inside the tree, read with hooks:
For dynamic catalog browse and a hook-based booking flow, add @voyant-travel/catalog-react. It exposes VoyantCatalogProvider (same { baseUrl, fetcher } context, so it composes with the storefront provider), discovery hooks useCatalogSearch, usePackageSearch, usePackageDetail, useCatalogSlots, and, under @voyant-travel/catalog-react/booking-engine, the booking hooks useBookingDraft, useBookingQuote, and useBookingHold. These hooks can target /v1/admin or /v1/public depending on the baseUrl and the route they call.

Mobile or any other language: raw REST

The SDK is a convenience, not a requirement. Everything is plain HTTP and JSON under https://{workspace}.onvoyant.com/api/v1/public/*, so a native mobile app or a backend in any language can call it directly.
This product read needs no key. For routes that depend on a sales channel, send a secret key from your backend in the x-api-key header. Keep that key off devices, so route native apps through your own server for those calls. Routes. Public routes are organized by business capability, not by the frontend that calls them: /v1/public/bookings, /v1/public/products, /v1/public/pricing, and so on. The full set is documented in the Storefront API reference in the Platform navigation, with your workspace as the server URL. Success envelope. Reads return { "data": ... }. List endpoints add pagination alongside data.
Error envelope. Errors return one shape on every route. Branch on code, not on error.
requestId is also returned in the X-Request-Id response header on success and failure alike. Keep it in logs and support requests. Idempotency. Writes accept an Idempotency-Key request header so a retry does not create a duplicate. Async bootstrap endpoints reject a write with 428 if the key is missing.
CORS. A browser can call the API only from a listed site. Add your sites under Allowed websites on a public key, in the admin under Settings, then API. List exact origins or a single-label wildcard such as https://*.example.com. A bare * is rejected. Native mobile apps do not run a browser CORS preflight, so this list does not affect them. Caching. GET /v1/public/* responses that the route marks Cache-Control: public, s-maxage=... and that carry no Set-Cookie are served from a shared cache. To force a fresh read, send Cache-Control: no-cache on your request.

Read admin data from your own server

When you need data only the admin surface exposes (full bookings, finance, staff operations), call it from your backend with @voyant-travel/admin-client and a voy_ API key. This client is server only. Never ship it or the key to a browser or mobile bundle; a public site reaches admin data by proxying through its own backend.
This package is a final release. For an endpoint it does not cover, call the API over HTTP with the same key.
Non-2xx responses throw AdminApiError. Mint and scope voy_ keys per Authentication, and grant each key only the scopes it uses.

A working example

For examples that consume these public contracts, see the @voyant-travel/storefront-sdk documentation.

Next steps

Public API

The customer-facing surface, its packages, and where checkout fits.

API routes

The admin/public split, the error envelope, and the route conventions.

SDKs overview

The hosted Cloud, Connect, and Data clients and their shared shape.

SDK authentication

How voy_ API keys, scopes, and server-only token rules work.