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

# AI Instructions API

> Read, replace, and clear team-wide global and AI SRE Markdown instructions with the beta public REST API.

> [!WARNING]
>
> This API is in beta and may change without notice. Breaking or unstable changes are possible.

Manage two team-wide instruction surfaces at `https://api.rootly.com/v1/ai/sre/instructions`:

* `global`: guidance for every supported AI feature.
* `sre`: extra guidance for AI SRE investigations.

See [AI SRE instructions](https://docs.rootly.com/ai/ai-sre/instructions.md) for guidance on writing instructions.

## Access

Use a Personal or Global API key in `Authorization: Bearer YOUR_API_KEY`. Global API keys (`kind: organization`) are accepted, use their assigned roles and key's team, and receive the same success statuses listed below when authorized. Missing permissions return 403; Global keys aren't rejected just for their kind. Team API keys are rejected with 404. OAuth tokens return 403 with the title `API key required.`. AI instructions must be enabled for your team; accessing `sre` also requires AI SRE to be enabled.

Global reads require `view_configure_ai`. SRE reads require `view_configure_ai` or `configure_ai_sre_rules`. Global writes require permission to configure AI; SRE writes also allow permission to configure AI SRE rules.

Global writes require an Incident Response Owner or Admin role and an Incident Response seat. SRE API reads and writes also allow Incident Response Owners and Admins, or On-Call Admins, without an Incident Response seat through `configure_ai_sre_rules`. The On-Call Admin grant requires On-Call to be enabled for the team. These grants also require AI features to be enabled.

The web app has an additional access gate: its AI SRE instructions page and save actions require `view_configure_ai`, so managing instructions there still requires an Incident Response seat. The API does not apply that extra UI gate to SRE writes.

Index returns only surfaces you can read, hides SRE when disabled, and returns 403 if you have no readable surfaces. All operations use the API key's team.

Personal and Global keys are bound to the team selected when the key is created; these endpoints use that stored team, not a team-selection header or parameter. A Global key acts as its service user with the key's assigned roles, not its human creator: global-instruction writes check that service user's membership for the Incident Response Owner/Admin role and seat (the seat check means the Incident Response role isn't **No Access**).

## Operations

Replace `{surface}` with `global` or `sre`; unknown surfaces return 404.

| Method | Path | Success |
| - | - | - |
| GET | `/v1/ai/sre/instructions` | 200: `data` array of available instructions |
| GET | `/v1/ai/sre/instructions/{surface}` | 200: resource; 404 when no instruction or effective default exists |
| PUT or PATCH | `/v1/ai/sre/instructions/{surface}` | 200: saved resource; 204 when cleared |
| DELETE | `/v1/ai/sre/instructions/{surface}` | 204: slot cleared, including when already empty |

## Replace Instructions

PUT and PATCH replace the entire Markdown body. Send a string of up to 20,000 characters. Leading and trailing whitespace is trimmed.

```bash theme={null}
curl --request PUT 'https://api.rootly.com/v1/ai/sre/instructions/sre' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
    "data": {
      "type": "ai_instructions",
      "attributes": {"body": "Check deploys first."}
    }
  }'
```

Example response (200):

```json theme={null}
{
  "data": {
    "id": "019a6500-0000-7000-8000-000000000002",
    "type": "ai_instructions",
    "attributes": {
      "surface": "sre",
      "body": "Check deploys first.",
      "source": "custom",
      "updated_at": "2026-11-09T12:00:00Z"
    }
  }
}
```

Only `body` is writable. Extra `data` or attribute keys, a wrong `type`, a missing body, or a non-string body (including null) return 400. Validation failures return 422.

## Clear Instructions

Send DELETE without a body, or PUT/PATCH with this payload:

```json theme={null}
{
  "data": {
    "type": "ai_instructions",
    "attributes": {"body": ""}
  }
}
```

Both return 204 without a response body. Whitespace-only text also clears the slot.

## Global Best-Practice Defaults

When Rootly's best-practice mode is active, GET and index return the effective global default text, even if no saved instruction exists. The read-only `source` is `best_practice` or `custom`.

For an unsaved default, `id` and `updated_at` are null. The `body` contains Rootly's default Markdown, rather than an empty string.

Saving global text that contains more than whitespace switches the source to `custom`. Clearing removes the saved slot. If best-practice mode is enabled, subsequent reads return the default again; clearing doesn't disable that mode.


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