Skip to main content
The MarketBox API is a RESTful, JSON-over-HTTPS surface. This reference section is auto-generated from the OpenAPI specification that the API serves at /v1/openapi.json — every endpoint listed here is a direct projection of what the running service accepts and returns. A route that isn’t listed doesn’t exist. See What the API doesn’t do for what to use instead of the common missing ones.

Base URL

The MarketBox API is served from:
Every example in these docs reads it from MARKETBOX_API_URL:
This is the production API. A key acts on the real data of its project. See Test keys and sandbox.

Authentication

Every endpoint under /v1 requires an x-api-key header, with two exceptions: the browser beacon for site events takes a publishable key in its query string, and GET /v1/openapi.json needs no auth. The playground accepts your key in the authorization slot. The end-user routes — the client’s /clients/me and the supplier’s /suppliers/me — also take the signed-in person’s access token as Authorization: Bearer <token>. See Authentication and End-user authentication for the full model.
There is one kind of key: no test keys and no sandbox. See Test keys and sandbox.

Conventions

The same shapes show up everywhere:
  • List responses wrap items in { data: [...], nextCursor }. See Pagination.
  • Single-item responses wrap the item in { data: {...} }.
  • Errors are returned with a shared envelope. See Errors.
  • Times are ISO 8601 strings in UTC, paired with an IANA timezone identifier on resources that have a client-facing local time. See Timezones.
  • Money is { amount: integer, currency: 3-letter ISO } — amounts are integers in the currency’s minor unit (cents, pence, etc.).

Tags

Endpoints are grouped by tag in the sidebar:

Bookings

Scheduling primitive. Includes participants and notes.

Orders

Commerce primitive. Includes items.

Offerings

Catalog of bookable / orderable items — services, offerings, and the packages built from them.

Holds

Claim a supplier’s time during checkout — a single session or a whole package slate — then convert the hold into bookings.

Suppliers

Suppliers in a project, enriched with services and skills — listed, read and managed with the API key.

Supplier plane

A signed-in supplier’s own profile, bookings, hours, travel zones and insights, under /suppliers/me.

Clients

A signed-in client’s onboarding, profile, addresses and credits, under /clients/me.

Locations and skills

The project’s venues, travel-zone areas and supplier skills.

Events

Report which suppliers your site showed, and what clients saw and opened.

The raw spec

If you’d rather work directly from the OpenAPI document — generating a client, importing into Postman, or writing your own playground — pull it straight from the running service:
The same document is bundled with this site and can be fetched at /api-reference/openapi.json.
The spec is OpenAPI 3.0. Tools like openapi-typescript, openapi-generator, and orval all consume it directly.