> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecadence.gg/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
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 theme={null}
{
  "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:

```bash theme={null}
-H "x-cadenceplus-space-id: YOUR_SPACE_ID"
```

`spaces/list` returns the spaces you can use. See [Spaces](https://docs.usecadence.gg/teams/spaces.md).

## TypeScript

The procedures are defined with [oRPC](https://orpc.dev) in `packages/contracts/src/rpc.ts`. Inside the Cadence repository you can call them with a fully typed client:

```ts theme={null}
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

> [card] [Authentication](https://docs.usecadence.gg/api/authentication.md)
>
> Get a token and send it with each call.

> [card] [Errors](https://docs.usecadence.gg/api/errors.md)
>
> The error shape and what to do about each code.

> [card] [Streaming](https://docs.usecadence.gg/api/streaming.md)
>
> Follow a chat live as the bot works.

> [card] [Webhooks](https://docs.usecadence.gg/api/reference/webhooks.md)
>
> 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.