Skip to content
ailuDOCS
FROpen the Studio
Settings › Developer access

Ailu from your tools

The REST API, the MCP server for Claude Code, Cursor and VS Code, and the engine SDKs. The API acts with your identity, in your organisation, by your role. The MCP server does so only for some of its tools.

The API

Every request carries a token — Authorization: Bearer, with your session token or an API key — and may name the organisation it targets — x-tenant-id — when you belong to several. Role and membership are always read on the server: the header grants nothing.

API keys

A key starts and reads the organisation's runs from CI, a script or n8n, without a person's session. An owner creates it with a name, a lifetime in months and its scopes — start a run, read runs —, then copies it: it shows only once, and Ailu keeps only a fingerprint. It can be revoked at any time.

  1. It never approves a gate and touches neither members, nor keys, nor policies.
  2. A run started with a key goes through the same gates, policies and caps as a run a person starts; the journal signs it in the key's name, and the person who created the key counts as the one who started the run.
  3. Per key: 60 requests per minute on the Free plan, and everywhere until the Ailu team turns on plan limits. With them: 300 on Team, 600 on Regulated, 1,200 on Enterprise. During the beta, a Free organisation is treated as Team: 300 per key, once plan limits are on.
  4. POST /runs: 20 starts per minute, counted per key with plan limits, per IP address otherwise. With them, the organisation also has a cap on starts per minute by plan.
  5. Beyond a limit, the API answers 429. An unknown graph, or another organisation's, answers 404.
betaThe Ailu team turns API keys on organisation by organisation. Until then, no key can be created and any key presented to the API is refused.

Webhooks

Ailu tells your tools when a run ends or waits, when an approval is requested or given, when a delegation is refused or an incident opens. An owner adds the URL and picks the events.

  1. Each delivery carries only ids, a status and links — never a run's content. The signing secret shows only once.
  2. The Ailu-Signature header reads t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. Accept the delivery if one v1 matches and t is within 300 seconds of your clock.
  3. During a secret rotation, the header carries one v1 per secret: only one needs to match.
  4. Eight attempts per delivery; after 20 failed deliveries in a row, the webhook is turned off and the owners are told by e-mail.
betaLike API keys, webhooks are turned on organisation by organisation by the Ailu team; until then, nothing is sent.

The MCP server

Ailu's MCP server runs locally, on your machine, started by your editor. Some tools call the control plane with the token and organisation you give it. The others run on the spot, without it.

  1. Knowledge, with your role: search_brain, get_context, brain_*, index_local. What index_local indexes stays pending until it is reviewed in governed knowledge.
  2. Skills, with your role: list_skills, get_skill. They read your organisation's skills.
  3. Modules, on the spot: list_modules, get_module, plan_module_workflow, run_module_workflow. They read the catalogue shipped with the server, not your organisation.
  4. Agents and graphs, on the spot: list_agents, run_agent, run_graph, approve_and_resume, validate_graph, compile_graph_yaml. run_agent and run_graph run only the server's sample agents and graphs, never your organisation's graphs.
runsrun_agent, run_graph and run_module_workflow run in memory, in the local process, outside the control plane: no organisation, no journal, no attestation. Everything is lost on restart.
gatesThese runs' gates are not governed human approvals. By default, approve_and_resume refuses to pass them. The server records the approver human-operator only if the person who launched it set AILU_MCP_ALLOW_LOCAL_APPROVAL=1. That opt-in authenticates no one: the name the caller gives stays mere information. An input with a key starting with __ is refused. For a governed run, start it through the API (POST /runs with a key) and approve its gates in the Studio.

The engine SDKs

@ailu-ai/graph-sdk (TypeScript, npm) and adriane-ai (Python, PyPI) build, validate and run graphs in your own process, with the same runtime as the control plane.

Not yet

SoonA hosted MCP endpoint, with OAuth.

SoonThe full API reference, generated from its OpenAPI document.

Checked against the Studio on 21 October 2026