Latest features: the HTTP API

Version

3.x

Updated

25 Aug 2026

View markdown

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

---

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
• How a request becomes a record, from the inside

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 and the 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
• The response envelope every surface answers with

Tokens with scopes, and a format built to be caught

Bearer tokens (RFC 6750), minted from the admin screen 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 — 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
• Admin Guide: 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
• Type generation — the single pass that produces schemas and PHP record classes together

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
• The four ways in — 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 could be built as just another client of it.

• The runtime API
• The headless configurator, normatively
• How the storefront's own JavaScript talks to the server

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

---

Next: the CLI · the MCP server · back to Latest features