Reference

HTTP contract

This is the only hard artifact. There is no SDK to keep in sync and no UI package to import — if your product speaks these routes, it works, and it keeps working when the internals move.

kernel/harness/src/server.ts is authoritative and contract.ts holds the types. Where this page and that code disagree, the code wins; tell us and we will fix the page.

Start with four routes

Most products never need more than this. Build these before you read the rest of the page.

POST /v1/tasks                  # start work
GET  /v1/tasks/:id/events       # watch it (SSE, resumable)
GET  /v1/approvals?status=pending
POST /v1/approvals/:id/approve  # { edited? }

Three planes, three credentials

Getting a 401 usually means you are on the wrong plane, not that the token is wrong.

The planes do not overlap. A client token on a founder route is an unrecognised credential, not a narrowed one. GET /health and the five /v1/auth/* routes are the only open endpoints.

Scope: a project key sees exactly its project. A member sees the whole org and must send X-Mycel-Project on writes if they have more than one. Out-of-scope ids return 404, never 403.

Tasks

constraints are max_runtime_s, max_cost_usd and approval_required, all clamped down to the server ceilings — a client cannot raise them.

Approvals

GET  /v1/approvals?status=pending|auto_approved|approved|rejected|expired
POST /v1/approvals/:id/approve   { "edited": { … } }   → { ok, decision }
POST /v1/approvals/:id/reject                          → 409 if already decided

The identifier field on an Approval is approval_id, not id.

Connections, channels, clients

Wedges and knowledge

GET  /v1/wedges/:wedge                       # manifest, skills, authored + live knowledge
GET  /v1/wedges/:wedge/knowledge
POST /v1/wedges/:wedge/knowledge             # { name, content, kind?, source?, metadata? }
PUT  /v1/knowledge/:id
DEL  /v1/knowledge/:id

GET  /v1/wedges/:wedge/intake                # question queue + coverage percentage
POST /v1/wedges/:wedge/intake/:question      # { answer }
POST /v1/wedges/:wedge/intake/:question/dismiss

The service surface

Only reach for these when the work outlives a single task. Cases are a lifecycle, records are a per-wedge key-value store, schedules make work arrive on its own.

GET|POST /v1/cases            GET|PUT /v1/cases/:id
POST     /v1/cases/:id/tasks              # spawn a task on the case; 409 if closed

GET|POST /v1/records          GET|DELETE /v1/records/:id
                                          # ?where=<JSON>; upsert on (wedge, collection, key)

GET|POST /v1/schedules        GET|PUT|DELETE /v1/schedules/:id
POST     /v1/schedules/:id/run            # fire now

GET|POST /v1/blueprints…                  # provision / readiness / activate
GET      /v1/analytics?days=30
GET      /v1/audit  ·  /v1/audit/verify   # tamper-evident chain
GET      /v1/tasks/:id/trace              # the run as a span tree, folded from the event log
GET      /v1/meta                         # wedges, store, sandbox
GET      /health                          # open

Schedule cadences are { kind: "every", seconds }, { kind: "daily", hour, minute } or { kind: "monthly", day, hour, minute }, all UTC.

The client plane

POST /v1/portal/session              # { token: "mpl_…" } → mcli_ session. Single use
GET  /v1/portal/me
GET  /v1/portal/threads  ·  /threads/:id
POST /v1/portal/threads/:id/messages # { body } → message + task_id. 413 over 10,000 chars
GET  /v1/portal/tasks/:id/events     # filtered stream — no cost, no approvals
GET  /v1/portal/cases

A customer replying on a thread starts work— the message spawns a task on the thread's channel. That is the shortest path from "customer said something" to "agent is on it".

The sandbox plane

You do not call these. They exist so you can reason about what the agent can reach: /v1/internal/gate (approval for tool calls), /v1/internal/actions/:capability (gated), /v1/internal/reads/:capability (ungated, capped), /v1/internal/llm/* (proxied model calls), /v1/internal/records/*, /v1/internal/case*, /v1/internal/workflows/:name, /v1/internal/knowledge/gap.

Each is authenticated by a per-task nonce that expires with the run. None of them accept a founder key. See The trust boundary.

Errors

Errors are { "error": "lower-case sentence" }. They are written to be shown to a developer, not parsed.

What to read next

Integrating a frontend — the handful of these routes that need care when proxied.