REST API

The API is versioned under /api/v1. JSON goes in and JSON comes out, and every route is scoped to a workspace, so a token only ever acts inside the workspaces it is allowed into.

There is a shorter overview at API. This page is the detail.

Base paths

Two shapes cover almost everything:

• Platform routes hang off a workspace slug: /api/v1/orgs/<workspace>/.... Field definitions, wires (bindings), views, search, tags, and files live here.
• Module routes hang off a module inside a workspace: /api/v1/orgs/<workspace>/modules/<module>/.... A module owns its own records, so listing parts, creating a machine, or running a module action all go through its subtree.

A handful of routes sit outside the workspace tree because their URL carries no slug: the inbound webhook receivers, for instance, resolve the workspace from a token in the path. Those are covered in Events and webhooks.

Auth

Send a bearer token:

Authorization: Bearer cbt_your_token_here

A browser session uses a short-lived JWT, while a script or service uses a long-lived API token, which starts with cbt_. See API tokens for minting and scoping them.

Records

Each module exposes its record kinds under its subtree. A record kind has an id like inventory:part or projects:task (the module name, a colon, the kind). The usual operations exist: list, get one, create, update, delete. A resolved record comes back with its id, a title, and a fields map, and custom-field values live inside that map. The data model section covers kinds, fields, and how records link.

Actions

Beyond plain create and update, a module registers actions: named operations like "use one" on a part or "mark task done." An action declares which record kinds it applies to, so the app can offer only the ones that make sense on a given record. Actions are also what wires invoke, which is why one action can be both a button in the UI and the target of an automation.

The OpenAPI spec

Cobblr describes itself with an OpenAPI 3.1 document, generated from the live module registry in each workspace, so it reflects the kinds and fields that workspace actually has:

GET /api/v1/orgs/<workspace>/modules/core-openapi/openapi.json

Point Swagger UI, Insomnia, or a client generator at that URL rather than working from a hand-kept endpoint list. There's also a built-in viewer at Configuration → OpenAPI that lists the spec's paths and schemas with copy and download buttons, but the JSON stays the source of truth.

Errors

Errors come back as JSON with a stable shape:

{ "error": { "code": "not_found", "message": "token not found" } }

The HTTP status carries the category (401 for a bad token, 404 for a missing record, and so on), while the code is a short machine-readable tag and message is human-readable.