Custom Instructions API

The Custom Instructions API provides full create, read, update, and delete access to your AI Agent’s Custom Instructions - system-level behavioral guidance that the Agent follows across conversations. Use it to manage instructions programmatically instead of only through the dashboard.

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 for details on generating and using API keys.