How the API works

The rest of these docs are about what you can build without writing code. This section is the other half: everything mente can do is a tool, and every tool is callable by a program.

There is one thing to understand before anything else.

One surface, two transports

mente does not have an MCP API and a separate REST API. It has one tool surface with two front doors, and they resolve the same tools, enforce the same permissions, and return the same results.

	MCP	REST
Who uses it	AI clients — Claude, Cursor, anything MCP-compatible	Your own code, scripts, CI
Find a tool	search_tools	GET /api/capabilities
Read its schema	get_tool_schema	GET /api/capabilities?name=…
Run it	execute_tool	POST /api/capabilities/{tool}

Pick the transport that fits the caller. An assistant discovering tools mid-conversation wants MCP; a nightly job that already knows what it's calling wants REST.

Discovery is the point

The catalog runs to a few hundred tools, and it moves — whenever a connector is added, and whenever you connect one. So nothing, not an AI client and not your code, should hold a hardcoded list.

Ask the catalog instead. It is filtered to what you can reach: your permissions, your connected services, your workspace.

GET /api/capabilities                 # everything you can call
GET /api/capabilities?toolkit=tasks   # one feature
GET /api/capabilities?query=invoice   # search across names and descriptions
GET /api/capabilities?name=create_task

Each entry carries the tool's name, description, JSON Schema, and whether it reads or writes. The response also carries a catalogVersion — 16 hex characters over the set of tools you can see. Cache against it, and you'll know when your view of the surface has changed.

The reference pages in this section list names and descriptions only, on purpose. Fetch the schema for the tool you're about to call rather than trusting a copy in a document — that's the one thing that can't go stale.

Calling a tool

POST /api/capabilities/create_task
Authorization: Bearer <token>
Content-Type: application/json

{ "title": "Renew the Acme policy", "priority": "high" }

Success returns the tool's own output wrapped in an envelope:

{ "data": { "id": "tsk_019a…", "title": "Renew the Acme policy" } }

Failure returns a flat body with a stable error code, whatever metadata the tool attached, and a requestId you can quote when asking for help:

{ "error": "invalid_input", "requestId": "req_01j…" }

Input is validated against the tool's schema before anything runs, so a malformed call fails cleanly without side effects.

When a tool needs a person

Some tools are gated on human approval. Those calls come back with approval_required and an approval id rather than a result — the work is waiting, not lost. Approve it (in the web app, or with mente approvals approve) and re-run the call.

The mente command-line tool maps this to exit code 4, distinct from a real failure, so a script can tell "someone needs to say yes" apart from "this broke."

Authenticating

Caller	Credential
An AI client over MCP	OAuth 2.1 — the client walks you through it on connect
An agent you run	An agent token, issued from the agent's page
Your own code	The same agent token, as Authorization: Bearer
The CLI	mente login (browser), or MENTE_TOKEN for headless use

If you belong to more than one workspace, send X-Mente-Org-Id to pick which one a request runs against. Without it, requests run against your default.

Creating an agent, minting its token, and scoping what it can reach is on the Agents page; Connecting to mente covers the OAuth path.

An agent's access is capped by the person who owns it — an agent can never reach something its owner cannot. See Sharing & permissions.

What's not a tool

A few things are ordinary HTTP endpoints because they move bytes rather than data: uploading and downloading files, and exporting a saved domain view as CSV. Your assistant can tell you the size of an export; the file itself comes from a plain authenticated download.

Where to go next

• Tools by feature — the primitives, grouped
• Connector library — every service mente connects to, and the tools each one adds to your catalog