Update a template - Qoder CN Series - Alibaba Cloud Documentation Center

Update a Forward template by ID.

Request 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.

Request body

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 an 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	Merges updates into custom metadata.

Nested configuration objects

tools, mcp_servers, and skills are all array fields; when supplied in an update, each array replaces the previous one in full.

Files

files is a map keyed by File ID. Do not include file_id, id, or resource_id inside an entry. Forward injects mount_path automatically when a session is created.

Field	Type	Required	Description
`enabled`	boolean	No	Omitted is treated as `true`. In an Identity Config, set it to `false` to disable an inherited file.

tools[] items

Each tools[] entry chooses its shape via the type field.

Field	Type	Applies to	Description
`type`	string	All	Required. One of `agent_toolset_20260401`, `mcp_toolset`, or `custom`.
`enabled_tools`	array	`agent_toolset_20260401`	Convenience allowlist; a non-empty array enables only the listed built-in tools.
`disallowed_tools`	array	`agent_toolset_20260401`	Convenience denylist; compiled into 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 a `mcp_servers[].name`.
`name`	string	`custom`	Required. Custom tool name; must not collide with a built-in tool.
`description`	string	`custom`	Required. Description of the custom tool.
`input_schema`	object	`custom`	Required JSON Schema. `input_schema.type` must be `object`.

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

Tool config

Each entry in tools[].configs[] uses the following shape.

Field	Type	Required	Description
`name`	string	Yes	Tool name; use the built-in tool name for built-ins and the MCP tool name for MCP toolsets.
`enabled`	boolean	No	`false` hides and rejects the tool; `true` enables it explicitly.
`permission_policy`	object	No	Runtime permission behavior.

Permission policy

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

MCP servers

Field	Type	Required	Description
`type`	string	No	Only `http` is currently supported. When omitted, the Effective Config treats the entry as an HTTP MCP server.
`name`	string	Yes	MCP server name that is unique within the Template and referenced by `tools[].mcp_server_name`.
`url`	string	Yes	Streamable HTTP MCP endpoint URL.

skills[] items

Field	Type	Required	Description
`type`	string	Yes	Either `custom` or `qoder`.
`skill_id`	string	Yes	Skill ID.
`version`	string	No	Skill version. Omit to use the latest version.
`enabled`	boolean	No	Omitted is treated as `true`. `false` excludes the skill from the compiled Agent config.

Example request

curl -s -X POST 'https://api.qoder.com.cn/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.