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

# Routines

> Create and manage work a bot does on its own.

See [Routines](https://docs.usecadence.gg/work/routines.md) for how routines behave.

## routines/list

`POST /rpc/routines/list` returns a bot's routines.

**botId** `string` *required*

The bot.

## routines/create

`POST /rpc/routines/create` creates a routine. It needs at least one trigger: `crons`, `webhookEnabled`, `githubEnabled`, `messageProvider` or `watch`.

**botId** `string` *required*

The bot that runs it.

**name** `string` *required*

Up to 80 characters.

**prompt** `string` *required*

What the bot should do each time.

**crons** `string[]` (default: \[])

Cron expressions, like `0 9 * * 1-5`.

**timezone** `string` (default: UTC)

An IANA time zone, like `Africa/Lagos`.

**active** `boolean` (default: false)

Whether it runs. New routines start inactive.

**notify** `boolean` (default: true)

Notify when a run finishes.

**webhookEnabled** `boolean` (default: false)

Run when the bot's [webhook](https://docs.usecadence.gg/api/reference/webhooks.md) is called.

**githubEnabled** `boolean` (default: false)

Run on GitHub events.

**messageProvider** `string | null`

Run when a message arrives from this channel, like `slack`.

**watch** `object | null`

A change trigger. Cannot be combined with `crons`. See below.

**runAt** `string`

An ISO time for a one-time run.

**maxMinutes** `number | null`

Stop a run after 5 to 240 minutes. Null means no limit.

**overlap** `"skip" | "queue"` (default: skip)

What to do when the last run is still going.

**runOnStartup** `boolean` (default: false)

Catch up a missed run when the worker starts.

**modelProvider, modelId, thinkingLevel** `string | null`

Run on a different model from the bot's. Set provider and model together.

**attachmentIds** `string[]`

Up to 50 files to attach to every run.

```bash theme={null}
curl -s "$CADENCE_URL/rpc/routines/create" \
  -H "Authorization: Bearer $CADENCE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json": {
        "botId": "YOUR_BOT_ID",
        "name": "Morning orders",
        "prompt": "Summarize yesterday'\''s orders and post the totals.",
        "crons": ["0 9 * * 1-5"],
        "timezone": "Africa/Lagos",
        "active": true
      }}'
```

### The watch object

**watch.kind** `"files" | "command" | "tool"` *required*

What to check.

**watch.paths** `string[]`

For `files`: up to 20 paths on the bot's computer.

**watch.command** `string`

For `command`: a shell command whose output is compared.

**watch.tool** `string`

For `tool`: a read-only integration tool.

**watch.args** `object`

For `tool`: fixed arguments.

**watch.track** `string[]`

For `command` and `tool`: up to 5 fields that mark a change in a JSON list.

**watch.everyMinutes** `number` (default: 15)

How often to check, 5 to 1440.

**watch.loud** `boolean` (default: false)

Post "No changes" in chat on quiet checks.

## routines/update

`POST /rpc/routines/update` takes a `routineId` and any of the fields above. Null clears `watch`, `maxMinutes` and the routine's own model.

## Other routine procedures

| Procedure | Input | Effect |
| - | - | - |
| `routines/testRun` | `{ routineId }` | Runs it now. Returns `runId`. |
| `routines/history` | `{ routineId, before? }` | Past runs, newest first. |
| `routines/cancelRun` | `{ routineId, runId }` | Stops a run in progress. |
| `routines/remove` | `{ routineId }` | Deletes the routine. |


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