Create a template

POST /api/v1/forward/templates Creates a template that defines the default agent configuration and session defaults used when Forward starts a session for an identity.

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 Browser Use is enabled.

Body parameters

Parameter	Type	Required	Description
`name`	string	Yes	Template name. Must be 1-256 characters and unique within the tenant.
`model`	string\|object	Yes	Model identifier, or an object with the model ID and optional `effort`, `speed`, and `context_window` fields.
`environment_id`	string	Yes	Default environment used by sessions created from this template.
`description`	string	No	Template description. Maximum 2048 characters.
`system`	string	No	System prompt. Maximum 100,000 characters.
`max_tool_rounds`	integer\|null	No	Maximum tool-call rounds per Turn. Must be a positive integer. Omit or pass `null` to use the platform default; Forward does not set an additional default.
`tools`	array	No	Tool configuration list. Maximum 128 items.
`managed_tool_config`	object\|null	No	Forward managed-capability baseline. Use `enabled_tools` to declare the complete set of enabled capability selectors.
`mcp_servers`	array	No	MCP server configuration list. Maximum 20 items.
`skills`	array	No	Skill binding list. Maximum 20 items.
`multiagent`	object\|null	No	Multi-agent collaboration configuration. `type` must be `coordinator`. Omit or pass `null` to disable it.
`vaults`	object	No	Default Vault configuration keyed by Vault ID.
`files`	object	No	Default file resources keyed by file ID.
`github_repositories`	object	No	Default GitHub repositories keyed by a caller-defined binding key. Maximum 20 bindings.
`environment_variables`	object \| string	No	Default session environment variables.
`metadata`	object	No	Custom metadata.

Nested configuration objects

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. Do not repeat vault_id, id, or resource_id inside an entry.

{
  "vaults": {
    "vault_019f18f2761b": {
      "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 and mounts each file at /data/workspace/<file-name>.

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

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 is a top-level Template field for selecting managed capabilities provided and run by Forward. Forward provides the corresponding tool definitions. Specify Capability or Bundle selectors; you do not need to configure these tools again in tools.

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

Field	Type	Required	Description
`enabled_tools`	array	No	Complete list of enabled selectors. An empty array enables no Forward managed capabilities.

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. drive represents the full Drive capability. Bundle/Capability selectors are used only for configuration. 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. Unknown or duplicate selectors are rejected.

Request shape	Semantics
Field omitted	Does not create a managed-capability baseline; no Forward managed capabilities are enabled by default.
`null`, `{}`, or `{ "enabled_tools": [] }`	Creates an explicit empty managed-capability baseline.
Non-empty `enabled_tools` array	Uses the array as the complete baseline.

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

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.

Each multiagent.agents[] item can use one of these forms:

Form	Example	Description
Template reference	`{"type":"agent","template_id":"tmpl_research"}`	References a Forward Template accessible to the current caller.
Coordinator itself	`{"type":"self"}`	Makes the current coordinator available as a delegable Agent.
Advisor object	`{"type":"advisor","model":"ultimate"}`	Configures an advisory model for the main thread. At most one per roster. See Advisor.

The following fields apply to ordinary Agent and self entries. Advisor uses a separate structure; see Advisor.

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.

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. Forward adds this toolset automatically when creating a Template.

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' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Support assistant",
  "description": "Handles customer support requests",
  "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",
        "name": "Research Agent"
      },
      {
        "type": "self"
      }
    ]
  },
  "environment_id": "env_xxx",
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    }
  },
  "files": {},
  "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"
  },
  "metadata": {}
}'

Example response

HTTP 200 OK

{
  "type": "template",
  "id": "tmpl_support",
  "name": "Support assistant",
  "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",
        "name": "Research Agent"
      },
      {
        "type": "self"
      }
    ]
  },
  "environment_id": "env_xxx",
  "vaults": {
    "vault_019f18f2761b": {
      "enabled": true
    }
  },
  "files": {},
  "github_repositories": {
    "source": {
      "url": "https://github.com/acme/support-agent",
      "mount_path": "/data/workspace/support-agent"
    }
  },
  "environment_variables": {
    "BASE_MODE": "support"
  },
  "metadata": {},
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:00:00Z"
}

Response fields

Field	Type	Description
`type`	string	Always `template`.
`id`	string	Template ID.
`status`	string	`active` or `archived`.
`model`	string \| object	Returned in the submitted form. Object form preserves `id`, `effort`, `speed`, and `context_window`.
`max_tool_rounds`	integer	Maximum tool-call rounds per Turn. Omitted when unset or cleared; not returned as `null`.
`managed_tool_config`	object	Forward managed-capability baseline. When configured, it is returned as an `enabled_tools` array.
`multiagent`	object\|null	Multi-agent configuration. `null` when not configured.
`environment_id`	string	Default Environment ID used by sessions.
`vaults`	object	Default Vault configuration keyed by Vault ID.
`files`	object	Default file resource configuration keyed by file ID.
`github_repositories`	object	Default GitHub repository configuration. Includes normalized `url` and final `mount_path`, but omits `authorization_token`.
`created_at`	string	Creation timestamp.
`updated_at`	string	Update timestamp.

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`	-	Referenced environment, skill, vault, or file does not exist.
409	`conflict_error`	-	The Template name already exists, or normalized GitHub repository URLs or mount paths are duplicated.
401	`authentication_error`	`authentication_required`	The PAT or SAT is invalid or expired.

Notes

The id is generated by Forward. Do not send a Template ID in the create request.
files is a map keyed by file ID. Do not include file_id, id, or resource_id inside each file item.
Forward injects file mount paths when creating sessions.
Omitting managed_tool_config leaves all Forward managed capabilities disabled by default.
Legacy requests using managed_tool_config.tools or schedule_creation_enabled remain compatible. New integrations should use managed_tool_config.enabled_tools.
github_repositories.*.authorization_token is write-only and is omitted from Template responses.

Create a template

Headers

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

List templates

Create a session

​Headers

​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

List templates

Create a session

Headers

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