Update Agent

Update an agent’s display name, description, metadata, or status

Update Agent

PATCH /v1/agents/{agentID}

Updates mutable fields on an existing machine agent identity. Only the fields provided in the request body are modified; all other fields remain unchanged. At least one field must be provided.

To change an agent’s scopes, use the delegation system or re-register the agent. Scopes cannot be modified directly through this endpoint to preserve the audit trail of scope changes.

Authentication

Requires X-API-Key header or Bearer JWT token. Tenant-scoped via X-Tenant-ID.

Path Parameters

agentID · string · required

The MAIP agent identifier (e.g., maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH).

Request Body

All fields are optional, but at least one must be provided.

display_name · string

Updated human-readable name. Maximum 256 characters.

description · string

Updated description. Maximum 2048 characters.

metadata · object

Replacement metadata object. Replaces the entire metadata field (not a merge). Maximum 16 KB serialized.

status · string

Update the agent’s lifecycle status. One of: "active", "suspended". Use the dedicated suspend or revoke endpoints for status changes that require a reason for audit compliance.

Response

Returns the full updated agent identity object.

id · string

Internal UUID primary key.

agent_id · string

MAIP-compliant agent identifier.

display_name · string

The updated display name.

description · string

The updated description.

metadata · object

The updated metadata object.

status · string

Current lifecycle status after update.

updated_at · string

ISO 8601 timestamp reflecting the update.

Example

curl -X PATCH https://api.truthlocks.com/v1/agents/maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Customer Support Bot v2",
    "description": "Upgraded to handle Tier-1 and Tier-2 support with escalation",
    "metadata": {
      "team": "support",
      "model": "claude-opus-4",
      "environment": "production",
      "version": "2.0"
    }
  }'