API

The short answer

The supported programmatic surface of Corlecti Map is its MCP endpoint, a single address that speaks the Model Context Protocol:

POST https://map.corlecti.com/api/mcp
Authorization: Bearer mmap_live_YOUR_KEY

Everything a script needs — listing maps, reading one, creating blocks and links, searching by meaning, examining the shape of a map — is a tool on that endpoint. The MCP page names every one of them and shows how to connect.

You do not need an MCP client library to call it. It is JSON-RPC over HTTP, and a request is one POST with a JSON body.

Why there is not a REST API beside it

The application's own browser routes exist, and you can see them in a network tab. They are internal: they are shaped around what a screen needs, they change whenever a screen does, and they authenticate with a session cookie issued to a browser rather than with anything you can hold in a script. Nothing about them is promised to stay put.

One supported surface that is versioned by a protocol is worth more than two that disagree. If MCP cannot express something you need, tell us — that is a gap worth closing at [email protected], and it is more useful than a route that might be gone next month.

Getting a key

Settings → MCP Server, in the app. A key begins mmap_live_ and is shown once, at the moment it is minted. It carries your account's access and nothing narrower — treat it as a password, keep it out of a repository, and mint a new one rather than trying to recover a lost one.

Revoking a key takes effect immediately.

Making a call

Two headers matter. The bearer token, and an Accept naming both content types — the endpoint answers with a stream, and refuses a request that does not say it can read one:

curl -X POST https://map.corlecti.com/api/mcp \
  -H "Authorization: Bearer mmap_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

tools/list returns every tool with its input schema — the authoritative list, and worth reading rather than assuming, because it is generated from the server rather than written down. Calling one is tools/call with {"name": "...", "arguments": {...}}.

What an error means

• 401 — the key is missing, malformed, or has been revoked. Mint a new one.
• 402 — a capability or a spend gate. The body names which.
• 403 — a workspace member scoped to one branch reached outside it. Rare

outside a shared map.

• 404 — the map does not exist or is not yours. Deliberately the same

answer, so that a wrong id cannot be used to discover that somebody else's map exists.

• 429 — too many calls in a short window. The reply says how many seconds

to wait. It is a pause, not a limit on your plan.

• 500 — ours. If it repeats, [email protected].
• 503 — a dependency this deploy needs is unreachable. Not your plan's

fault; try again shortly.

Every code, what it means and what to do about it, in full: /docs/limits.

A tool that fails for an ordinary reason — a map that is not there, a document that will not validate — does not use a status code for it. The call succeeds and the result is marked as an error, with the reason in it.

Rate limits

Calling the endpoint is metered twice, separately: a volume quota (how many calls your plan gives you per day and per week) and a short-window burst ceiling shared across every caller, set well above ordinary use, to protect the endpoint itself rather than to bound any one account. Retrying immediately on a 429 will not help; the reply tells you how long to wait. Figures for both: /docs/limits.

Stability

Tool names and their inputs are the interface, and we do not remove or repurpose one silently. New tools and new optional arguments can appear at any time, so read tools/list rather than hard-coding the set.