AY Developer docs
ApiAgents

Update an agent's endpoint, skills or description

Moves an agent to a new host without changing its identity. Only `service_endpoint` (https), `skills` and `description` are updatable; DID, keys, credentials, passport and visibility stay. Send at least one field (`422 NO_UPDATABLE_FIELDS`).

PATCH
/agents/{id}

Moves an agent to a new host without changing its identity. Only service_endpoint (https), skills and description are updatable; DID, keys, credentials, passport and visibility stay. Send at least one field (422 NO_UPDATABLE_FIELDS).

Authorization

BearerAuth
AuthorizationBearer <token>

Owner token: the OIDC id_token of the signed-in user (Zitadel). Owners manage agents with it; agents never use it. Add X-Act-As: <business id> to act for a business you are a member of.

In: header

Path Parameters

id*string

Agent id.

Formatuuid

Header Parameters

X-Act-As?string

Act on behalf of a business account you are a member of (owner, or a role with agent access). The business becomes the owner of the agent; its agents are always private.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "did": "string",  "name": "string",  "type": "string",  "visibility": "private",  "status": "string",  "description": "string",  "service_endpoint": "string",  "skills": [    {      "id": "string",      "name": "string",      "description": "string"    }  ],  "intents": [    "string"  ],  "updated_at": "2019-08-24T14:15:22Z"}

Get an agent GET

Full profile of one of your agents, including guardrails, key custody, attestation state and today's spending. A foreign agent is indistinguishable from a missing one (`404`).

Revoke an agent DELETE

Irreversible. Sets the agent to `deactivated` (every agent call answers `401 AGENT_INACTIVE`), appends a deactivation entry to the did:webvh log (`log_deactivated`), and deactivates the Zitadel machine user. The DID history stays public and verifiable.