Skip to main content
POST /api/v1/forward/templates/{template_id} Updates mutable template fields. Fields omitted from the request are left unchanged. Array fields such as tools, mcp_servers, and skills are replaced as a whole when provided.

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT>
Content-TypeYesapplication/json
Idempotency-KeyNoOptional idempotency key for unsafe requests.

​
Path parameters

ParameterTypeRequiredDescription
template_idstringYesForward Template ID.

​
Body parameters

ParameterTypeRequiredDescription
namestringNoNew template name.
descriptionstringNoNew template description.
modelstringNoNew model identifier.
systemstringNoNew system prompt.
toolsarrayNoReplaces the tool configuration list.
mcp_serversarrayNoReplaces the MCP server list.
skillsarrayNoReplaces the Skill binding list.
multiagentobjectNoReplaces the Managed Agents configuration.
environment_idstring|nullNoReplaces the default Environment ID. null or empty string clears it.
vault_idsarray|nullNoReplaces default Vault IDs. null clears the list.
filesobject|nullNoReplaces default file resources. null clears the map.
environment_variablesobject | string|nullNoReplaces default session environment variables. null clears them.
metadataobjectNoMerge updates custom metadata.

​
Nested configuration objects

tools, mcp_servers, and skills are array fields. When provided in an update request, each array replaces the previous array as a whole.

​
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.
FieldTypeRequiredDescription
enabledbooleanNoDefaults to true. false disables the inherited file in Identity Config.

​
Tools array

Each tools[] item is selected by type.
FieldTypeApplies toDescription
typestringAllRequired. agent_toolset_20260401, mcp_toolset, or custom.
enabled_toolsarrayagent_toolset_20260401Convenience allowlist. A non-empty list enables only these built-in tools.
disallowed_toolsarrayagent_toolset_20260401Convenience denylist. Compiles to disabled tool configs.
configsarrayagent_toolset_20260401, mcp_toolsetPer-tool enablement and permission policy.
mcp_server_namestringmcp_toolsetRequired. Must match an item in mcp_servers[].name.
namestringcustomRequired custom tool name. Must not conflict with a built-in tool.
descriptionstringcustomRequired custom tool description.
input_schemaobjectcustomRequired 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.
FieldTypeRequiredDescription
namestringYesTool name. Built-in tool name for agent_toolset_20260401; MCP tool name for mcp_toolset.
enabledbooleanNofalse hides and denies the tool. true explicitly enables it.
permission_policyobjectNoRuntime permission behavior.

​
Permission policy

FieldTypeRequiredDescription
typestringYesalways_allow, always_ask, or always_deny.

​
MCP servers

FieldTypeRequiredDescription
typestringNoCurrently only http. Omitted values are treated as HTTP MCP servers in Effective Config.
namestringYesUnique MCP server name within the Template. Referenced by tools[].mcp_server_name.
urlstringYesStreamable HTTP MCP endpoint URL.

​
Skills

FieldTypeRequiredDescription
typestringYescustom or qoder.
skill_idstringYesSkill ID.
versionstringNoSkill version. Omitted values use the latest version.
enabledbooleanNoDefaults 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/tmpl_support' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support assistant v2",
    "environment_id": "env_support_v2",
    "vault_ids": ["vault_crm", "vault_billing"],
    "environment_variables": {
      "BASE_MODE": "support_v2"
    }
  }'

​
Example response

HTTP 200 OK 
{
  "type": "template",
  "id": "tmpl_support",
  "name": "Support assistant v2",
  "description": "Handles pre-sales and after-sales support",
  "status": "active",
  "model": "ultimate",
  "system": "You are a helpful support assistant.",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "multiagent": null,
  "environment_id": "env_support_v2",
  "vault_ids": ["vault_crm", "vault_billing"],
  "files": {},
  "environment_variables": {
    "BASE_MODE": "support_v2"
  },
  "metadata": {},
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:30:00Z"
}

​
Response fields

Returns the updated Template object.

​
Errors

HTTPTypeTrigger
400invalid_request_errorInvalid request body or unsupported field value.
401authentication_errorPAT invalid or expired.
404not_found_errorTemplate or referenced resource does not exist.
409conflict_errorTemplate name already exists.

​
Notes

  • Archived templates cannot be updated.
  • Updating session defaults does not mutate existing sessions.

Get a template

Clone a template