Update a template

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 or SAT>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Optional idempotency key for unsafe requests.
`X-Qoder-Beta`	Required for Browser Use	Must be `browser-use-2026-07-14` when the updated `tools` contain the Browser Use toolset.

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\|object	No	New model identifier, or an object with the model ID and optional `effort`, `speed`, and `context_window` fields.
`system`	string	No	New system prompt.
`max_tool_rounds`	integer\|null	No	Maximum tool-call rounds per Turn. Must be a positive integer. Omission preserves the current value; `null` clears the explicit limit and uses the platform default.
`tools`	array	No	Replaces the tool configuration list.
`managed_tool_config`	object\|null	No	Replaces the complete Forward managed-capability baseline. `null`, `{}`, or `enabled_tools: []` clears it.
`mcp_servers`	array	No	Replaces the MCP server list.
`skills`	array	No	Replaces the Skill binding list.
`multiagent`	object\|null	No	Replaces the Multi-agent configuration. `null` clears it; omission preserves the current configuration.
`environment_id`	string\|null	No	Replaces the default Environment ID. `null` or empty string clears it.
`vaults`	object\|null	No	Replaces the complete default Vault configuration. `null` clears it.
`files`	object\|null	No	Replaces default file resources. `null` clears the map.
`github_repositories`	object\|null	No	Replaces default GitHub repositories. `null` or an empty object clears all bindings.
`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.

Model

model accepts either a model ID string or an object containing the model ID and optional tuning fields.

Field	Type	Required	Description
`id`	string	Yes	Model identifier. Use the List models endpoint to discover available values.
`effort`	string	No	Reasoning effort: `none`, `low`, `medium`, `high`, `xhigh`, or `max`. Check the model's `efforts` list for supported values.
`context_window`	integer	No	Requested context window in tokens. Choose a positive integer from the model's `available_context_windows`.
`speed`	string	No	Inference speed: `standard` or `high`. Defaults to `standard` when omitted. See the `speed` array returned by List models for supported values.

Vaults

vaults is a map keyed by Vault ID. Each entry accepts an optional enabled boolean; omission is equivalent to true. Supplying vaults replaces the complete existing configuration, while null clears it.

{
  "vaults": {
    "vault_019f18f2761b": { "enabled": true },
    "vault_019f18f2762c": { "enabled": true }
  }
}

Responses always return vaults in object form.

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.

GitHub repositories

github_repositories is a map keyed by a binding key. Each key must match [A-Za-z][A-Za-z0-9_-]{0,63}. At most 20 bindings are allowed, and normalized repository URLs and mount paths must be unique.

Field	Type	Required	Description
`url`	string	Yes	Absolute HTTPS repository URL. Userinfo, query, fragment, percent encoding, and backslashes are rejected; a trailing `.git` is removed during normalization.
`authorization_token`	string	Yes	Write-only repository access token. It is never echoed in responses. Maximum 8192 bytes; only ASCII letters, digits, and underscores are allowed.
`mount_path`	string	No	Normalized absolute mount path inside the Session, other than `/`. Defaults to `/data/workspace/<repository-name>`. Omitting the entire `github_repositories` field preserves the existing configuration.

Request shape	Semantics
Field omitted	Preserves the current repository configuration.
`github_repositories: null`	Clears all bindings.
`github_repositories: {}`	Clears all bindings.
Non-empty object	Replaces the complete repository configuration.

Tools array

Each tools[] item is selected by type.

Field	Type	Applies to	Description
`type`	string	All	Required. `agent_toolset_20260401`, `browser_toolset_20260714`, `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.

Forward managed capabilities

managed_tool_config.enabled_tools is the complete set of Forward managed capabilities enabled by the Template. Forward provides the corresponding tool definitions; callers do not need to configure them again in tools. Supported selectors are schedule, create_forward_schedule, list_forward_schedules, delete_forward_schedule, and drive. schedule is shorthand for the Schedule capability bundle, equivalent to enabling create_forward_schedule, list_forward_schedules, and delete_forward_schedule together:

{
  "managed_tool_config": {
    "enabled_tools": ["schedule"]
  }
}

Bundle/Capability selectors such as schedule are used only for configuration; drive represents the full Drive capability. At runtime, a Session receives the corresponding Forward managed tools, which can be called independently. Template responses preserve schedule or drive from the request without rewriting them as execution tool names.

Request shape	Semantics
Field omitted	Preserves the current managed-capability baseline.
`managed_tool_config: null`	Clears all Forward managed capabilities.
`managed_tool_config: {}`	Clears all Forward managed capabilities.
`{ "enabled_tools": [] }`	Clears all Forward managed capabilities.
Non-empty `enabled_tools` array	Replaces the complete baseline with the array.

Unknown or duplicate selectors are rejected.

Browser Use (Beta)

Browser Use is currently a Beta feature. Its capabilities, limits, and API details may change. To enable browser capabilities for Sessions created from this Template, add the following toolset to tools:

{
  "type": "browser_toolset_20260714"
}

The request must also include this header:

X-Qoder-Beta: browser-use-2026-07-14

tools uses replacement semantics in the update API. To preserve existing toolsets, include them together with browser_toolset_20260714 in the new tools array.

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.

Multiagent

multiagent configures the current Template as a coordinator, declaring its delegable Agent roster and an optional Advisor.

Field	Type	Required	Description
`type`	string	Yes	Must be `coordinator`.
`agents`	array	Yes	Non-empty roster with up to 20 ordinary Agent entries (including `self`), plus one optional Advisor.

multiagent.agents[] accepts Template references such as {"type":"agent","template_id":"tmpl_research"} and {"type":"self"} for the coordinator itself. A Template reference may also include an optional name.

Field	Type	Applies to	Required	Description
`type`	string	All	Yes	`agent` references another Agent; `self` references the coordinator itself.
`template_id`	string	`agent`	Yes	Referenced Forward Template ID.
`name`	string	`agent`	No	Display name of the sub-Agent.

Advisor entries use {"type":"advisor","model":"ultimate"}. At most one is allowed; see Advisor. The referenced Template must exist and be accessible to the current caller. When the roster contains ordinary Agent or self entries, tools must include agent_toolset_20260401. An Advisor-only roster does not require this toolset. If tools is also provided in the same update request, retain this toolset in the replacement array.

Request form	Meaning
Field omitted	Preserve the current `multiagent` configuration.
`multiagent: null`	Clear the `multiagent` configuration.
Non-empty object	Replace the current configuration.

Advisor

Advisor gives the main Agent advice for tasks such as plan review and complex analysis. The main Agent decides when to consult it and whether to adopt its advice; you can specify consultation conditions in the system prompt. Advisor uses the main Agent's current conversation context and does not execute tools.

Field	Type	Required	Description
`type`	string	Yes	Must be `"advisor"`.
`model`	string	Yes	Non-empty available model name. See List models. Model objects are not supported.

An Advisor entry accepts only type and model. It can be configured alone or alongside ordinary entries. Each roster allows at most one Advisor, which does not count toward the 20 ordinary Agent limit. It does not need to be added to enabled_tools. Its fields match the Managed-layer Advisor object.

{
  "multiagent": {
    "type": "coordinator",
    "agents": [{"type": "advisor", "model": "ultimate"}]
  }
}

To change the Advisor model, update the model string in its multiagent.agents[] entry. The Template's top-level model controls the main Agent and does not change the Advisor model. Updating multiagent replaces the entire configuration, so include all ordinary Agent and self entries you want to keep. Remove the Advisor by deleting its entry; clear the entire roster with multiagent: null. Advisor configuration changes apply only to new Sessions.

Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/templates/tmpl_support' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Support assistant v2",
  "max_tool_rounds": 40,
  "model": {
    "id": "ultimate",
    "effort": "high",
    "speed": "standard",
    "context_window": 400000
  },
  "managed_tool_config": {
    "enabled_tools": []
  },
  "multiagent": {
    "type": "coordinator",
    "agents": [
      {
        "type": "agent",
        "template_id": "tmpl_research_v2",
        "name": "Research Agent"
      },
      {
        "type": "self"
      }
    ]
  },
  "environment_id": "env_support_v2",
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    },
    "vault_019f18f2762c": {
      "enabled": true
    }
  },
  "github_repositories": {
    "source": {
      "url": "https://github.com/acme/support-agent.git",
      "authorization_token": "github_pat_xxx",
      "mount_path": "/data/workspace/support-agent"
    }
  },
  "environment_variables": {
    "BASE_MODE": "support_v2"
  }
}'

Example response

HTTP 200 OK

{
  "type": "template",
  "id": "tmpl_support",
  "name": "Support assistant v2",
  "description": "Handles customer support requests",
  "status": "active",
  "max_tool_rounds": 40,
  "model": {
    "id": "ultimate",
    "effort": "high",
    "speed": "standard",
    "context_window": 400000
  },
  "system": "You are a helpful support assistant.",
  "tools": [
    {
      "type": "agent_toolset_20260401"
    }
  ],
  "managed_tool_config": {
    "enabled_tools": []
  },
  "mcp_servers": [],
  "skills": [],
  "multiagent": {
    "type": "coordinator",
    "agents": [
      {
        "type": "agent",
        "template_id": "tmpl_research_v2",
        "name": "Research Agent"
      },
      {
        "type": "self"
      }
    ]
  },
  "environment_id": "env_support_v2",
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    },
    "vault_019f18f2762c": {
      "enabled": true
    }
  },
  "files": {},
  "github_repositories": {
    "source": {
      "url": "https://github.com/acme/support-agent",
      "mount_path": "/data/workspace/support-agent"
    }
  },
  "environment_variables": {
    "BASE_MODE": "support_v2"
  },
  "metadata": {},
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:30:00Z"
}

Response fields

Field	Type	Description
Return value	object	Complete updated Template object. If the request includes `model`, it is returned in the submitted form; otherwise, its existing form is preserved.
`managed_tool_config`	object	Updated Forward managed-capability baseline, returned as an `enabled_tools` array.
`max_tool_rounds`	integer	Maximum tool-call rounds per Turn. Omitted when unset or cleared; not returned as `null`.
`multiagent`	object\|null	Updated Multi-agent configuration. `null` when not configured.
`github_repositories`	object	Updated GitHub repository configuration. Omits the write-only `authorization_token`.

Errors

HTTP	Type	Code	Trigger
400	`invalid_request_error`	-	Invalid request body or unsupported field value.
400	`invalid_request_error`	-	`browser_toolset_20260714` is used without the required `X-Qoder-Beta` header.
400	`invalid_request_error`	-	Invalid `multiagent` structure: an empty roster, more than 20 ordinary Agents, more than one Advisor or invalid Advisor fields, or a referenced Forward Template that does not exist or is inaccessible.
404	`not_found_error`	-	Template or referenced resource does not exist.
409	`conflict_error`	-	The Template name already exists, the Template state conflicts, or normalized GitHub repository URLs or mount paths are duplicated.
401	`authentication_error`	`authentication_required`	The PAT or SAT is invalid or expired.

Notes

Archived templates cannot be updated.
Legacy requests using managed_tool_config.tools or schedule_creation_enabled remain compatible. New integrations should use managed_tool_config.enabled_tools.
Updating session defaults does not mutate existing sessions.
github_repositories.*.authorization_token is write-only and is omitted from Template responses.

Update a template

Headers

Path parameters

Body parameters

Nested configuration objects

Model

Vaults

File resources

GitHub repositories

Tools array

Forward managed capabilities

Browser Use (Beta)

Tool config

Permission policy

MCP servers

Skills

Multiagent

Advisor

Example request

Example response

Response fields

Errors

Notes

Get a template

Clone a template

​Headers

​Path parameters

​Body parameters

​Nested configuration objects

​Model

​Vaults

​File resources

​GitHub repositories

​Tools array

​Forward managed capabilities

​Browser Use (Beta)

​Tool config

​Permission policy

​MCP servers

​Skills

​Multiagent

​Advisor

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related

Get a template

Clone a template

Headers

Path parameters

Body parameters

Nested configuration objects

Model

Vaults

File resources

GitHub repositories

Tools array

Forward managed capabilities

Browser Use (Beta)

Tool config

Permission policy

MCP servers

Skills

Multiagent

Advisor

Example request

Example response

Response fields

Errors

Notes

Related