> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Every endpoint, schema, and example for the MarketBox public API.

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](https://docs.gomarketbox.com/concepts/what-the-api-doesnt-do.md) for what to use
instead of the common missing ones.

## Base URL

The MarketBox API is served from:

```
https://apiv2.gomarketbox.com
```

Every example in these docs reads it from `MARKETBOX_API_URL`:

```bash theme={null}
export MARKETBOX_API_URL="https://apiv2.gomarketbox.com"
export MARKETBOX_API_KEY="your-key-here"
```

> [!NOTE]
>
> This is the production API. A key acts on the real data of its project. See
> [Test keys and sandbox](https://docs.gomarketbox.com/concepts/authentication.md#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](https://docs.gomarketbox.com/concepts/authentication.md) and
[End-user authentication](https://docs.gomarketbox.com/concepts/end-user-authentication.md) for the full
model.

```http theme={null}
x-api-key: $MARKETBOX_API_KEY
```

There is one kind of key: no test keys and no sandbox. See
[Test keys and sandbox](https://docs.gomarketbox.com/concepts/authentication.md#test-keys-and-sandbox).

## Conventions

The same shapes show up everywhere:

* **List responses** wrap items in `{ data: [...], nextCursor }`. See
  [Pagination](https://docs.gomarketbox.com/concepts/pagination.md).
* **Single-item responses** wrap the item in `{ data: {...} }`.
* **Errors** are returned with a shared envelope. See
  [Errors](https://docs.gomarketbox.com/concepts/errors.md).
* **Times** are ISO 8601 strings in UTC, paired with an IANA timezone
  identifier on resources that have a client-facing local time.
  See [Timezones](https://docs.gomarketbox.com/concepts/timezones.md).
* **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:

> [card] [Bookings](https://docs.gomarketbox.com/resources/bookings.md)
>
> Scheduling primitive. Includes participants and notes.

> [card] [Orders](https://docs.gomarketbox.com/resources/orders.md)
>
> Commerce primitive. Includes items.

> [card] [Offerings](https://docs.gomarketbox.com/concepts/booking-engine-model.md)
>
> Catalog of bookable / orderable items — services, offerings, and the
> packages built from them.

> [card] [Holds](https://docs.gomarketbox.com/guides/hold-slots-for-checkout.md)
>
> Claim a supplier's time during checkout — a single session or a whole
> package slate — then convert the hold into bookings.

> [card] [Suppliers](https://docs.gomarketbox.com/resources/suppliers.md)
>
> Suppliers in a project, enriched with services and skills — listed,
> read and managed with the API key.

> [card] [Supplier plane](https://docs.gomarketbox.com/guides/build-a-supplier-portal.md)
>
> A signed-in supplier's own profile, bookings, hours, travel zones and
> insights, under `/suppliers/me`.

> [card] [Clients](https://docs.gomarketbox.com/guides/booking-flow-auth.md)
>
> A signed-in client's onboarding, profile, addresses and credits, under
> `/clients/me`.

> [card] [Locations and skills](https://docs.gomarketbox.com/resources/locations.md)
>
> The project's venues, travel-zone areas and supplier skills.

> [card] [Events](https://docs.gomarketbox.com/guides/report-site-events.md)
>
> 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:

```bash theme={null}
curl "$MARKETBOX_API_URL/v1/openapi.json"
```

The same document is bundled with this site and can be fetched at
[`/api-reference/openapi.json`](https://docs.gomarketbox.com/api-reference/openapi.json).

> [!TIP]
>
> The spec is OpenAPI 3.0. Tools like
> [openapi-typescript](https://github.com/drwpow/openapi-typescript),
> [openapi-generator](https://openapi-generator.tech/), and
> [orval](https://orval.dev/) all consume it directly.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.