Skip to main content
POST /api/v1/forward/identities/{identity_id}/templates/{template_id}/config Creates the config if it does not exist, or updates the existing active config. Identity Config is a user-level override over the Template baseline.

​
Headers

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

​
Path parameters

ParameterTypeRequiredDescription
identity_idstringYesForward Identity ID.
template_idstringYesForward Template ID.

​
Body parameters

ParameterTypeRequiredDescription
namestringNoConfig display name.
identity_configobjectYesUser-level override configuration.
metadataobjectNoCustom metadata. Replaces existing metadata when provided.

​
Identity config object

identity_config is the stored user-level override DSL. It is not the compiled runtime config returned by Get Effective Config.
FieldInternal targetDescription
systemAgentSystem prompt override or append rule.
modelAgentModel override.
toolsAgentBuilt-in tool overrides keyed by tool name.
mcp_serversAgentMCP server overrides keyed by MCP server name.
skillsAgentSkill overrides keyed by Skill ID.
toolsetsAgentToolset-level overrides, mainly for MCP toolsets or built-in tool groups.
agent_metadataAgentMetadata merged into the compiled agent metadata.
vaultsSessionVault resource overrides keyed by Vault ID.
filesSessionFile resource overrides keyed by File ID. Forward injects mount_path; callers do not provide it here.
environment / environment_idUnsupportedIdentity Config cannot override the Template environment. Requests containing these fields fail with 400 invalid_request_error.

​
Update semantics

Request shapeSemantics
Field omittedKeep the existing value.
Field present with a non-null valueUpdate that field.
Field present with nullRemove that field from the current Identity Config.
metadata omittedKeep existing metadata.
metadata objectReplace existing metadata.
metadata nullClear metadata.

​
Resource map semantics

skills, vaults, and files use resource IDs as map keys. Do not include skill_id, vault_id, file_id, id, or resource_id inside the map item. Those runtime fields only appear in the Effective Config compiled by Forward.
Map item valueSemantics
{ "enabled": true }Explicitly enable or override the resource.
{ "enabled": false }Explicitly disable the resource, even if it exists in the Template baseline.
Item omittedInherit the Template baseline.
Item value nullDelete this override and restore Template inheritance.

​
Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/identities/idn_019eabc123/templates/tmpl_support/config' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM profile",
    "identity_config": {
      "system": {
        "mode": "append",
        "content": "Prefer CRM data when answering."
      },
      "skills": {
        "skill_customer_reply": {
          "enabled": true,
          "type": "custom",
          "version": "1"
        },
        "skill_marketing_copy": {
          "enabled": false
        }
      },
      "mcp_servers": {
        "mcp_crm": {
          "enabled": true,
          "type": "http",
          "url": "https://crm.example.com/mcp"
        }
      },
      "tools": {
        "Read": { "enabled": true },
        "Grep": { "enabled": true },
        "WebSearch": { "enabled": true }
      },
      "vaults": {
        "vault_crm": { "enabled": true }
      },
      "files": {
        "file_019eXXXX": { "enabled": true }
      }
    },
    "metadata": {}
  }'

​
Example response

HTTP 200 OK 
{
  "type": "config",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_support",
  "name": "CRM profile",
  "status": "active",
  "effective_hash": "sha256:...",
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:00:00Z"
}

​
Response fields

FieldTypeDescription
typestringAlways config.
identity_idstringForward Identity ID.
template_idstringForward Template ID.
namestringConfig display name.
statusstringConfig status.
effective_hashstringHash of the compiled effective config.
created_atstringCreation timestamp.
updated_atstringUpdate timestamp.

​
Errors

HTTPTypeTrigger
400invalid_request_errorInvalid config field, unsupported environment override, or invalid body.
401authentication_errorPAT invalid or expired.
404not_found_errorIdentity, Template, Skill, Vault, or File does not exist.
409conflict_errorConfig state conflict.

​
Notes

  • Omitted config fields remain unchanged.
  • A field set to null removes that field from the current Identity Config.
  • Resource maps use their resource ID as the map key. To restore inheritance for one resource, set that map entry to null.
  • Identity Config does not support overriding environment_id.

Get identity config

Get effective config