Custom Instructions API now generally available
The Custom Instructions API is now generally available. It provides programmatic create, read, update, and delete access to an AI Agent’s Custom Instructions - the system-level behavioral guidance the Agent follows across conversations - so instructions can be managed through code and version control instead of only through the dashboard.
API endpoints
Five REST endpoints are available:
- List custom instructions (
GET /v2/custom-instructions/): Returns the Agent’s custom instructions, both live and inactive, in cursor-paginated pages. - Create a custom instruction (
POST /v2/custom-instructions/): Creates a new instruction, which defaults to inactive. - Get a custom instruction (
GET /v2/custom-instructions/{custom_instruction_id}): Returns a single instruction by itsid. - Update a custom instruction (
PATCH /v2/custom-instructions/{custom_instruction_id}): Partially updates an instruction; only the fields in the request body change. - Delete a custom instruction (
DELETE /v2/custom-instructions/{custom_instruction_id}): Deletes an instruction by itsid.
Each instruction can also carry an optional availability_rules expression that gates which end users it applies to — set it on create or update, and it’s returned on reads.
Get started
See the reference docs for full endpoint, field, and authentication details:
- Custom Instructions API reference for endpoint details, fields, pagination, authentication, and error codes.