Marketplace API
A module adds one service to Jade. It is a JSON file with the address of the service’s MCP server and the steps for making a token. It has no code. Add a module to your own Jade with a link, or publish it to this catalog. No account needed.
New to APIs? · Module format · Script apps · API · Try it · Catalog · JSON Schema
New to APIs?
An API is a web address you send requests to, and it sends back an answer. You don’t need to write a program: you can use the forms in Try it below, or run a command in a terminal.
The steps to get a service into Jade:
- Write the module file (JSON, a text format). Copy the example under Module format and change the values.
- Send it to this server. Either paste it into the Publish form below, or run the
curlcommand in API (curl is a tool that sends web requests, and it is already on Mac and Linux). - The server checks the file and tells you what is wrong, if anything. If it is fine, the module is
pending. The person who runs this server looks at it and approves it. - Once approved it is
live, and it shows up in Jade’s list of services.
Words you will see
- GET reads something. POST sends something new. PUT replaces something you sent before. DELETE removes it.
- Edit token: a secret code you get once when you publish. It proves the module is yours, so you can update or remove it later. Save it somewhere safe. If you lose it, you can’t change the module.
- MCP server: the part of a service that Jade talks to. If you don’t have one, a script app (below) needs no server.
- Pending, live, rejected: waiting for review, listed in Jade, or turned down (the status call tells you why).
If something goes wrong
400The file has a mistake. The answer lists each one in plain words.401The edit token is missing or wrong.404There is no module with that id.409That id is already taken. Pick another.429Too many tries. Wait an hour.
Module format
The token is sent only to the module’s server, which has to be https. A file is at most 64 KB.
{
"id": "acme",
"name": "Acme Tasks",
"publisher": "Acme Inc.",
"category": "Productivity",
"blurb": "Your Acme tasks and projects",
"about": "Jade can look up, create and update tasks through Acme's MCP server.",
"symbol": "checklist",
"color": "#5E6AD2",
"server": { "url": "https://mcp.acme.example/mcp", "header": "Authorization" },
"token": {
"name": "API key",
"page": "https://acme.example/settings/keys",
"steps": [
"Open Acme's key page and sign in.",
"Create a key named “Jade”.",
"Copy it."
]
},
"abilities": ["Find tasks", "Create and update tasks"],
"version": 1
}
| Field | Required | Rules |
|---|---|---|
id | yes | 1–48 characters: a-z 0-9 . _ -. Must be unique. schema is reserved. |
name | yes | Up to 40 characters. |
publisher | yes | Who makes the service. Up to 80 characters. |
category | yes | Free text, like “Developer” or “Email”. The catalog groups by it. |
blurb | yes | One line, up to 140 characters. |
about | no | Up to 1000 characters. |
symbol | yes | An SF Symbol name. Unknown names show a puzzle piece. |
color | no | #RRGGBB |
server.url | yes | https only, with no username or password. |
server.header | no | Header that carries the token. Default: Authorization as a bearer token. Letters, digits and -. |
server.auth | no | token (default) or oauth. With oauth the person signs in on the service’s own page and there is no token. |
server.oauth | no | Only with auth: "oauth", and every part is optional: scopes (up to 20, no spaces), clientID (up to 200 characters), and https addresses authorizationURL, tokenURL, registrationURL. Jade finds the rest from the server. Its redirect is jade://oauth/callback. |
token.name | yes, unless oauth | For example “API key”. |
token.page | yes, unless oauth | https page where the token is made. |
token.steps | yes, unless oauth | 1–12 steps, up to 300 characters each. |
abilities | no | Up to 12 short phrases. |
version | no | Whole number. Raise it when the file changes. |
verified | no | false if the server could not be checked. The app hides the module unless the person turns on Developer mode, and tags it Unverified. Then the server is not required to answer when you publish (private addresses are still refused). |
whatsNew | no | Up to 5 short lines (120 characters each) about what changed. Shown with an update. |
To add a module to your own Jade, go to Settings → Apps & tools → Connections → Browse services → Add a module. Use a link to the file, paste the JSON, or choose a file. A jade://module?url=https%3A%2F%2Fexample.com%2Facme.json link opens Jade with the module. Jade shows where the module connects and keeps it only after you tap Add.
Script apps
A module can carry its own code instead of pointing to a server. A script app has script and no server or token. Its tools are small JavaScript functions that run on the user’s device, in Jade’s code sandbox, and each run asks first.
{
"id": "tip",
"name": "Tip Splitter",
"publisher": "Me",
"category": "Scripts",
"blurb": "Split a bill with a tip, exactly",
"symbol": "dollarsign.circle",
"script": {
"tools": [{
"name": "split",
"description": "Split a bill between people with a tip percentage.",
"parameters": [
{ "name": "bill", "type": "number", "description": "The total before tip" },
{ "name": "tip_percent", "type": "number", "required": false },
{ "name": "people", "type": "integer", "required": false }
],
"code": "const tip = (args.tip_percent ?? 18) / 100; const n = args.people ?? 1; const total = args.bill * (1 + tip); return `Total ${total.toFixed(2)}, ${(total / n).toFixed(2)} each for ${n}.`;"
}],
"network": false
},
"version": 1
}
- A module has either
scriptorserver(withtoken, orauth: "oauth"and notoken), never both. script.tools: 1–8 tools (none is fine when the app haswindows).nameis letters, digits and_, starting with a letter. The full name,<id>_<name>with anything but letters and digits in the id turned into_, is at most 40 characters and unique in the app.descriptionis required, up to 300 characters. The model reads it to decide when to call the tool.codeis the body of an async function ofargs, up to 32 KB. What it returns is the result.parameters: up to 12, each{ name, type, description, required }.typeis string, number, integer, boolean, array or object.requireddefaults to true.script.network: truesays the code fetches from the internet. Prefer thenetworkpermission andjade.fetch, which lists the sites and asks the user.- Every
jade.*function, with signatures, limits and examples, is in the jade object reference. script.permissions(optional): up to 19 entries{ id, access, reason, warning, domains }for what the code can reach throughjade.*.idis one of calendar, reminders, contacts, photos, location, notes, shortcuts, models, web, clipboard, notifications, tools, network, scan, files, chat, session, window, media, once each.accessisread(default) orchange; every one but contacts, photos, location, models and web can bechange, and shortcuts, notifications, tools, network, scan, files, chat, session, window and media always count aschange.networklets the code calljade.fetchand takesdomains: up to 20 sites likeexample.comor*.example.comthat it may reach without asking; any other site asks once per run.reasonis shown next to the choice andwarningwhen the user picks Blocked, each up to 200 characters. When adding the app, the user picks Ask first, Allowed or Blocked for each one. Each starts Allowed unless the entry has"default": "ask".script.entitlements(optional): up to 7 entries{ id, reason }for going past the usual limits.idis one ofhighVolume(more calls and model requests per run),longRuns(runs up to 10 minutes),anyNetwork(the code can reach any website),moreStorage(8 MB of saved data) orrunsQuietly(its tools run without the usual OK before each run),webSearch(the app's search hook runs before every web search) oranyModel(any model, not just the person's chosen one), once each.reasonis up to 200 characters and shows next to the switch. Each starts on for the user to switch off, unless the entry has"default": "off".script.cards(optional): up to 8 cards{ name, summary, template, sample }that the app shows in the chat withjade.cards.show(name, data).nameis 2 to 30 characters and unique once lowercased with other characters as_.summaryis up to 200 characters.templateis HTML of up to 50,000 characters with{{field}},{{#list}}…{{/list}}and{{^field}}…{{/field}}; it runs in a web view with no network.sampleis an object of example data. The whole file still has to fit in 64 KB. Showing a card needs no permission.script.settings(optional): a settings page of the app's own,{ "title", "sections": [ { "title", "footer", "items": [ … ] } ] }: 1 to 8 sections (title 60 characters, footer 300) and 40 items in all. An item hastype,title(60),subtitle(200) andicon(an SF Symbol name); every type excepthtmlalso needs anid(letters, digits and_, starting with a letter, up to 40, unique in the app). Types:toggle(defaulttrue or false);choice(options, 2 to 20 of{ value, title }, and adefaultthat is one of them);text(placeholder,multiline,maxLengthup to 2,000,default);number(min,max,step,slider,default); andhtml(htmlup to 20,000 characters,cssup to 10,000,height40 to 800), a block of the app's own markup in a web view with no network. The page shows as a Settings row on the app and in Settings → Apps & tools → App settings. The code reads and writes the values withjade.settings, which needs no permission. See the jade object reference.script.setup(optional): a setup screen that opens when the app is added,{ "title", "message", "sections", "check" }:title60 characters,message400,sectionsas inscript.settings. It uses the settings rows plussecret(text kept in the Keychain; nodefault) andsignin({ id, title, url, doneWhenUrlMatches }: a button that opens the site's own sign-in page;urlis https, up to 500 characters, with no login in it, and its host has to be covered by a domain of the app'ssessionpermission). A row can say"required": true(text, secret, toggle or signin only).checkis{ "tool", "title" }:toolis one of the app's tools, which Jade runs when the person taps the button, and which fails by throwing or returning{ "ok": false, "message" }. Until every required row is done and the check has passed, the app shows Needs setup and its tools say what is missing. Ids can't be used in bothsetupandsettings.secretandsigninrows also work on a settings page.script.server(optional):{ "routes": [ { "method", "path", "tool" } ] }, 1 to 24 routes. It is a small server inside Jade on the device, not a network server. Each route runs one of the app's own tools:toolhas to be the name of one of the app's tools,pathstarts with/(up to 200 characters;/items/:idhas a parameter), andmethodis GET, POST, PUT, PATCH or DELETE (any method when left out). A card with"interactive": truecan call these routes from its page, and needsscript.server.script.webSearch(optional):{ "tool": "name" }.toolis the name of one of the app's tools, and thewebSearchentitlement has to be listed too. Jade calls that tool before every web search, once the person switches the entitlement on. The tool returns{ query, count, engine, allowDomains, blockDomains }(all optional) or{ results: [{ title, url, snippet }] }.script.windows(optional): up to 8 full-screen pages of the app's own,{ id, title, entry, tools }. The app has to list thewindowpermission.idis letters, digits and_, starting with a letter (40 at most, unique);titleis up to 60 characters;entryis an.htmlfile with no leading/, no..and no part starting with a dot (index.htmlwhen left out). Each window gets the toolopen_<id>, and each of its up to 24tools{ name, description (1–300 characters), parameters }becomes the app tool<id>_<name>, answered by the open page. Every tool name of the app, its own and the generated ones, is unique once lowercased, and its full name is at most 40 characters.script.bundle(optional):{ url, sha256, size }, the pages and assets as one.tar.gz.urlis https with no login in it,sha256is 64 hex digits andsizea whole number of bytes up to 200 MB. When the module is sent in, or its bundle changes, this server downloads the file: the address has to answer 200 and the file has to match the hash (and the size).script.files(optional): up to 40 small text files kept in the manifest, path → text, 48 KB all together. A path has no leading or trailing/, no.or..part, no part starting with a dot, and only letters, digits and._ -/@+=. Without abundle, every window's page has to be one of these files. The file as a whole still has to fit in 64 KB.- There is no server to check, so submitting skips that. Any change to the script of a live app (code, tools, parameters,
network, permissions, entitlements, cards, webSearch, server, settings, setup, windows, bundle, files) goes back to review, andversiongoes up.
API
All paths are on this server. No sign-in. Responses are cached for 5 minutes. CORS allows any origin.
| Request | Does |
|---|---|
GET /v1/services | Lists live modules: { "version": 1, "modules": [ … ] }. Optional ?category= (exact match) and ?q= (words to find in the text). |
GET /v1/services/{id} | One live module, or 404. |
GET /v1/services/schema | The JSON Schema for a module. |
POST /v1/services | Publishes a module (the JSON body). Returns an edit token. |
PUT /v1/services/{id} | Replaces a module. Needs the edit token. |
DELETE /v1/services/{id} | Removes a module. Needs the edit token. |
GET /v1/services/{id}/status | Returns { "status": "pending" | "live" | "rejected", "note": "…" }. Needs the edit token. |
The edit token goes in the header Authorization: Bearer <token>. A wrong or missing token gets 401.
Publish
curl -X POST /v1/services \ -H "Content-Type: application/json" \ -d @acme.json # 201 { "id": "acme", "status": "pending", "editToken": "jsm_…" }
The module is checked against the schema. Also, server.url and token.page have to be https, the id can’t be taken, and server.url has to answer within 5 seconds (any status counts; private and local addresses are refused). A new module is pending until the operator approves it, and only live modules are listed. Save the editToken: it is shown once.
A server operator can give someone a publisher key for a limited time. Send it as Authorization: Bearer jpk_… on the POST, and the module goes live without review, with a higher limit per hour. An invalid, expired or revoked key gets 401.
| Status | Meaning |
|---|---|
201 | Accepted and waiting for review. |
400 | { "error", "problems": [ … ] }, one sentence per problem. |
409 | The id is taken. |
413 | The file is over 64 KB. |
429 | Too many from this address: 5 an hour, and 10 waiting for review. Retry-After says when to try again. |
Update and remove
curl -X PUT /v1/services/acme \ -H "Authorization: Bearer jsm_…" \ -H "Content-Type: application/json" \ -d @acme.json
Send the whole module. The id has to stay the same, and version goes up by itself. If you only change text (blurb, about, abilities, category, symbol, color, token name or steps), a live module stays live. If you change the name, publisher, server, sign-in (auth or oauth) or token page, it goes back to pending, and the approved version stays listed until the change is approved. A rejected module has a note in its status; fix it with a PUT.
Try it
Add to Jade link
Host your module file on https, then use this link on a website or in a README. It opens Jade and shows the module before anything is added.
<a href="jade://module?url=…">Add to Jade</a>
Publish to this catalog
Sends the JSON to POST /v1/services. You get an edit token if it is accepted.
Catalog
Loading…