# bots

Canonical page: https://docs.ovok.com/settings-and-features/features/bots

Lets the project run Bots: server-side code that Ovok executes on request, when data changes, or on a schedule.

| | |
| --- | --- |
| Type | Project feature |
| Value in `features` | `bots` |
| Change with | `PATCH /v1/projects/me/features` (replaces the whole list) |
| Who can change it | Project admin. Any practitioner can read the list. |
| On for new projects | Yes |
| Other features that need it | [cron](/settings-and-features/features/cron) and Subscriptions that deliver to a Bot |
| When off | Bots cannot be executed or deployed |

## What it enables [#what-it-enables]

| Capability | Route |
| --- | --- |
| Run a Bot by id | [`POST /fhir/R4/Bot/:id/$execute`](/primitives/execute-bot-by-id) |
| Run a Bot by identifier | [`POST /fhir/R4/Bot/$execute?identifier=`](/primitives/execute-bot-by-identifier) and `POST /v1/bots?identifier=` |
| Deploy Bot code | [`POST /fhir/R4/Bot/:id/$deploy`](/primitives/deploy-bot) |
| Run a Bot when data changes | A [Subscription](/api/fhir/r4/subscription) whose channel endpoint is `Bot/<id>` |
| Run a Bot on a schedule | Together with [cron](/settings-and-features/features/cron) |

## Turn it on [#turn-it-on]

Read the current list, add `bots`, and send the whole list back. `PATCH` replaces the list, so any feature you leave out is turned off.

```bash
curl --request PATCH \
  --url 'https://api.sandbox.ovok.com/v1/projects/me/features' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"features":["bots","cron","email","transaction-bundles","websocket-subscriptions"]}'
```

The response is `{ "features": [...] }`, the list as stored.

## What callers see when it is off [#what-callers-see-when-it-is-off]

| Request | Status | Response |
| --- | --- | --- |
| `POST /fhir/R4/Bot/:id/$execute` | `400` | An `OperationOutcome` saying `Bots not enabled` |
| `POST /fhir/R4/Bot/:id/$deploy` | `400` | `Bots not enabled` |
| `POST /v1/bots?identifier=` | `400` | `Failed to execute bot.` |

A Subscription that delivers to a Bot, and a scheduled Bot, simply do not run.

## Gotchas [#gotchas]

- **The check is made against the project the Bot belongs to.** A Bot lives in the project where it was created, so that project needs the feature.
- **Scheduled Bots keep firing after you turn it off, and fail.** Schedules that already exist are not removed; each run is refused with `Bots not enabled`. Remove a Bot's schedule if you want it to stop.
- **The feature is necessary, not sufficient.** A Bot also needs a supported runtime. One that does not have one fails with `Unsupported bot runtime`.
- **Sending email from a Bot is a separate feature.** Add [email](/settings-and-features/features/email) as well.
- **`POST /v1/bots?identifier=` needs exactly one match.** No Bot, or more than one, with that identifier answers `400`, and a successful run answers `201`.
- **Projects created before this was a default can lack it.** Call `GET /v1/projects/me/features` and check.

## Related [#related]

- [cron](/settings-and-features/features/cron)
- [email](/settings-and-features/features/email)
- [Execute a Bot by id](/primitives/execute-bot-by-id)
- [Deploy a Bot](/primitives/deploy-bot)
