Copy

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 tuning fields.
`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\|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`.

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.

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 and declares the Agents to which it can delegate.

Field	Type	Required	Description
`type`	string	Yes	Must be `coordinator`.
`agents`	array	Yes	Delegable Agent roster. Must contain 1-20 items.

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. The referenced Template must exist and be accessible to the current caller. When multiagent is used, tools must include agent_toolset_20260401. 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.

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",
  "model": {
    "id": "ultimate",
    "effort": "high",
    "context_window": 400000
  },
  "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",
  "model": {
    "id": "ultimate",
    "effort": "high",
    "context_window": 400000
  },
  "system": "You are a helpful support assistant.",
  "tools": [
    {
      "type": "agent_toolset_20260401"
    }
  ],
  "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.
`multiagent`	object\|null	Updated Multi-agent configuration. `null` when not configured.

Errors

HTTP	Type	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 `agents` count outside 1-20, or an inaccessible referenced Forward Template.
401	`authentication_error`	PAT or SAT invalid or expired.
404	`not_found_error`	Template or referenced resource does not exist.
409	`conflict_error`	Template name already exists.
401	`authentication_error`	`authentication_required`

Notes

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

Update a template

Headers

Path parameters

Body parameters

Nested configuration objects

Model

Vaults

File resources

GitHub repositories

Tools array

Browser Use (Beta)

Tool config

Permission policy

MCP servers

Skills

Multiagent

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

​Browser Use (Beta)

​Tool config

​Permission policy

​MCP servers

​Skills

​Multiagent

​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

Browser Use (Beta)

Tool config

Permission policy

MCP servers

Skills

Multiagent

Example request

Example response

Response fields

Errors

Notes

Related