v3

latestOpenAPI 3.0.02026-08-081996601.2 MB

Instructions

Get instruction

Returns the full definition of an instruction, including its template, metadata, enabled status, and version. Instruction templates may contain Velocity expressions that reference tools and metadata. If no version is specified, the platform returns the latest version.

get/v2/instructions/{instruction_id}

Path parameters

instruction_idstring required

The unique identifier for an instruction.

Example:ins_customer_support_init

The unique identifier of the instruction to retrieve.

Query parameters

versioninteger

Example:1

The specific version of the instruction to retrieve. If not specified, the platform returns the latest version.

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Response

The requested instruction details.

idstring required

The unique identifier for an instruction.

typestring required

The type of instruction.

namestring required

The human-readable name of an instruction.

descriptionstring

A detailed description of what this instruction does.

template_type'velocity' | 'text' required

The templating engine used to render the instruction's template.

velocity: render the template with the Velocity engine, substituting agent, session, and tool variables.
text: use the template verbatim as plain text, with no variable substitution.

templatestring required

The instruction template content. How it is rendered depends on the sibling template_type.

When template_type is text, the content is used verbatim as the instruction and no variables are substituted.

When template_type is velocity, the content is rendered with the Velocity engine and the following variables are available:

$agent.name - Agent name
$agent.key - Agent key
$agent.metadata - Agent metadata map
$session.key - Session key
$session.metadata - Session metadata map (includes user-provided context from test/runtime)
$currentDate - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z")
$tools - List of tool maps, each with name and description fields

Example: You are a helpful customer support agent. Agent: $agent.name. Today is $currentDate. Available tools: #foreach($tool in $tools)${tool.name}#if($foreach.hasNext), #end#end

versioninteger required

The version identifier for this instruction. The version increments automatically when the instruction is updated.

metadataobject

Arbitrary metadata associated with the instruction.

enabledboolean required

Whether the instruction is currently enabled and available for use.

created_atstring date-time

Timestamp when the instruction was created.

updated_atstring date-time

Timestamp when the instruction was last updated.

Example response

{
  "id": "ins_customer_support_init",
  "type": "initial",
  "name": "Customer Support Initial Instruction",
  "template_type": "velocity",
  "template": "You are an expert customer support agent for $agent.name. Available tools: #foreach($tool in $tools)${tool.name}#if($foreach.hasNext), #end#end",
  "version": 1
}