# Latest features: the HTTP API

> What's new for integrators — a token-authenticated REST surface over the whole catalog, described by a generated OpenAPI 3.1 document, plus a runtime API for configuring a product headlessly.

Source: CBX documentation, version 3.x (released). Canonical page: https://docs.configbox.at/docs/features/latest/http-api. Last updated 2026-08-25.

---
**CBX became something you can program against.** Not a webhook or two — a REST surface over the whole
catalog, authenticated with scoped bearer tokens, described by an OpenAPI 3.1 document that is built
from the same property definitions the admin forms are built from, plus a second, session-based surface
for driving a configuration to a cart without a browser.

← [Back to Latest features](https://docs.configbox.at/docs/features/latest/)

---

## The entity API

```
GET    /cb-api/v1/                          what this store exposes
GET    /cb-api/v1/{entity}                  a page of records
POST   /cb-api/v1/{entity}                  create                      -> 201
GET    /cb-api/v1/{entity}/{id}             one record
PATCH  /cb-api/v1/{entity}/{id}             change some fields          -> 200
DELETE /cb-api/v1/{entity}/{id}             delete                      -> 200
```

`{entity}` is any name the index lists — the same registry the type generator walks, so the entity list
and the shipped schemas cannot disagree. Each entity's model declares which operations make sense for
it, which is how one-row entities like the store record narrow to list/read/update rather than
pretending a second one could be created.

- [The entity API — endpoints, records, translations, coverage](https://docs.configbox.at/docs/technical/entity_api#2-the-endpoints)
- [How a request becomes a record, from the inside](https://docs.configbox.at/docs/technical/http_api)

## One pipeline under five surfaces

This is the part worth understanding before anything else. The admin UI, the storefront, the HTTP API,
the [MCP server](https://docs.configbox.at/docs/features/latest/mcp-server) and the [CLI](https://docs.configbox.at/docs/features/latest/cli) converge on **shared code, not merely shared
behaviour** — one entity registry, one store pipeline, one model. A record created over HTTP is
validated exactly like one saved from an admin form, and a rejection carries the wording an operator
would have seen.

- [The four ways in, and where they converge](https://docs.configbox.at/docs/technical/api_surfaces#1-the-four-surfaces)
- [The response envelope every surface answers with](https://docs.configbox.at/docs/technical/api_contract)

## Tokens with scopes, and a format built to be caught

Bearer tokens (RFC 6750), minted from the [admin screen](https://docs.configbox.at/docs/features/latest/admin-experience) or
`configbox:token:mint`. A scope is **`<area>:<level>`** — `catalog:write`, `orders:read`: seven areas
say *what* a token may touch, two levels say *how*. Write covers read inside an area, nothing carries
across areas, and permission to run PHP (`code:write`) is never part of any preset. Optional expiry,
revocation, and a last-used stamp so a token that has been dead weight for months is visible.

That vocabulary replaced a blunt `read` / `write` / `admin` triple, which could only say how much a
caller could do and never what it could reach — so an integration that needed to read orders had to
be trusted with the catalog too.

Two details that matter operationally: only the SHA-256 is stored, so a token is shown once and
nothing can show it again; and the token carries a `cbx_` prefix specifically **so a secret scanner
can recognise a leaked one** — a bare random string looks like nothing to a scanner.

- [API tokens and scopes](https://docs.configbox.at/docs/technical/api_tokens_and_scopes) — the seven areas,
  the rules that govern them, the presets, and where tokens are minted
- [Authentication, expiry, and the stance on CORS and rate limiting](https://docs.configbox.at/docs/technical/entity_api#5-authentication)
- [Admin Guide: manage API tokens](https://docs.configbox.at/docs/admin-guide/settings/manage-api-tokens) ·
  `configbox:token:scopes` prints the whole vocabulary from the running code

## The description is generated, so it cannot lie

`GET /cb-api/v1/openapi.json` returns an **OpenAPI 3.1** document assembled per request, `$ref`-ing
the JSON Schemas the API itself serves. 3.1 rather than 3.0 because 3.1 uses JSON Schema 2020-12
unchanged — which is exactly what CBX ships — so nothing is lossily converted on the way out.

Three schemas per entity, and the distinction is deliberate: `<Entity>Read` (a full record),
`<Entity>Write` (what a create or update may send), `<Entity>ListRow` (a listing row — the listing
columns only). `ListRow` is derived from the same method the admin list uses, so a collection read and
its description cannot drift.

The document endpoints are the **one deliberate exception** to the response envelope: an OpenAPI
document and a JSON Schema have their own root-level contracts, and their consumers are other people's
tools, which do not unwrap envelopes.

- [Discovery: why 3.1, why per-request, and why these two endpoints answer bare](https://docs.configbox.at/docs/technical/entity_api#6-discovery)
- [Type generation — the single pass that produces schemas and PHP record classes together](https://docs.configbox.at/docs/technical/type_generation)

## Take the description with you

`configbox:api:export` writes the same description to disk in three shapes: the **OpenAPI document**, a
**Postman collection**, and a **browsable HTML reference**. Useful when the people who need the API are
not the people who have a token for the live store.

- [`configbox:api:export`, and the `--live-site` caveat](https://docs.configbox.at/docs/technical/cli_commands#1-the-commands)
- [The four ways in](https://docs.configbox.at/docs/technical/api_surfaces#1-the-four-surfaces) — which also
  ships the same map as a diagram, `technical/com_configbox_api_wiring.html`, in the component itself

## The runtime API: a configuration without a browser

A different surface with different rules, and the one to reach for if you are building a client that
*configures* rather than *authors*. Fetch the configuration, set a selection, preview one without
committing it, ask why a question is unavailable, add the result to the cart — all with an HTTP client
and a cookie jar, no HTML parsing.

It is the same code the configurator page runs on, which is why the [chat advisor](https://docs.configbox.at/docs/features/latest/ai-assistant)
could be built as just another client of it.

- [The runtime API](https://docs.configbox.at/docs/technical/runtime_api)
- [The headless configurator, normatively](https://docs.configbox.at/docs/technical/api_contract)
- [How the storefront's own JavaScript talks to the server](https://docs.configbox.at/docs/technical/frontend_requests)

## Where the surface stops

The entity API's documentation includes a section titled *Coverage, honestly* — what is exposed, what
is not, and why. Worth reading before scoping an integration against it.

- [Coverage, honestly](https://docs.configbox.at/docs/technical/entity_api#8-coverage-honestly)

---

*Next: [the CLI](https://docs.configbox.at/docs/features/latest/cli) · [the MCP server](https://docs.configbox.at/docs/features/latest/mcp-server) ·
[back to Latest features](https://docs.configbox.at/docs/features/latest/)*