For developers
The protocols Jade speaks and the APIs it exposes: Jade Cloud, MCP, model providers, webhooks, modules and links.
On this page
What you can build on
- Jade Cloud API
- The HTTP API the app uses to talk to a Jade Cloud server: pair a device, start tasks, answer approvals, schedule routines, receive webhooks. Details.
- MCP servers
- Jade connects to remote MCP servers over Streamable HTTP or HTTP+SSE, with a token or OAuth sign-in. Details.
- Modules and script apps
- A JSON file that adds a service, or a few scripts that run on the device, to Jade. Published through a public API. Guide, jade object reference and Marketplace API.
- Model providers
- Any server that speaks the OpenAI or Anthropic wire format works as a provider. Details.
- Links
jade://module?url=https://…opens the add screen for a module.jade://oauth/callbackis the redirect for OAuth sign-in. Details.
Jade Cloud API
Jade Cloud is a small Node server (TypeScript, SQLite) that runs the app’s agent while the phone is locked. The hosted one is jade.alexmiod.com. You can also run your own with Docker: it sets up its own proxy and certificate, runs the agent and the browser as accounts with no shell and read-only filesystems, and has no plan limits. The whole API is JSON over HTTPS.
The full list of calls, with bodies and answers, is in the API reference.
Authentication
A device pairs once and gets a token. Every other call sends it:
# On the server, make a one-time code (works once, for 15 minutes):
docker compose exec runner jade-runner pair
# Trade the code for a device token:
curl -X POST /v1/pair \
-H 'content-type: application/json' \
-d '{"code": "ABCD-EFGH"}'
# {"token": "…", "deviceId": "…", "accountId": "…", "runner": {…}}Send Authorization: Bearer <token> on everything after that. The hosted server also takes a signed App Store transaction (POST /v1/appstore/activate) in place of a code. Accounts hold no name, email or password: an account is a random id.
Start a task and watch it
curl -X POST /v1/tasks \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"id": "5F1C2B1E-0A4D-4D0B-9F43-2D3E5C7A9B10",
"goal": "Find three flights to Lisbon next month and compare them",
"autonomy": "balanced"}'
# What changed since change number N (tasks, approvals, activity):
curl "/v1/sync?since=0" -H "Authorization: Bearer $TOKEN"
# Answer an approval:
curl -X POST /v1/approvals/$APPROVAL_ID \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"decision": "allowOnce"}' # or alwaysAllowTool, alwaysAllowConnection, denyid is optional and makes the call idempotent: sending the same one twice returns the same task. autonomy is askFirst, balanced or handsOff. A goal is up to 20,000 characters, and context (up to 8,000) is text the caller shares with the task.
Endpoints
| Call | What it does |
|---|---|
POST /v1/pair | Trade a pairing code for a device token. |
GET /v1/info | What this server is and offers. No sign-in. |
GET /v1/sync?since=n | Tasks, approvals and activity changed since change number n, plus deletions. |
GET /v1/events | Server-sent events: pings that something changed, with no content. Then call sync. |
POST /v1/tasks | Start a task. |
POST /v1/tasks/<id>/cancel, /retry, DELETE /v1/tasks/<id> | Stop, try again, or delete. |
POST /v1/tasks/<id>/plan | Change the plan while it runs: add, reword or skip a step. |
POST /v1/tasks/<id>/notes | Say something to a running task: {"text"}, up to 4,000 characters. |
POST /v1/approvals/<id> | Answer an approval. |
GET/PUT /v1/config | The account’s settings: providers, search, MCP servers, agent rules, saved cards, site notes. API keys are sent separately. |
PUT/DELETE /v1/secrets/<name> | Store or remove an API key, kept on the server or in memory only. |
GET/POST /v1/triggers, PATCH/DELETE /v1/triggers/<id> | Schedules and webhooks. |
PUT/GET/DELETE /v1/profile | Memories and a rough location the app shares, so routines and webhook runs know the user. Sealed, and cleared when the app stops sharing. |
GET /v1/me, GET /v1/export, DELETE /v1/me | Account, a full export, and delete everything. |
GET /v1/ai/models, POST /v1/ai/chat/completions | Jade AI as an OpenAI-compatible provider. |
Webhooks
A webhook trigger has its own secret address. A POST to it starts a task, and the body becomes untrusted input: the agent reads it as data, never as instructions.
# A webhook (needs the server's public address to be set):
curl -X POST /v1/triggers \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"kind": "webhook", "name": "New order", "goal": "Summarize this order and flag anything odd."}'
# {"trigger": {…}, "webhookURL": "https://…/v1/hooks/"}
# Anyone with that address can call it (up to 64 KB, rate limited):
curl -X POST "$WEBHOOK_URL" -d '{"order": 1042, "total": "58.20"}'
# A schedule: weekdays at 08:00 (1 is Monday), in a time zone:
curl -X POST /v1/triggers \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"kind": "schedule", "name": "Morning brief", "goal": "Summarize my day.",
"timeZone": "Europe/Lisbon", "schedule": {"daily": {"time": "08:00", "weekdays": [1,2,3,4,5]}}}'
# or: "schedule": {"everyMinutes": 60} Webhook addresses are stored only as hashes. A call to a locked account is held and runs when a device unlocks it.
Self-hosting
The setup script installs everything: Docker, the proxy, certificates, backups, and a jade command for admin tasks (pair, accounts, devices, unpair, services, keys, logs, backup, and more). Settings are environment variables; the ones most people change are JADE_PUBLIC_URL, JADE_MODE (hosted or selfhosted) and the model server for Jade AI. JADE_SITE=0 turns this website off.
MCP servers
Jade merges the tools of every connected server into every chat and task.
| Transport | Status |
|---|---|
| Streamable HTTP | Supported. POST for requests, with an optional event stream for replies. |
| HTTP + SSE | Supported, for older servers. |
| stdio | Not possible on iOS (no child processes). Run the server elsewhere and expose it over HTTP, for example with an MCP proxy. |
- Methods. JSON-RPC 2.0:
initialize,tools/list,tools/call,resources/list,resources/read,prompts/list. Tool lists are re-fetched when they change. - Token sign-in. A header name and a token. The default is
Authorization: Bearer. The token goes only to that server, and is kept in the Keychain. - OAuth sign-in. The MCP authorization flow (OAuth 2.1 with PKCE). Jade finds the sign-in service from
/.well-known/oauth-protected-resource(RFC 9728) and/.well-known/oauth-authorization-server(or OpenID configuration), registers itself with dynamic client registration (RFC 7591), and signs in through the system’s secure web sheet. Redirect:jade://oauth/callback. Theresourceparameter is the server’s URL (RFC 8707). The access token is refreshed while the app is open. - Risk. A tool is low risk if it only reads: the server says so with
readOnlyHint(and no destructive hint or send/buy/delete in its name), or the user marks it. Everything else is high risk and asks first. - Untrusted by design. Tool descriptions and results are data. They are quoted into the model’s context, never placed in its instructions.
To list a server for everyone, publish it as a module.
Model providers
| Kind | Protocol | Auth |
|---|---|---|
openAI, openAICompatible | OpenAI /v1/chat/completions with SSE streaming | Bearer key (optional for compatible) |
anthropic, anthropicCompatible | Anthropic /v1/messages with SSE | x-api-key and anthropic-version |
ollama | Ollama /api/chat, NDJSON | None (a local network) |
custom | One of the above, against any URL | Optional |
A server that speaks the OpenAI or Anthropic format needs no changes on Jade’s side: add it as a provider with its base URL. Every provider’s stream is turned into the same events (text, tool calls, usage), and a dropped connection is a typed error that triggers fallback, never a hang. A Jade Cloud also offers its included models at /v1/ai/chat/completions, so another OpenAI-compatible client can use them with a device token.
Modules and script apps
A module adds a service: a JSON file naming the service’s MCP server and how to sign in. A script app is a few small JavaScript tools that run on the user’s device in Jade’s sandbox, with a jade.* API for calendar, notes, models, web, notifications, cards and more. Each kind of access is a permission the user answers Ask first, Allowed or Blocked, and limits can be raised by entitlements the user switches on. Every function is in the jade object reference.
Publishing is one public API call with no account. See the marketplace API for the file format, the JSON Schema (/v1/services/schema), the publish and update calls, and a form to try them.
Links
jade://module?url=https://…- Opens Jade’s add screen with the module at that address. The user reads what it is and where it connects, and confirms.
jade://oauth/callback- The redirect address for OAuth sign-in. Register it as Jade’s redirect URI with a service that has no dynamic client registration.
Security notes for integrators
- Outside content is data. Web pages, search results, MCP descriptions and results, files and webhook bodies are quoted and labelled. A task that has read some asks again before a risky tool.
- Secrets. Keys live in the Keychain on the device. On a server, they are encrypted under a master key, or kept in memory only if the app asks. Logs and error messages strip key-shaped text.
- Passwords are never sent to a model. The model writes a stand-in and the real value is typed only on the site the sign-in belongs to, over https.
- Locked accounts. An account can be locked with a key kept on its devices. The server holds the data sealed, and a task that needs it waits for a device to unlock it.
- Rate limits apply to pairing, webhooks and publishing, and answer 429.