Create a template

Create a Forward Template baseline.

Request Headers

Header	Required	Description
Authorization	Yes	`Bearer <PAT>`
Content-Type	Yes	`application/json`
Idempotency-Key	No	Optional idempotency key for requests with side effects.

Request Body Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Template name, 1-256 characters, unique within the tenant.
`model`	string	Yes	Model identifier, e.g. `ultimate`.
`environment_id`	string	Yes	Default Environment ID used when creating Sessions.
`description`	string	No	Template description, up to 2048 characters.
`system`	string	No	System Prompt, up to 100,000 characters.
`tools`	array	No	Tool configuration list, up to 128 items.
`mcp_servers`	array	No	MCP Server configuration list, up to 20 items.
`skills`	array	No	Skill binding list, up to 20 items.
`multiagent`	object	No	Managed Agents configuration.
`vault_ids`	array	No	Default Vault ID list.
`files`	object	No	Default file resource configuration, 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 entry. Forward automatically injects mount_path when creating a Session.

Field	Type	Required	Description
`enabled`	boolean	No	Omitting the field is equivalent to `true`. In an Identity Config, set `false` to disable an inherited file.

tools array items

Each tools[] item selects its shape via type.

Field	Type	Applies to	Description
`type`	string	All	Required. One of `agent_toolset_20260401`, `mcp_toolset`, or `custom`.
`enabled_tools`	array	`agent_toolset_20260401`	Convenience allowlist; a non-empty array enables only these built-in tools.
`disallowed_tools`	array	`agent_toolset_20260401`	Convenience denylist; compiled into disabled tool config.
`configs`	array	`agent_toolset_20260401`, `mcp_toolset`	Per-tool enable state and permission policy.
`mcp_server_name`	string	`mcp_toolset`	Required. Must match one of the `mcp_servers[].name` values.
`name`	string	`custom`	Required. Custom tool name; must not collide with a built-in tool name.
`description`	string	`custom`	Required. Custom tool description.
`input_schema`	object	`custom`	Required JSON Schema; `input_schema.type` must be `object`.

Built-in tool names include Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, and DeliverArtifacts.

Tool config

Each entry in tools[].configs[] uses the following shape.

Field	Type	Required	Description
`name`	string	Yes	Tool name; use the built-in tool name for a built-in toolset, or the MCP tool name for an MCP toolset.
`enabled`	boolean	No	`false` hides and denies the tool; `true` enables it explicitly.
`permission_policy`	object	No	Runtime permission behavior.

Permission policy

Field	Type	Required	Description
`type`	string	Yes	One of `always_allow`, `always_ask`, or `always_deny`.

MCP servers

Field	Type	Required	Description
`type`	string	No	Only `http` is currently supported; when omitted, the Effective Config treats the entry as an HTTP MCP server.
`name`	string	Yes	MCP server name, unique within the Template, referenced by `tools[].mcp_server_name`.
`url`	string	Yes	Streamable HTTP MCP endpoint URL.

skills array items

Field	Type	Required	Description
`type`	string	Yes	`custom` or `qoder`.
`skill_id`	string	Yes	Skill ID.
`version`	string	No	Skill version; omit to use the latest version.
`enabled`	boolean	No	Omitting the field is equivalent to `true`; `false` excludes it from the compiled Agent config.

Example Request

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/templates' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Support assistant",
  "description": "Handles customer support requests",
  "model": "ultimate",
  "system": "You are a helpful support assistant.",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "environment_id": "env_support",
  "vault_ids": [
    "vault_crm"
  ],
  "files": {},
  "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",
  "model": "ultimate",
  "system": "You are a helpful support assistant.",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "environment_id": "env_support",
  "vault_ids": [
    "vault_crm"
  ],
  "files": {},
  "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.
`vault_ids`	array	Default Vault ID list.
`files`	object	Default file resource configuration.

Errors

HTTP	Type	Code	Trigger
400	`invalid_request_error`	-	Request body or field value is invalid.
404	`not_found_error`	-	A referenced Environment, Skill, Vault, or File does not exist.
409	`conflict_error`	-	Template name already exists.
401	`authentication_error`	`TOKEN_INVALID`	PAT is invalid or has expired.

Notes

Do not pass a template_id when creating; the ID is generated by Forward.
files uses file ID as the map key; do not repeat file_id, id, or resource_id inside each entry.
Forward automatically supplies file mount paths when creating a Session.

​Request Headers

​Request Body Parameters

​Nested Configuration Objects

​File Resources

​tools array items

​Tool config

​Permission policy

​MCP servers

​skills array items

​Example Request

​Example Response

​Response Fields

​Errors

​Notes

​Related