DocsDevelopers

API reference

Every call the Jade Cloud server answers: what to send, what comes back, and what can go wrong.

On this page
OverviewServerPairingAccount and devicesSettings, secrets and shared dataTasksRoutines and webhooksJade AIMarketplaceOther callsCompatibility

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. code is 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

StatusMeaning
400The body or a value is wrong. The message says which.
401No token, or the device isn’t paired (code unauthorized).
402The 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.
403Not allowed: a plan without this model, or a wrong key for a locked account (code wrongKey).
404No such thing, or this server doesn’t offer the feature.
409It can’t be done in the current state: a plan edit that no longer applies, a task that ended, an id in use.
413Too large.
423The account is locked and no key was sent (X-Jade-Key).
429Too many requests. Retry-After is set where known.

Rate limits

WhatLimit
Signed-in calls600 a minute per device.
Wrong tokens30 a minute per address.
POST /v1/pair10 in 10 minutes per address.
POST /v1/hooks/…60 a minute per address, and 30 an hour per webhook.
Publishing modules5 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

GET/healthzNo sign-in

Answers {"ok": true} when the runner is up.

GET/v1/infoNo sign-in

What 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
GET/v1/privacyNo sign-in

The privacy notes as an HTML page (also at /privacy).

Pairing

POST/v1/pairNo sign-in

Trades 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": {…}}
POST/v1/pairing-codesDevice token

Makes a code for another device of the same account. Answers {"code", "expiresAt", "link"}; the link opens the app.

POST/v1/appstore/activateNo sign-in

Hosted 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.

PUT/v1/appstore/subscriptionDevice token

Hosted 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.

POST/v1/appstore/notificationsNo sign-in

Hosted server only. Apple’s App Store Server Notifications v2 (renewals, expiry, refunds): body {"signedPayload"}.

Account and devices

GET/v1/meDevice token

The 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.

GET/v1/devicesDevice token

The paired devices: {"devices": [{"id", "name", "platform", "current", "push"}]}.

DELETE/v1/devices/<id>Device token

Signs a device out. Its token stops working.

PUT/v1/devices/current/pushDevice token

Registers this device for push notifications. Body {"token": "<hex>", "environment": "sandbox"|"production"}. Answers {"ok", "delivers"}: delivers is false when the server can’t send pushes.

DELETE/v1/devices/current/pushDevice token

Stops pushes to this device.

PUT/v1/devices/current/live-activity-startDevice token

Registers 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"}.

DELETE/v1/devices/current/live-activity-startDevice token

Removes it.

PUT/v1/account/lockDevice token

Locks the account with a key: {"key": "<256 bits, base64>"}. Changing a key needs the current one in X-Jade-Key.

DELETE/v1/account/lockDevice token

Removes the lock. Needs the key.

POST/v1/account/unlockDevice token

Sends the key so held work (schedules, webhook calls, tasks) can go on. Body {"key"}.

GET/v1/exportDevice token

Everything 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.

GET/v1/auditDevice token

The account’s security log: {"events": [{"at", "event", "detail"}]}.

POST/v1/me/consents/<tier>Device token

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.

DELETE/v1/me/consents/<tier>Device token

Takes the agreement back.

DELETE/v1/meDevice token

Deletes the account and everything it holds, and stops its tasks. Can’t be undone.

Settings, secrets and shared data

GET/v1/configDevice token

The 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.

PUT/v1/configDevice token

Replaces 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.

PUT/v1/secrets/<name>Device token

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.

DELETE/v1/secrets/<name>Device token

Removes a secret.

GET/v1/vaultDevice token

Saved sign-ins for the browser: {"entries": [{"id", "label", "domain", "username", "createdAt", "lastUsedAt"}]}. Passwords are never listed.

PUT/v1/vault/<id>Device token

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.

DELETE/v1/vault/<id>Device token

Deletes a sign-in.

PUT/v1/browser/cookiesDevice token

Replaces the browser cookies that Cloud tasks start with (up to 1.2 MB). Sealed, never logged, not exported. Answers {"count"}.

GET/v1/browser/cookiesDevice token

The cookies a task’s browser ended with, newer than ?since= (a timestamp), for the app to keep.

PUT/v1/profileDevice token

What 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.

GET/v1/profileDevice token

What is shared: {"memories", "location", "updatedAt"}.

DELETE/v1/profileDevice token

Clears 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.

POST/v1/tasksDevice token

Starts 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.
autonomy
askFirst, balanced or handsOff.
modelScopedID
The model to use, as provider/model from 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", …}}
GET/v1/tasksDevice token

The latest 200 tasks.

GET/v1/tasks/<id>Device token

One task with its approvals and up to 200 activity entries: {"task", "approvals", "activity"}.

POST/v1/tasks/<id>/cancelDevice token

Stops a task. Work done so far is kept.

POST/v1/tasks/<id>/retryDevice token

Runs a task that stopped (failed, cancelled or blocked) again. Counts as continuing, so a plan’s allowance applies.

POST/v1/tasks/<id>/planDevice token

Edits 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.

POST/v1/tasks/<id>/notesDevice token

Says 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.

GET/v1/tasks/<id>/browserDevice token

A look at a Cloud task’s browser: the page’s address, title and a small JPEG. 204 when no page is open.

DELETE/v1/tasks/<id>Device token

Deletes a task. Deleting one that doesn’t exist is not an error.

POST/v1/tasks/<id>/live-activityDevice token

Registers 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.

DELETE/v1/tasks/<id>/live-activityDevice token

Stops those pushes.

GET/v1/files/<id>Device token

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.

POST/v1/approvals/<id>Device token

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.

GET/v1/sync?since=nDevice token

Everything 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.

GET/v1/eventsDevice token

A 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"}.

GET/v1/triggersDevice token

All schedules and webhooks of the account.

POST/v1/triggersDevice token

Makes 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. enabled defaults 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]}}}'
PATCH/v1/triggers/<id>Device token

Changes any of those fields: {"enabled": false} pauses one.

DELETE/v1/triggers/<id>Device token

Deletes one. A webhook’s address stops working at once.

POST/v1/hooks/<secret>No sign-in

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.

GET/v1/ai/modelsDevice token

The levels this account can use now (auto, fast, expert, and ultra with Jade Max if offered), in OpenAI’s list shape.

POST/v1/ai/chat/completionsDevice token

OpenAI’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"}]}'
POST/v1/ai/audio/speechDevice token

Natural voices, taking what OpenAI’s speech call takes (input, voice, speed, response_format) and answering with audio. Counted in characters against the plan.

POST/v1/ai/mcpDevice token

Jade 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.

GET/v1/servicesNo sign-in

Live modules: {"version": 1, "modules": […]}. Optional ?category= and ?q=. Cached for 5 minutes; CORS allows any origin.

GET/v1/services/<id>No sign-in

One live module.

GET/v1/services/schemaNo sign-in

The JSON Schema for a module.

POST/v1/servicesNo sign-in

Publishes 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.

PUT/v1/services/<id>No sign-in

Replaces a module. Needs the edit token.

DELETE/v1/services/<id>No sign-in

Removes a module. Needs the edit token.

GET/v1/services/<id>/statusNo sign-in

{"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.

GET/v1/attest/challengeNo sign-in

A one-time challenge for App Attest.

POST/v1/attest/keyNo sign-in

Registers an attested app key: {"keyId", "attestation", "challenge"}.

POST/v1/help/chatNo sign-in

The help chat in onboarding. Needs an App Attest key; limited per address and per key.

POST/v1/relay/pushNo sign-in

The 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.