Update a template

Update a Forward template by ID.

POST /api/v1/forward/templates/{template_id}

Updates mutable template fields. Fields omitted from the request are left unchanged. Array fields such as tools, mcp_servers, and skills are replaced as a whole when provided.

Headers

Header	Required	Description
Authorization	Yes	Bearer <PAT>
Content-Type	Yes	application/json
Idempotency-Key	No	Optional idempotency key for unsafe requests.

Path parameters

Parameter	Type	Required	Description
template_id	string	Yes	Forward Template ID.

Body parameters

Parameter	Type	Required	Description
name	string	No	New template name.
description	string	No	New template description.
model	string	No	New model identifier.
system	string	No	New system prompt.
tools	array	No	Replaces the tool configuration list.
mcp_servers	array	No	Replaces the MCP server list.
skills	array	No	Replaces the Skill binding list.
multiagent	object	No	Replaces the Managed Agents configuration.
environment_id	string|null	No	Replaces the default Environment ID. null or empty string clears it.
vault_ids	array|null	No	Replaces default Vault IDs. null clears the list.
files	object|null	No	Replaces default file resources. null clears the map.
environment_variables	object | string|null	No	Replaces default session environment variables. null clears them.
metadata	object	No	Merge updates custom metadata.

Nested configuration objects

tools, mcp_servers, and skills are array fields. When provided in an update request, each array replaces the previous array as a whole.

File resources

files is a map keyed by File ID. Do not include file_id, id, or resource_id inside each item. Forward injects mount_path when creating Sessions.

Field	Type	Required	Description
enabled	boolean	No	Defaults to true. false disables the inherited file in Identity Config.

Tools array

Each tools[] item is selected by type.

Field	Type	Applies to	Description
type	string	All	Required. agent_toolset_20260401, mcp_toolset, or custom.
enabled_tools	array	agent_toolset_20260401	Convenience allowlist. A non-empty list enables only these built-in tools.
disallowed_tools	array	agent_toolset_20260401	Convenience denylist. Compiles to disabled tool configs.
configs	array	agent_toolset_20260401, mcp_toolset	Per-tool enablement and permission policy.
mcp_server_name	string	mcp_toolset	Required. Must match an item in mcp_servers[].name.
name	string	custom	Required custom tool name. Must not conflict with a built-in tool.
description	string	custom	Required custom tool description.
input_schema	object	custom	Required JSON Schema. input_schema.type must be object.

Built-in tool names are Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, and DeliverArtifacts.

Tool config

tools[].configs[] items use this shape.

Field	Type	Required	Description
name	string	Yes	Tool name. Built-in tool name for agent_toolset_20260401; MCP tool name for mcp_toolset.
enabled	boolean	No	false hides and denies the tool. true explicitly enables it.
permission_policy	object	No	Runtime permission behavior.

Permission policy

Field	Type	Required	Description
type	string	Yes	always_allow, always_ask, or always_deny.

MCP servers

Field	Type	Required	Description
type	string	No	Currently only http. Omitted values are treated as HTTP MCP servers in Effective Config.
name	string	Yes	Unique MCP server name within the Template. Referenced by tools[].mcp_server_name.
url	string	Yes	Streamable HTTP MCP endpoint URL.

Skills

Field	Type	Required	Description
type	string	Yes	custom or qoder.
skill_id	string	Yes	Skill ID.
version	string	No	Skill version. Omitted values use the latest version.
enabled	boolean	No	Defaults to true. false prevents the skill from being included in the compiled agent config.

Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/templates/tmpl_support' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support assistant v2",
    "environment_id": "env_support_v2",
    "vault_ids": ["vault_crm", "vault_billing"],
    "environment_variables": {
      "BASE_MODE": "support_v2"
    }
  }'

Example response

HTTP 200 OK

{
  "type": "template",
  "id": "tmpl_support",
  "name": "Support assistant v2",
  "description": "Handles pre-sales and after-sales support",
  "status": "active",
  "model": "ultimate",
  "system": "You are a helpful support assistant.",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "multiagent": null,
  "environment_id": "env_support_v2",
  "vault_ids": ["vault_crm", "vault_billing"],
  "files": {},
  "environment_variables": {
    "BASE_MODE": "support_v2"
  },
  "metadata": {},
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:30:00Z"
}

Response fields

Returns the updated Template object.

Errors

HTTP	Type	Trigger
400	invalid_request_error	Invalid request body or unsupported field value.
401	authentication_error	PAT invalid or expired.
404	not_found_error	Template or referenced resource does not exist.
409	conflict_error	Template name already exists.

Notes

• Archived templates cannot be updated.
• Updating session defaults does not mutate existing sessions.

Related

Get a template

Clone a template