AI Instructions API

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

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

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):

{
  "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:

{
  "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.