API reference
Every call the Jade Cloud server answers: what to send, what comes back, and what can go wrong.
On this page
Overview
The Jade Cloud API is JSON over HTTPS. The app uses all of it, and so can scripts. Calls marked Device token need a paired device’s token; those marked No sign-in don’t. In the examples, is this server’s address and $TOKEN is a device token.
- Base URL
- The server’s address, like
https://jade.alexmiod.com. All paths start with/v1/. - Format
- Request and response bodies are JSON (
content-type: application/json). Times are ISO 8601 strings. Ids are UUIDs in upper case; lower case is accepted in paths. - Errors
- A failed call answers with an HTTP status and
{"error": "…plain words…", "code": "…"}. The message is written to be shown to a person.codeis optional and stable. The/v1/ai/…calls use OpenAI’s error shape instead:{"error": {"message", "type", "code"}}. - Sizes
- Bodies are limited per call (given below). A body over its limit answers
413.
Authentication
A device pairs once and receives a token. Every other call sends it as Authorization: Bearer <token>. A missing or unknown token answers 401 with code unauthorized. An account holds no name, email or password: it is a random id, and a token belongs to one device of it.
Status codes
| Status | Meaning |
|---|---|
400 | The body or a value is wrong. The message says which. |
401 | No token, or the device isn’t paired (code unauthorized). |
402 | The plan can’t do this now. Code subscription (ended or none) or allowance (a weekly limit is used up). The message says when it resets. |
403 | Not allowed: a plan without this model, or a wrong key for a locked account (code wrongKey). |
404 | No such thing, or this server doesn’t offer the feature. |
409 | It can’t be done in the current state: a plan edit that no longer applies, a task that ended, an id in use. |
413 | Too large. |
423 | The account is locked and no key was sent (X-Jade-Key). |
429 | Too many requests. Retry-After is set where known. |
Rate limits
| What | Limit |
|---|---|
| Signed-in calls | 600 a minute per device. |
| Wrong tokens | 30 a minute per address. |
POST /v1/pair | 10 in 10 minutes per address. |
POST /v1/hooks/… | 60 a minute per address, and 30 an hour per webhook. |
| Publishing modules | 5 an hour per address, or the publisher key’s own limit. |
Locked accounts
An account locked with a key sends that key (256 bits, base64) in an X-Jade-Key header. Without it, calls that need the data answer 423. A wrong key answers 403.
Server
/healthzAnswers {"ok": true} when the runner is up.
/v1/infoWhat this server is and offers: version, mode (hosted or selfhosted), public address, and a features object: browser, push, appStore (plans and products), webhooks, liveActivities, mcp, planEdits, notes, vault, browserCookies, profile, browserView, images, code, help, services, speech, accountLock and models (the Jade AI levels). A feature this server doesn’t offer is false or null.
curl /v1/info
/v1/privacyThe privacy notes as an HTML page (also at /privacy).
Pairing
/v1/pairTrades a one-time pairing code (from jade pair, valid for 15 minutes, once) for a device token. Body: {"code", "device": {"name", "platform", "appVersion"}}. Answers {"token", "deviceId", "accountId", "runner": {…info}}. Limited per address.
curl -X POST /v1/pair \
-H 'content-type: application/json' \
-d '{"code": "ABCD-EFGH", "device": {"name": "My phone", "platform": "ios"}}'
# {"token": "…", "deviceId": "…", "accountId": "…", "runner": {…}}/v1/pairing-codesMakes a code for another device of the same account. Answers {"code", "expiresAt", "link"}; the link opens the app.
/v1/appstore/activateHosted server only. Body: {"signedTransaction", "device"}, an App Store signed transaction, verified against Apple’s certificates. Finds or makes the account for that subscription, pairs the device, and answers like /v1/pair. 402 if the subscription has ended.
/v1/appstore/subscriptionHosted server only. Body {"signedTransaction"}: a newer transaction (for example after switching to Jade Max) applies at once, without waiting for Apple’s notification. 409 if the subscription belongs to another account.
/v1/appstore/notificationsHosted server only. Apple’s App Store Server Notifications v2 (renewals, expiry, refunds): body {"signedPayload"}.
Account and devices
/v1/meThe account: id, kind, locked, entitlement (active, problem, expiresAt, product), limitPercent if limited access, the devices, the names of stored secrets, MCP server status, usage for the last 30 days, the plan with what is left of each allowance, and the consents given.
/v1/devicesThe paired devices: {"devices": [{"id", "name", "platform", "current", "push"}]}.
/v1/devices/<id>Signs a device out. Its token stops working.
/v1/devices/current/pushRegisters this device for push notifications. Body {"token": "<hex>", "environment": "sandbox"|"production"}. Answers {"ok", "delivers"}: delivers is false when the server can’t send pushes.
/v1/devices/current/pushStops pushes to this device.
/v1/devices/current/live-activity-startRegisters the push-to-start token (iOS 17.2+) so a Live Activity can start for a task begun while the app is closed. Body {"token", "environment"}.
/v1/devices/current/live-activity-startRemoves it.
/v1/account/lockLocks the account with a key: {"key": "<256 bits, base64>"}. Changing a key needs the current one in X-Jade-Key.
/v1/account/lockRemoves the lock. Needs the key.
/v1/account/unlockSends the key so held work (schedules, webhook calls, tasks) can go on. Body {"key"}.
/v1/exportEverything the account holds as one JSON file: settings, tasks, approvals, activity, files, schedules, usage and the audit log. Secret values and passwords are never included.
/v1/auditThe account’s security log: {"events": [{"at", "event", "detail"}]}.
/v1/me/consents/<tier>Agrees to the provider’s privacy policy for a Jade AI level that asks (such as Ultra). Body {"version"} must be the version the server lists; 409 if the policy changed.
/v1/me/consents/<tier>Takes the agreement back.
/v1/meDeletes the account and everything it holds, and stops its tasks. Can’t be undone.
Settings, secrets and shared data
/v1/configThe account’s settings, as the app last sent them: model providers, search, MCP servers, agent rules, saved cards, site notes, time zone. API keys aren’t in it.
/v1/configReplaces the settings (up to 1 MB). Validated; 400 says what is wrong. Tasks that were waiting on a setup then go on; the answer’s resumed counts them.
/v1/secrets/<name>Stores an API key under a name like provider:openai. Body {"value", "remember"}; with remember: false it is kept in memory only. Values are sealed and never shown again.
/v1/secrets/<name>Removes a secret.
/v1/vaultSaved sign-ins for the browser: {"entries": [{"id", "label", "domain", "username", "createdAt", "lastUsedAt"}]}. Passwords are never listed.
/v1/vault/<id>Adds or changes a sign-in: {"label", "site", "username", "password"}. The password goes one way and only the browser uses it. Up to a fixed number of sign-ins; 409 past it.
/v1/vault/<id>Deletes a sign-in.
/v1/browser/cookiesReplaces the browser cookies that Cloud tasks start with (up to 1.2 MB). Sealed, never logged, not exported. Answers {"count"}.
/v1/browser/cookiesThe cookies a task’s browser ended with, newer than ?since= (a timestamp), for the app to keep.
/v1/profileWhat the app shares about the user so routines and webhook runs know them: {"memories": […], "location": {…}}. Sealed. Send only what sharing allows; what is left out is cleared.
/v1/profileWhat is shared: {"memories", "location", "updatedAt"}.
/v1/profileClears it.
Tasks
A task has a state: proposed, planning, waitingForApproval, running, waiting (a timed pause), blocked (needs the user, for example to sign in), completed, failed or cancelled. It has steps (each with its own state, tool calls and result), a result, usage and a budget.
/v1/tasksStarts a task (body up to 512 KB). Answers {"id", "task"}. Counts against the plan’s daily limit; 402 if there’s none left.
goal- Required. What to do, up to 20,000 characters.
id- A UUID. Makes the call idempotent: sending the same id twice returns the same task.
title- Up to 120 characters.
autonomyaskFirst,balancedorhandsOff.modelScopedID- The model to use, as
provider/modelfrom the settings. context- Text to share with the task, up to 8,000 characters (relevant memories, for example).
notify- Send a notification when it needs attention or finishes.
budget{maxModelCalls, maxToolCalls, maxInputTokens, maxActiveMinutes}. Each is capped (1,000; 2,000; 50,000,000; 1,440).origin,conversationID,messageID- Where it came from, so the app can link the task to its chat.
curl -X POST /v1/tasks \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"goal": "Find three flights to Lisbon next month and compare them",
"autonomy": "balanced"}'
# {"id": "5F1C…", "task": {"state": "planning", …}}/v1/tasksThe latest 200 tasks.
/v1/tasks/<id>One task with its approvals and up to 200 activity entries: {"task", "approvals", "activity"}.
/v1/tasks/<id>/cancelStops a task. Work done so far is kept.
/v1/tasks/<id>/retryRuns a task that stopped (failed, cancelled or blocked) again. Counts as continuing, so a plan’s allowance applies.
/v1/tasks/<id>/planEdits the plan while it runs. Body {"edit": "add", "text"}, {"edit": "reword", "stepID", "text"}, {"edit": "skip", "stepID"} or {"edit": "restore", "stepID"}. Answers {"task"}; 409 (code plan) when the change doesn’t apply now.
/v1/tasks/<id>/notesSays something to a task that hasn’t finished: {"text"} up to 4,000 characters. The task reads it at its next model call. 409 (code notes) if it has finished or has as many notes as it takes.
/v1/tasks/<id>/browserA look at a Cloud task’s browser: the page’s address, title and a small JPEG. 204 when no page is open.
/v1/tasks/<id>Deletes a task. Deleting one that doesn’t exist is not an error.
/v1/tasks/<id>/live-activityRegisters a Live Activity’s push token for the task on this device ({"token", "environment"}), so the Lock Screen follows it while the app isn’t running. 409 (code ended) if the task is over.
/v1/tasks/<id>/live-activityStops those pushes.
/v1/files/<id>A file a task made (an artifact), sent as a download with a locked-down content policy.
Approvals
A task asks before a risky tool. The approval is part of the task’s sync and notifications.
/v1/approvals/<id>Answers one: {"decision": "allowOnce" | "alwaysAllowTool" | "alwaysAllowConnection" | "deny", "via"}. Answers {"ok", "alreadyAnswered", "approval"}; answering twice is harmless.
Sync and events
Devices don’t poll tasks one by one. They keep a change number and ask what is newer, and listen on an event stream for when to ask.
/v1/sync?since=nEverything changed after change number n: {"seq", "more", "tasks", "approvals", "activity", "deleted": {"tasks", "approvals"}, "secretsMissing", "settingsUpdatedAt", "settingsDevice"}. Pages are limited; when more is true, call again with the new seq. secretsMissing names keys the settings need that the server doesn’t have, so a device can send them.
/v1/eventsA server-sent event stream. It carries only “something changed” pings and the change number, never content. On a ping, call sync.
# Start from nothing, then keep the number for next time: curl "/v1/sync?since=0" -H "Authorization: Bearer $TOKEN" # Listen for changes: curl -N /v1/events -H "Authorization: Bearer $TOKEN"
Routines and webhooks
See Routines and webhooks for how they behave. A trigger is {"id", "kind", "name", "goal", "enabled", "schedule", "timeZone", "autonomy", "modelScopedID", "createdAt", "lastRunAt", "lastTaskID", "lastSkip", "runs", "nextRunAt"}.
/v1/triggersAll schedules and webhooks of the account.
/v1/triggersMakes one (body up to 64 KB, at most 50 per account). Webhooks answer with webhookURL, shown once.
kind"schedule"or"webhook".name,goal- Required. Up to 80 and 4,000 characters.
schedule- For schedules:
{"everyMinutes": 60}(at least 15 on the hosted server) or{"daily": {"time": "08:00", "weekdays": [1,2,3,4,5]}}(1 is Monday). timeZone- An IANA name like
Europe/Lisbon. Defaults to the account’s setting. autonomy,modelScopedID,enabled- As for a task.
enableddefaults to true.
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]}}}'/v1/triggers/<id>Changes any of those fields: {"enabled": false} pauses one.
/v1/triggers/<id>Deletes one. A webhook’s address stops working at once.
/v1/hooks/<secret>The webhook itself: any body up to 64 KB (JSON is formatted, 32 KB of it kept). Answers {"ok": true, "task": "…"}, or {"ok": true, "held": true} for a locked account. 404 unknown, 429 too often. The body reaches the task as untrusted data.
Jade AI
Models, pictures and voices that come with a plan, as OpenAI-compatible calls, so another client can use them with a device token. Every token, image and character counts against the plan’s weekly allowance.
/v1/ai/modelsThe levels this account can use now (auto, fast, expert, and ultra with Jade Max if offered), in OpenAI’s list shape.
/v1/ai/chat/completionsOpenAI’s chat completions, with streaming and tool calls (body up to 24 MB). model is a level. jade_effort sets how much it thinks. 402 with code allowance when the week’s tokens are used up; 403 for a level the plan doesn’t include.
curl /v1/ai/chat/completions \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"model": "fast", "messages": [{"role": "user", "content": "Hello"}]}'/v1/ai/audio/speechNatural voices, taking what OpenAI’s speech call takes (input, voice, speed, response_format) and answering with audio. Counted in characters against the plan.
/v1/ai/mcpJade AI Images as an MCP server (JSON-RPC 2.0, stateless): initialize, tools/list, tools/call. Making an image counts against the weekly images; 402 with Retry-After when used up.
Marketplace
Public, with no account. Details, the module format and a form to try it are on the marketplace page; this is the list.
/v1/servicesLive modules: {"version": 1, "modules": […]}. Optional ?category= and ?q=. Cached for 5 minutes; CORS allows any origin.
/v1/services/<id>One live module.
/v1/services/schemaThe JSON Schema for a module.
/v1/servicesPublishes a module (up to 64 KB). Answers 201 {"id", "status", "editToken"}; the token is shown once. With a publisher key (Authorization: Bearer jpk_…) it goes live without review.
/v1/services/<id>Replaces a module. Needs the edit token.
/v1/services/<id>Removes a module. Needs the edit token.
/v1/services/<id>/status{"status": "pending" | "live" | "rejected", "note"}. Needs the edit token.
Other calls
These serve the app’s own setup and aren’t useful to scripts, but are listed for completeness.
/v1/attest/challengeA one-time challenge for App Attest.
/v1/attest/keyRegisters an attested app key: {"keyId", "attestation", "challenge"}.
/v1/help/chatThe help chat in onboarding. Needs an App Attest key; limited per address and per key.
/v1/relay/pushThe push relay for licensed self-hosted servers (Authorization: License …). Hosted server only.
Compatibility
Paths are under /v1/. New fields can appear in answers, and clients should ignore ones they don’t know. A field that is removed or changes meaning gets a new path. GET /v1/info says which features a server has, so a client can check before it calls.