Create a template

Create a Forward template baseline for future sessions.

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>
Content-Type	Yes	application/json
Idempotency-Key	No	Optional idempotency key for unsafe requests.

Body parameters

Parameter	Type	Required	Description
name	string	Yes	Template name. Must be 1-256 characters and unique within the account.
model	string	Yes	Model identifier, such as ultimate.
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	No	Managed Agents configuration.
vault_ids	array	No	Default Vault IDs used by sessions.
files	object	No	Default file resources keyed by file ID.
environment_variables	object | string	No	Default session environment variables.
metadata	object	No	Custom metadata.

Nested configuration objects

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.

Tools array

Each tools[] item is selected by type.

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

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.

Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/templates' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support assistant",
    "description": "Handles pre-sales and after-sales support",
    "model": "ultimate",
    "system": "You are a helpful support assistant.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "configs": [
          { "name": "Read", "enabled": true },
          { "name": "Grep", "enabled": true },
          { "name": "WebSearch", "enabled": true }
        ]
      }
    ],
    "mcp_servers": [],
    "skills": [
      {
        "type": "custom",
        "skill_id": "skill_customer_reply",
        "version": "1",
        "enabled": true
      }
    ],
    "environment_id": "env_support",
    "vault_ids": ["vault_crm"],
    "files": {
      "file_019eXXXX": { "enabled": true }
    },
    "environment_variables": {
      "BASE_MODE": "support"
    },
    "metadata": {}
  }'

Example response

HTTP 201 Created

{
  "type": "template",
  "id": "tmpl_support",
  "name": "Support assistant",
  "description": "Handles pre-sales and after-sales support",
  "status": "active",
  "model": "ultimate",
  "system": "You are a helpful support assistant.",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "configs": [
        { "name": "Read", "enabled": true },
        { "name": "Grep", "enabled": true },
        { "name": "WebSearch", "enabled": true }
      ]
    }
  ],
  "mcp_servers": [],
  "skills": [
    {
      "type": "custom",
      "skill_id": "skill_customer_reply",
      "version": "1",
      "enabled": true
    }
  ],
  "multiagent": null,
  "environment_id": "env_support",
  "vault_ids": ["vault_crm"],
  "files": {
    "file_019eXXXX": { "enabled": true }
  },
  "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.
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.
401	authentication_error	PAT invalid or expired.
404	not_found_error	Referenced environment, skill, vault, or file does not exist.
409	conflict_error	Template name already exists.

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.

Related

List templates

Create a session