API introduction

Call the same procedures the Cadence app uses.

Everything the Cadence web, desktop and mobile apps do goes through one API. You can call it too: create bots, send them messages, read their replies, manage routines and invite people.

The API is a set of procedures. Each procedure has a path like bots/list or threads/send, takes one JSON input, and returns one JSON output.

​

The shape of a call

Every procedure is a POST to /rpc/ plus its path. The input goes in a json field. The output comes back in a json field.

export CADENCE_URL="https://app.example.com"   # the address you sign in at
export CADENCE_TOKEN="..."                     # see Authentication

curl -s "$CADENCE_URL/rpc/bots/get" \
  -H "Authorization: Bearer $CADENCE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json": {"botId": "YOUR_BOT_ID"}}'

{
  "json": {
    "id": "YOUR_BOT_ID",
    "name": "Ada",
    "instructions": "You answer customer questions for our store.",
    "computerMode": "team",
    "pinned": false,
    "...": "..."
  },
  "meta": []
}

Three rules cover every procedure:

1. Always POST to $CADENCE_URL/rpc/<path>, where a dot in the procedure name becomes a slash (computer.status is /rpc/computer/status).
2. Wrap the input in json. A procedure with no input takes {} as the body.
3. Read the result from json. The meta array describes values JSON cannot carry natively, such as dates. You can ignore it when you only need plain values.

​

Spaces

Requests act inside one space. Without a hint, the API uses your default space. To act in another space you belong to, send its id in the x-cadenceplus-space-id header:

-H "x-cadenceplus-space-id: YOUR_SPACE_ID"

spaces/list returns the spaces you can use. See Spaces.

​

TypeScript

The procedures are defined with oRPC in packages/contracts/src/rpc.ts. Inside the Cadence repository you can call them with a fully typed client:

import { createORPCClient } from "@orpc/client";
import { RPCLink } from "@orpc/client/fetch";
import type { ContractRouterClient } from "@orpc/contract";
import type { AppContract } from "@cadenceplus/contracts";

const link = new RPCLink({
  url: `${process.env.CADENCE_URL}/rpc`,
  headers: { authorization: `Bearer ${process.env.CADENCE_TOKEN}` },
});
const cadence: ContractRouterClient<AppContract> = createORPCClient(link);

const bots = await cadence.bots.list();

From any other language, use plain HTTP as shown above.

​

What’s in the reference

Authentication

Get a token and send it with each call.

Errors

The error shape and what to do about each code.

Streaming

Follow a chat live as the bot works.

Webhooks

Start a bot’s routines from another system.

The procedure pages cover the ones most integrations need. The full list, with every field, lives in packages/contracts/src/rpc.ts.