REST API reference

The REST API is generated from the installed modules. There is no OpenAPI document yet; this page lists everything that exists. All bodies are JSON and all calls except login need a bearer token.

Authorization: Bearer obop_...
Content-Type: application/json

Endpoints ​

Administrators also manage people over REST (a signed-in administrator's session; an agent token gets 404, and proposes the same changes through the user_account commands instead):

Instances also serve the web app from /. The control plane serves its own endpoints under /api/platform/ (sign-up, sign-in, instances); they are used by the sign-up app and are not covered here. It also publishes GET /api/releases (the core releases an instance's Updates page reads) and three endpoints that only an instance's update token opens (/api/platform/update/status, start, rollback); the token can ask for a published version and nothing else.

On an instance, administrators update modules with POST /api/module/upgrade ({"id": ...}), /api/module/upgrade_all and /api/module/rollback, and the instance itself with POST /api/instance_update/check, status, start ({"version": ...}) and rollback. Agents only propose the changing ones (a 202 with a plan_id).

Command responses ​

Success: 200 with

{"denied": ["party.tax_id"], "value": { ... }}

denied lists the field names this caller may not see. Needs approval (for an agent): 202 with {"approval_required":true,"plan_id":"..."}.

Generated commands ​

Every model gets these. For model lead:

Create many records ​

POST /api/{model}/bulk_create creates up to 1,000 records in one call (an agent token needs the same scope as for create, and approval exactly where create would). Give rows or csv:

{
  "rows": [{ "title": "First" }, { "title": "Second", "stage": "new" }],
  "mode": "all_or_nothing",
  "dry_run": false,
  "idempotency_key": "import-2026-10-24"
}

Every row is checked exactly as create checks a record, and everything is written in one transaction. The answer:

{
  "value": {
    "ok": true,
    "dry_run": false,
    "mode": "all_or_nothing",
    "source": "rows",
    "total": 2,
    "created": 2,
    "failed": 0,
    "errors": [],
    "errors_truncated": false,
    "ids": ["01...", "01..."],
    "replayed": false
  }
}

ids follows the order of the rows (null for a row that was not created); with dry_run the count is valid and there are no ids; errors lists at most 100 problems as {row, line?, error}, line being the line of a CSV file. A person may start OBOP_BULK_PER_MINUTE calls a minute (default 12). Limits: no remapping of ids and no reference from one row to another row of the same call, no decimal or date-time kinds yet, no images or files.

Each workflow action is one more command: lead.qualify, invoice.post. Input is {"id"}, plus any required fields it needs.

Filters, order and paging ​

{
  "filter": [
    { "field": "stage", "op": "in", "value": ["new", "qualified"] },
    { "field": "expected_revenue_minor", "op": "gte", "value": 100000 }
  ],
  "order": [{ "field": "expected_revenue_minor", "dir": "desc" }, { "field": "title" }],
  "limit": 50,
  "offset": 100
}

• Conditions are combined with AND; at most 50.
• Operators: eq, ne, contains (case-insensitive substring, text only), in (up to 1000 values), gt, gte, lt, lte (not for bool or ref), is_null. ne also matches records where the field is empty; other operators never match an empty value.
• order: up to 5 keys, dir asc (default) or desc; empty values sort last.
• limit 1 to 5000 (default: no limit), offset 0 or more.
• id can be used as a field. Unknown keys, operators or malformed values are 400.
• Filtering and sorting only work on fields the caller can read in clear. Other fields fail with unknown field <model>.<field>.

Field values ​

Status codes ​

MCP ​

The same commands are also exposed as MCP tools at POST /mcp (Streamable HTTP, protocol revisions 2025-11-25, 2025-06-18 and 2025-03-26), with the same bearer token, permissions, masking and approvals. A command lead.search is the tool lead__search; its input is the REST body, described by a JSON Schema generated from the model. An approval-required step is a normal result with "status": "approval_required" and a plan_id instead of HTTP 202; a refused input is a tool result with isError: true instead of HTTP 400; a hidden or unknown tool is a JSON-RPC error instead of 404. The OpenAPI document advertises the endpoint in x-mcp, and GET /api/meta in a Link header (rel="mcp"). Setup, limits, discovery documents and client configuration: Connect over MCP.

Versioning ​

There is no version header or deprecation policy yet. The product plan calls for a dated version header; until it exists, treat the API as unstable during the beta and check the changelog.

See Use the REST API for worked examples and the module manifest reference for how fields and actions are declared.