Mycel
Get started

Mycel API

The Mycel API lets your own software, scripts and AI agents do what a firm owner does in Mycel: see what needs them, list clients, start client work, approve and send it, invoice and chase payment. It is a REST API over HTTPS with JSON in and out, described by an OpenAPI 3.1 specification. The same operations are available as tools on the Mycel MCP server.

Authentication

Every request carries the firm owner’s API key as a bearer token. Create one in Mycel under Settings, MCP. A key acts as the owner, so keep it on a server. Operations that reach a client (approve_and_send, send_invoice, chase_invoice) should be confirmed with the owner before an agent calls them.

Authorization: Bearer $MYCEL_API_KEY

Example request

Every operation is a POST to https://app.mycelhq.com/api/v1/<operation> with its inputs as a JSON body.

curl -X POST https://app.mycelhq.com/api/v1/list_clients \
  -H "Authorization: Bearer $MYCEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Operations

POST /api/v1/what_needs_me
The owner's ranked to-do list right now: work waiting for sign-off, clients who have not answered, overdue invoices, and why each matters.
POST /api/v1/list_clients
Every client of the firm, with their ids.
POST /api/v1/get_clientneeds client_id
What the firm knows about one client: their work, history, rules learned from corrections, and context.
POST /api/v1/add_clientneeds name
Add a client. Adding one can open their engagement if the firm has a live service; nothing is sent to them without the owner's OK.
POST /api/v1/list_deliverables
Client work produced by Mycel. Filter by status: in_review (waiting for the owner), with_client, accepted, drafting.
POST /api/v1/get_deliverableneeds deliverable_id
One deliverable: its versions, files, what was checked, and its timeline.
POST /api/v1/send_back_for_changesneeds deliverable_id, note
Send a deliverable back to be redone, with what is wrong. The note is kept as a correction the firm learns from.
POST /api/v1/list_client_requests
What the firm is waiting on from clients (documents, answers, decisions), and how long each has been open.
POST /api/v1/list_invoices
The firm's invoices, with status (draft, sent, overdue, paid) and amounts.
POST /api/v1/list_recurring_work
The recurring jobs per client (what runs, for whom, and when it is next due).
POST /api/v1/change_timingneeds job_id, instruction
Change when a recurring job runs, in plain words: 'push it to the 15th', 'skip October', 'quarterly from now on'. Unclear requests are refused with a question.
POST /api/v1/what_the_firm_knows
The firm's brain: what it sells, to whom, its clients and kinds of work, learned from its own mail and files.
POST /api/v1/approve_and_sendneeds deliverable_id
The owner's OK: send a deliverable that is waiting for review to its client.
POST /api/v1/list_approvals
Actions waiting for the owner's approval (emails, changes in client systems, spend).
POST /api/v1/decide_approvalneeds approval_id, decision
Approve or reject one pending approval.
POST /api/v1/send_invoiceneeds invoice_id
Send a drafted invoice to its client (moves it to sent and emails it).
POST /api/v1/chase_invoiceneeds invoice_id
Chase an overdue invoice now, politely, from the firm's inbox.
POST /api/v1/start_workneeds case_id, task_type
Start a piece of work on a client engagement (a case) — e.g. this month's report.
POST /api/v1/firm_files
List the firm's repository: a folder (path, default the root) or a search across it (q). The repo is how the firm works: practice/, rules/, clients/<name>/, gtm/ (icp.md, playbook.md, pipeline.md, deals.md), analytics/, site/.
POST /api/v1/read_firm_fileneeds path
Read one file in the firm's repository, e.g. gtm/playbook.md (which angle earns replies per buying moment) or rules/house.md.
POST /api/v1/firm_history
The repository's history: every commit to how the firm works, the proposed versions waiting, merged, declined or switched off.
POST /api/v1/edit_firm_fileneeds path, body
Edit a file the owner may edit (gtm/icp.md, gtm/playbook.md's 'Your angles' and 'Your opener', practice/*.md, a service's SKILL.md, a client's card.md). The change is a commit; every later run reads it.
POST /api/v1/decide_firm_changeneeds consolidation_id, index, decision
Merge, dismiss, or undo a change to how the firm works that its agents proposed (see firm_history and what_needs_me). Undo reverses a merged change and records it.
POST /api/v1/call_mycelneeds method, path
Any Mycel API route not covered above. method GET or POST (or PATCH/DELETE), path under /v1/, optional JSON body. See https://docs.mycelai.dev for the routes.

Errors

Every 4xx and 5xx response is JSON with a stable machine-readable code, a message for people and a hint for what to do next. Codes: missing_input (400), unauthorized (401), forbidden (403), unknown_tool and not_found (404), rate_limited (429), request_failed (500).

{ "error": { "code": "unauthorized", "message": "No key, or the key is not valid.", "hint": "Send Authorization: Bearer <owner API key> from Mycel's MCP settings." } }

Rate limits

Each key may make 120 requests per 60 seconds. Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy headers. Over the limit, the API answers 429 with a Retry-After header in seconds; wait that long, then retry.

Versioning and deprecation

The version is in the path: this is v1. Adding operations, optional inputs or response fields is not a breaking change. A breaking change ships as /api/v2, and v1 keeps working for at least six months after v2 ships. An operation that is going away answers with a Deprecation header (RFC 9745), a Sunset header with its last day (RFC 8594) and a Link to its replacement, and is announced in the changelog.

For AI agents

Agents can read llms.txt for when to use Mycel, connect over MCP, or load the OpenAPI specification as function definitions: every operation has a unique operationId, a description and a typed input schema.