Skip to main content

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; 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; 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; 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); the code is a short machine-readable tag and message is human-readable.