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

Create a template

Headers

Body parameters

Nested configuration objects

File resources

Tools array

Tool config

Permission policy

MCP servers

Skills

Example request

Example response

Response fields

Errors

Notes

List templates

Create a session

​Headers

​Body parameters

​Nested configuration objects

​File resources

​Tools array

​Tool config

​Permission policy

​MCP servers

​Skills

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related

List templates

Create a session

Headers

Body parameters

Nested configuration objects

File resources

Tools array

Tool config

Permission policy

MCP servers

Skills

Example request

Example response

Response fields

Errors

Notes

Related