DocsDevelopers

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 onJade Cloud APIMCP serversModel providersModules and script appsLinksSecurity notes for integrators

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/callback is 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, deny

id 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

CallWhat it does
POST /v1/pairTrade a pairing code for a device token.
GET /v1/infoWhat this server is and offers. No sign-in.
GET /v1/sync?since=nTasks, approvals and activity changed since change number n, plus deletions.
GET /v1/eventsServer-sent events: pings that something changed, with no content. Then call sync.
POST /v1/tasksStart a task.
POST /v1/tasks/<id>/cancel, /retry, DELETE /v1/tasks/<id>Stop, try again, or delete.
POST /v1/tasks/<id>/planChange the plan while it runs: add, reword or skip a step.
POST /v1/tasks/<id>/notesSay something to a running task: {"text"}, up to 4,000 characters.
POST /v1/approvals/<id>Answer an approval.
GET/PUT /v1/configThe 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/profileMemories 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/meAccount, a full export, and delete everything.
GET /v1/ai/models, POST /v1/ai/chat/completionsJade 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.

TransportStatus
Streamable HTTPSupported. POST for requests, with an optional event stream for replies.
HTTP + SSESupported, for older servers.
stdioNot 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. The resource parameter 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

KindProtocolAuth
openAI, openAICompatibleOpenAI /v1/chat/completions with SSE streamingBearer key (optional for compatible)
anthropic, anthropicCompatibleAnthropic /v1/messages with SSEx-api-key and anthropic-version
ollamaOllama /api/chat, NDJSONNone (a local network)
customOne of the above, against any URLOptional

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.

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.