> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Custom Instructions API

The Custom Instructions API provides full create, read, update, and delete access to your AI Agent's [Custom Instructions](/docs/automation/custom-instructions) - system-level behavioral guidance that the Agent follows across conversations. Use it to manage instructions programmatically instead of only through the dashboard.

Download full OpenAPI spec

Each Custom Instruction is identified by an `id` and can be either enabled (`true`, active) or disabled (`false`, inactive). New instructions default to inactive, so creating one does not change the Agent's behavior until you enable it.

## Endpoints

Five endpoints are available:

* **List custom instructions** (`GET /v2/custom-instructions/`): Returns the Agent's custom instructions, enabled or not, in cursor-paginated pages ordered by `id`.
* **Create a custom instruction** (`POST /v2/custom-instructions/`): Creates a new instruction. New instructions default to inactive (`enabled: false`); enable one by setting `enabled: true` on create or in a later update.
* **Get a custom instruction** (`GET /v2/custom-instructions/{custom_instruction_id}`): Returns a single instruction by its `id`.
* **Update a custom instruction** (`PATCH /v2/custom-instructions/{custom_instruction_id}`): Partially updates an instruction. Only the fields included in the request body are changed; omitted fields keep their existing values. To clear `notes`, send an empty string (`""`); omitting it leaves the existing value unchanged.
* **Delete a custom instruction** (`DELETE /v2/custom-instructions/{custom_instruction_id}`): Deletes an instruction by its `id`.

## Fields

| Field                | Type           | Description                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | string         | The unique identifier for the custom instruction. Read-only.                                                                                                                                                                                                                                                                                                                                                                             |
| `title`              | string         | Display name for the instruction, unique per Agent. Up to 150 characters.                                                                                                                                                                                                                                                                                                                                                                |
| `text`               | string         | The instruction content - the rule the Agent should follow. Up to 300 characters.                                                                                                                                                                                                                                                                                                                                                        |
| `enabled`            | boolean        | Whether the instruction is enabled. Defaults to `false`, which means inactive.                                                                                                                                                                                                                                                                                                                                                           |
| `notes`              | string \| null | Internal notes about the instruction. Not shown to the Agent.                                                                                                                                                                                                                                                                                                                                                                            |
| `availability_rules` | string \| null | Availability rule gating which end users the instruction applies to, written as a `v("<variable_name>")`-based rule-expression string (for example `all(equals(v("plan"), "premium"))`). `null` when no rule is set. On create and update, an invalid rule (an unknown variable name, or a malformed or unsupported expression) returns `400`; send `null` to clear the rule, or omit it on update to leave the existing rule unchanged. |

## Pagination

The list endpoint is cursor-paginated. Use the `limit` query parameter to set the page size, from `1` to `100`; omit it to use the default of `25`. To page through results, read `meta.next_page_url` from the response and replay it unchanged to fetch the next page. `next_page_url` is `null` on the last or empty page.

## Conflicts

Creating or updating an instruction can return a `409 Conflict` for one of two reasons:

* **Duplicate title** (`duplicate_resource`): The `title` is already used by another custom instruction. Titles are unique per Agent.
* **Enabled-instruction limit** (`conflict`): Enabling the instruction would exceed the Agent's limit on the number of live instructions.

## Authentication

Requests are authenticated with a Bearer API key. See [Authentication](/reference/introduction/authentication) for details on generating and using API keys.