REST API

The REST API is what both SDKs and the MCP server are built on. It speaks JSON over HTTP and is versioned in the path.

All paths below start with /v1. The engine also serves GET /health, which returns { "ok": true, "version": "…" }.

Authentication

Send a Bearer token with every request:

curl https://api.useprimitives.com/v1/groups \
  -H "Authorization: Bearer $PRIMITIVES_API_KEY"

• Workspace API keys (pk_…, cloud), scoped to every group and every tool, can call every endpoint for your account.
• Scoped API keys (pk_…, cloud), limited to one group or to some tools, can reach only their group and the primitives in it, and only through endpoints their tool allowlist covers. A primitive in another group answers 404 not_found, so its existence isn't leaked. Endpoints marked account below reject them with 403 forbidden. Create and scope keys in the dashboard; see Auth & scoping.
• Locally, primitives dev needs no token on localhost. Started with --token <secret>, it requires that value as the Bearer token for account-level calls.

No endpoint returns a secret's value.

Errors

Every error returns a non-2xx status and the same JSON envelope:

{
  "error": {
    "code": "branch_conflict",
    "message": "Main database changed since branch 'try-migration' was created."
  }
}

Every response carries an X-Request-Id header. Include it when you contact support.

Rate limits

The cloud API limits each API key to about 20 requests per second, with bursts up to 60. Over the limit it answers 429 rate_limited with a Retry-After header in seconds. Both SDKs retry 429 with backoff. The local engine doesn't rate-limit. RateLimit-* headers are coming soon.

Usage and limits

On Primitives Cloud, usage is measured in operations. An operation is any call that touches a primitive's data or lifecycle through REST, the SDKs or MCP:

• Every route under /v1/primitives/{id}/…: database query, exec and batch, files, queues, memories, vaults (including fetch), keys, objects (including presign), and snapshots, fork, restore, pause, resume, export and stats (but not audit).
• Every MCP tools/call of a primitive tool. Each call in a JSON-RPC batch counts on its own.

These are not operations: creating a primitive (POST /v1/primitives or primitive_create), GET /v1/groups and the other group routes, reading the audit trail (GET /v1/audit and /v1/primitives/{id}/audit), listing primitives with GET /v1/primitives, the primitive_list MCP tool, API key management, MCP initialize and tools/list, and dashboard page loads. Queue messages aren't a separate limit; sending and receiving them are operations like any other.

On Starter, requests over a cap are refused, never billed. Once the workspace has used its 1M operations for the month, further operations get 429 plan_limit:

{
  "error": {
    "code": "plan_limit",
    "message": "This workspace used its 1M operations for this month on the Starter plan. Upgrade to Pro or wait until 2026-11-01."
  }
}

At 5 GB of storage, write operations get 429 plan_limit: database exec and batch, file writes, queue sends, remember, setting a secret, setting or incrementing keys, putting or copying objects (including uploads through a signed URL) and creating a primitive (creating one isn't an operation, but it adds storage). Reads and deletes keep working, so you can free up space. Unlike rate_limited, retrying with backoff won't help; upgrade or wait for the reset.

Pro is never cut off. Usage beyond the included operations and storage is billed as overage. Operation counters reset on the 1st of each month, UTC.

Pagination

Endpoints that page take limit (default 50, max 200) and cursor, and return:

{ "data": [], "next_cursor": null }

Pass next_cursor back as cursor for the next page. When it's null, there are no more pages. Key and object listings page the same way, with 100 entries by default and up to 1,000. Other list endpoints return { "data": [...] } in one response.

Durations

Fields such as delay, lease, ttl and expires_in take strings like "250ms", "30s", "5m", "1h" or "7d"; a bare number in a string means seconds. Queue durations also accept an integer number of milliseconds. Timestamps in responses are milliseconds since the Unix epoch.

Endpoints

Every primitive (a database, filesystem, queue, memory, vault, key-value store or object store) has an immutable id, a 26-character lowercase ULID, and every primitive endpoint addresses it by that id: /primitives/{id}/…. Renaming or moving a primitive never changes its id.

A primitive also has a type (db, fs, queue, memory, vault, kv or storage), a name that's unique per group and type, and a group. The group is only a collection: it decides which account owns the primitive and which scoped API keys can reach it. {group} is the group name. Group and primitive names are 1–63 characters from a-z, 0-9, -, _ and ., starting with a letter or digit.

Shapes

Groups

A group has no lifecycle of its own beyond create and delete. It starts empty.

Audit

Every audit route takes these query filters, which combine: group, type (group or a primitive type), primitive (an id), action (exact, or a prefix ending in . or * such as db.), actor (exact, or a prefix ending in * such as key:*), and since / until (inclusive, ms since the epoch), plus limit and cursor. An unknown type or since after until is 400 invalid_request. Scoped API keys get 403 forbidden. In the cloud the audit log needs Pro (403 plan_limit on Starter) and Pro reads go back 30 days. See Audit log.

Primitives

Snapshots, restore, fork, pause and stats belong to one primitive, not to the group.

Fork. name defaults to <name>-fork-<6 chars>. group is a group name and defaults to the source's group; a group that doesn't exist answers 404 not_found. snapshot (a label or id) forks from that snapshot instead of the live data. The copy gets a new id; its forked_from records the source, and its group says where it landed. If the target group already has a primitive of that type and name, the fork fails with 409 already_exists. A filesystem fork shares files over 64 KiB instead of copying them. A queue fork releases leases: leased jobs are ready again in the copy. A vault fork re-encrypts every value under the target group's key. A storage fork doesn't accept the source's signed URLs, and moving a storage primitive to another group invalidates its signed URLs.

Pause. Every data call on a paused primitive answers 423 paused. Info, stats, listing and creating snapshots, restore, fork, pause and resume still work. Pausing survives restarts.

Types. The data routes below are per type. Calling one on a primitive of another type, such as …/query on a filesystem, answers 400 wrong_type.

Database

Under /primitives/{id}, for a primitive of type db:

Filesystem

Under /primitives/{id}, for a primitive of type fs:

GET …/files with no path lists the root.

Queue

A queue primitive (type queue) holds any number of named queues and topics. Under /primitives/{id}:

Memory

Under /primitives/{id}, for a primitive of type memory:

Vault

Under /primitives/{id}, for a primitive of type vault:

KV

Under /primitives/{id}, for a primitive of type kv. {key} is the rest of the path, so keys may contain /:

A failed if_version answers 412 precondition_failed; in an atomic mset, the message names the item's index and nothing is written.

Storage

Under /primitives/{id}, for a primitive of type storage. {key} is the rest of the path:

A failed If-Match or If-None-Match on a write answers 412 precondition_failed. A Range that starts past the end answers 416 range_not_satisfiable with Content-Range: bytes */<size>; a malformed or multi-range Range is ignored and the whole object is returned with 200. Object reads send X-Content-Type-Options: nosniff and Content-Security-Policy: sandbox.

Signed URLs

Signed URLs are served at the top level, outside /primitives, and need no Authorization header: the token in the path is the credential.

A bad signature, an expired or revoked URL, the wrong method or a primitive that no longer exists all answer 403 forbidden, without saying which, and a paused store answers 423 paused. In the cloud, a malformed token is 400 invalid_request. In the cloud, signed routes allow cross-origin requests from any origin and are rate-limited by IP. Each request counts as one operation of the store's group. See Signed URLs.

Tool allowlists and endpoints

For API keys limited to some tools, each endpoint needs one tool on the allowlist:

A primitive's stats needs its type's read tool: db_query, fs_read, queue_receive, memory_recall, vault_list, kv_get or storage_read. primitive_list is always allowed for any key that reaches the group, whatever its allowlist. Reading the group, listing primitives (GET /primitives), getting one (GET /primitives/{id}) and listing snapshots need only a key for that group. Deleting, renaming, moving, pausing and resuming a primitive, creating, listing and deleting groups, and the audit trail are account-only. A primitive outside the key's group answers 404 not_found.

Example: create a database and query it

Create returns the new primitive's id; every later call uses it.

curl -X POST http://localhost:7777/v1/primitives \
  -H "Content-Type: application/json" \
  -d '{"name": "main", "type": "db", "group": "agent-42"}'

{
  "id": "01jbz3k8m5q2w7x9v4n6t0r1ce",
  "name": "main",
  "type": "db",
  "group": "agent-42",
  "created_at": 1760486400000,
  "paused": false,
  "size_bytes": 0,
  "forked_from": null
}

curl -X POST http://localhost:7777/v1/primitives/01jbz3k8m5q2w7x9v4n6t0r1ce/query \
  -H "Content-Type: application/json" \
  -d '{"sql": "select id, title from tasks where status = ?", "params": ["open"]}'

{
  "columns": ["id", "title"],
  "rows": [{ "id": 1, "title": "Write docs" }],
  "rows_affected": 0,
  "last_insert_rowid": null,
  "truncated": false
}

Idempotency

Idempotency-Key headers are coming soon. Until then, use dedupe_key when sending queue messages, and prefer idempotent SQL such as insert … on conflict do nothing for writes you may retry. The SDKs never retry POST requests on 5xx.