Copy

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 account.
`model`	string\|object	Yes	Model identifier, or an object with the model ID and optional tuning 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.
`tools`	array	No	Tool configuration list. Maximum 128 items.
`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`.

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.

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.

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

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.

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 multiagent is used, tools must include agent_toolset_20260401. Forward adds this toolset automatically when creating a Template.

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",
  "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",
        "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 201 Created

{
  "type": "template",
  "id": "tmpl_support",
  "name": "Support assistant",
  "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",
        "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`.
`multiagent`	object\|null	Multi-agent configuration. `null` when not configured.
`environment_id`	string	Default Environment ID used by sessions.
`vault_ids`	array	Default Vault IDs.
`files`	object	Default file resource configuration keyed by file ID.
`created_at`	string	Creation timestamp.
`updated_at`	string	Update timestamp.

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`	Referenced environment, skill, vault, or file does not exist.
409	`conflict_error`	Template name already exists.
401	`authentication_error`	`authentication_required`

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.

Create a template

Headers

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

List templates

Create a session

​Headers

​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

List templates

Create a session

Headers

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