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?

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:

  1. Write the module file (JSON, a text format). Copy the example under Module format and change the values.
  2. Send it to this server. Either paste it into the Publish form below, or run the curl command in API (curl is a tool that sends web requests, and it is already on Mac and Linux).
  3. 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.
  4. 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

  • 400 The file has a mistake. The answer lists each one in plain words.
  • 401 The edit token is missing or wrong.
  • 404 There is no module with that id.
  • 409 That id is already taken. Pick another.
  • 429 Too 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
}
FieldRequiredRules
idyes1–48 characters: a-z 0-9 . _ -. Must be unique. schema is reserved.
nameyesUp to 40 characters.
publisheryesWho makes the service. Up to 80 characters.
categoryyesFree text, like “Developer” or “Email”. The catalog groups by it.
blurbyesOne line, up to 140 characters.
aboutnoUp to 1000 characters.
symbolyesAn SF Symbol name. Unknown names show a puzzle piece.
colorno#RRGGBB
server.urlyeshttps only, with no username or password.
server.headernoHeader that carries the token. Default: Authorization as a bearer token. Letters, digits and -.
server.authnotoken (default) or oauth. With oauth the person signs in on the service’s own page and there is no token.
server.oauthnoOnly 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.nameyes, unless oauthFor example “API key”.
token.pageyes, unless oauthhttps page where the token is made.
token.stepsyes, unless oauth1–12 steps, up to 300 characters each.
abilitiesnoUp to 12 short phrases.
versionnoWhole number. Raise it when the file changes.
verifiednofalse 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).
whatsNewnoUp 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
}

API

All paths are on this server. No sign-in. Responses are cached for 5 minutes. CORS allows any origin.

RequestDoes
GET /v1/servicesLists 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/schemaThe JSON Schema for a module.
POST /v1/servicesPublishes 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}/statusReturns { "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.

StatusMeaning
201Accepted and waiting for review.
400{ "error", "problems": [ … ] }, one sentence per problem.
409The id is taken.
413The file is over 64 KB.
429Too 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.

Publish to this catalog

Sends the JSON to POST /v1/services. You get an edit token if it is accepted.

Catalog

Loading…