PATCH /api/v1/agent/metadata

Update mutable SIGIL metadata fields for a registered agent.

Auth: Authorization: Bearer pvn_...

Base URL: https://provenonce.io

Requires a SIGIL. Purchase one at POST /api/v1/sigil first.

Request


curl -X PATCH https://provenonce.io/api/v1/agent/metadata \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_..." \
  -d '{
    "substrate": "frontier",
    "substrate_provider": "anthropic",
    "substrate_model": "claude-opus-4-6",
    "capability": "orchestrator",
    "tools": ["web-search", "code-execution"],
    "modality_input": ["text", "image"],
    "modality_output": ["text"],
    "protocol": "http",
    "compliance_regime": "gdpr"
  }'

Mutable fields

These fields can be updated at any time after SIGIL purchase.

Field	Type	Allowed values
`substrate`	string	`frontier`, `open`, `local`, `symbolic`, `hybrid`, `human`
`substrate_provider`	string	`anthropic`, `openai`, `google`, `meta`, `mistral`, `xai`, `cohere`, `deepseek`, `custom`
`substrate_model`	string	Free text (max 256 chars). E.g. `claude-opus-4-6`, `gpt-4o`
`capability`	string	`analyst`, `executor`, `orchestrator`, `guardian`, `retriever`, `renderer`, `witness`
`capability_scope`	string	Free text (max 256 chars). Describes what the agent does
`tools`	string[]	Array of up to 32 tool identifiers (max 64 chars each)
`modality_input`	string[]	Array of input modalities. E.g. `["text", "image", "audio"]`
`modality_output`	string[]	Array of output modalities. E.g. `["text", "image"]`
`protocol`	string	`http`, `grpc`, `websocket`, `mcp`, `a2a`, `custom`
`endpoint`	string	Agent’s service URL (max 256 chars)
`compliance_regime`	string	`gdpr`, `pdpa`, `hipaa`, `sox`, `aisi`, `none`, `custom`
`generation_trigger`	string	Free text (max 256 chars). Bumps the agent’s generation counter

Immutable fields (cannot be changed)

These fields are set at SIGIL purchase and are permanent:

sigil - the full SIGIL string (name*principal*tier)
sigil_name - the name component
principal - the principal namespace
tier - trust governance tier (sov, org, ind, eph, sbx)
identity_class - fee/capability class (narrow_task, autonomous, orchestrator)

Attempting to modify an immutable field returns 400.

Response


{
  "ok": true,
  "sigil": "myagent*acme*ind",
  "generation": 2,
  "updated_fields": ["substrate", "substrate_provider", "substrate_model", "capability"]
}

Error responses

Status	Cause
400	No valid mutable fields provided, or attempted to modify immutable field
400	Field validation failed (invalid vocabulary value)
401	Missing or invalid API key
403	Agent does not have a SIGIL
404	Agent not found
429	Rate limit exceeded

Rate limit

30 requests per minute per endpoint subject.

Generation counter

Each time you set generation_trigger, the agent’s generation counter increments by 1. Use this to signal model upgrades, retraining, or significant behavioral changes. The trigger string is stored as context for why the generation changed.


curl -X PATCH https://provenonce.io/api/v1/agent/metadata \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pvn_..." \
  -d '{"generation_trigger": "upgraded from gpt-4o to claude-opus-4-6", "substrate_model": "claude-opus-4-6"}'