---
title: "Update instruction"
method: PATCH
path: "/v2/instructions/{instruction_id}"
tags: ["Instructions"]
---

# Update instruction

`PATCH /v2/instructions/{instruction_id}`

Updates an existing instruction's template, metadata, and configuration. Updated templates may include Velocity variables such as `$tools` or metadata references. Each update creates a new version. Agents continue to use existing versions until you change them explicitly.

:::info Version Management
Agents referencing a specific version continue to use it until updated. Agents without a pinned version always use the latest.
:::

## Disable an instruction

Use this endpoint to disable an instruction without deleting it.

:::warning
Disabling an instruction prevents it from being added to new agents, but agents already using it continue to operate normally.
:::

## Path parameters

- `instruction_id` string, required — The unique identifier for an instruction.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- UpdateInstructionRequest — Request object for updating an existing initial instruction.
  - `type` string, required — The type of instruction to update.
  - `name` string — The human-readable name of an instruction.
  - `description` string — A detailed description of what this instruction does.
  - `template` string — 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`
  - `template_type` 'velocity' | 'text' — 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.
  - `metadata` object — Arbitrary metadata associated with the instruction.
  - `enabled` boolean — Whether the instruction is enabled.

## Response `200`

The updated instruction.

- Instruction — An initial instruction that provides guidance to the agent before user messages.
  - `id` string, required — The unique identifier for an instruction.
  - `type` string, required — The type of instruction.
  - `name` string, required — The human-readable name of an instruction.
  - `description` string — 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.
  - `template` string, 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`
  - `version` integer, required — The version identifier for this instruction. The version increments automatically when the instruction is updated.
  - `metadata` object — Arbitrary metadata associated with the instruction.
  - `enabled` boolean, required — Whether the instruction is currently enabled and available for use.
  - `created_at` string, date-time — Timestamp when the instruction was created.
  - `updated_at` string, date-time — Timestamp when the instruction was last updated.

## Other responses

- `400` — Instruction update request was malformed or contains invalid content.
- `403` — Permissions do not allow updating this instruction.
- `404` — Instruction not found.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/versions/fca567a46b3a/schema)