Create or update identity config

Create or update the Identity Config for one Identity and Template.

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

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

Path parameters

Parameter	Type	Required	Description
identity_id	string	Yes	Forward Identity ID.
template_id	string	Yes	Forward Template ID.

Body parameters

Parameter	Type	Required	Description
name	string	No	Config display name.
identity_config	object	Yes	User-level override configuration.
metadata	object	No	Custom 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.

Field	Internal target	Description
system	Agent	System prompt override or append rule.
model	Agent	Model override.
tools	Agent	Built-in tool overrides keyed by tool name.
mcp_servers	Agent	MCP server overrides keyed by MCP server name.
skills	Agent	Skill overrides keyed by Skill ID.
toolsets	Agent	Toolset-level overrides, mainly for MCP toolsets or built-in tool groups.
agent_metadata	Agent	Metadata merged into the compiled agent metadata.
vaults	Session	Vault resource overrides keyed by Vault ID.
files	Session	File resource overrides keyed by File ID. Forward injects mount_path; callers do not provide it here.
environment / environment_id	Unsupported	Identity Config cannot override the Template environment. Requests containing these fields fail with 400 invalid_request_error.

Update semantics

Request shape	Semantics
Field omitted	Keep the existing value.
Field present with a non-null value	Update that field.
Field present with null	Remove that field from the current Identity Config.
metadata omitted	Keep existing metadata.
metadata object	Replace existing metadata.
metadata null	Clear 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 value	Semantics
{ "enabled": true }	Explicitly enable or override the resource.
{ "enabled": false }	Explicitly disable the resource, even if it exists in the Template baseline.
Item omitted	Inherit the Template baseline.
Item value null	Delete 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

Field	Type	Description
type	string	Always config.
identity_id	string	Forward Identity ID.
template_id	string	Forward Template ID.
name	string	Config display name.
status	string	Config status.
effective_hash	string	Hash of the compiled effective config.
created_at	string	Creation timestamp.
updated_at	string	Update timestamp.

Errors

HTTP	Type	Trigger
400	invalid_request_error	Invalid config field, unsupported environment override, or invalid body.
401	authentication_error	PAT invalid or expired.
404	not_found_error	Identity, Template, Skill, Vault, or File does not exist.
409	conflict_error	Config 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.

Related

Get identity config

Get effective config