> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 ` | | `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 ```bash theme={null} 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** ```json theme={null} { "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