Create Instruction API Definition
The Create Instruction API enables you to create reusable sets of behavioral guidelines that shape how AI agents reason, respond, and interact with users and tools. Instructions are fundamental to ensuring that agents operate within enterprise policies, follow best practices, and maintain a consistent tone and personality across all interactions.
Organizations use this API to define standardized operational protocols, enforce compliance with regulatory requirements, and customize agent behavior to align with specific business use cases, such as customer support, financial analysis, or internal workflow automation.
Create Instruction Request and Response
To create an instruction, send a POST request to /v2/instructions. You specify the following parameters in the request body:
name(string, required): A human-readable name for the instruction.description(string, optional): A detailed description of the instruction's purpose and intended use.template(string, required): The instruction content in Apache Velocity Template Language, which allows for dynamic variable substitution.enabled(boolean, optional): Whether the instruction should be enabled upon creation (defaults totrue).metadata(object, optional): Arbitrary metadata for tracking, versioning, or categorization.
The response includes the full definition of the newly created instruction, including system-generated fields such as id, version, created_at, and updated_at.
Example Request
1
Example Response
1
Error Responses
The API returns standard HTTP error codes with detailed error information:
| HTTP Code | Error Code | Description |
|---|---|---|
| 400 | invalid_request | Missing required fields or malformed request structure |
| 401 | unauthorized | Invalid or missing API key |
| 403 | forbidden | Insufficient permissions for creating instructions |
| 409 | conflict | An instruction with the same name already exists |
| 429 | rate_limit_exceeded | Instruction creation rate limit exceeded |