Skip to main content
An agent represents an AI system that Veto authorizes on behalf of. Every authorization request is scoped to a specific agent, and policies are attached to agents.

​
The agent object

​
id
string
UUID uniquely identifying the agent.
​
name
string
Human-readable name for the agent.
​
description
string | null
Optional description of the agent’s purpose.
​
status
string
Current status of the agent. One of "active", "suspended", or "revoked". Only "active" agents can receive "allowed" authorization decisions.
​
createdAt
string
ISO 8601 timestamp of when the agent was created.
​
updatedAt
string
ISO 8601 timestamp of the last update.

​
POST /v1/agents

Create a new agent in your workspace.
Requires an API key with admin scope.
​
name
string
required
Human-readable name for the agent. Must be between 1 and 255 characters.
​
description
string
Optional description. Maximum 2,000 characters.
Returns the created agent object with HTTP 201. 
curl -X POST https://api.veto.tools/v1/agents \
  -H "Authorization: Bearer veto_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email assistant",
    "description": "Handles inbox triage and draft responses"
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Email assistant",
  "description": "Handles inbox triage and draft responses",
  "status": "active",
  "createdAt": "2026-01-15T10:00:00.000Z",
  "updatedAt": "2026-01-15T10:00:00.000Z"
}

​
GET /v1/agents

List all agents in your workspace.
​
limit
number
default:"100"
Maximum number of agents to return. Must be between 1 and 200.
​
offset
number
default:"0"
Number of agents to skip. Use with limit for pagination.
Returns a paginated envelope with an array of agent objects. 
curl "https://api.veto.tools/v1/agents?limit=50&offset=0" \
  -H "Authorization: Bearer veto_..."

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Email assistant",
      "description": "Handles inbox triage and draft responses",
      "status": "active",
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 1,
    "total": 1
  }
}

​
GET /v1/agents/:id

Retrieve a single agent by UUID. Returns the agent object, or 404 with AGENT_NOT_FOUND if it does not exist in your workspace. 
curl https://api.veto.tools/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer veto_..."

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Email assistant",
  "description": "Handles inbox triage and draft responses",
  "status": "active",
  "createdAt": "2026-01-15T10:00:00.000Z",
  "updatedAt": "2026-01-15T10:00:00.000Z"
}

​
PATCH /v1/agents/:id

Update an existing agent. All fields are optional — only the fields you include are updated.
Requires an API key with admin scope.
​
name
string
New name for the agent. Must be between 1 and 255 characters.
​
description
string | null
New description. Set to null to clear it. Maximum 2,000 characters.
​
status
string
New status. One of "active", "suspended", or "revoked".Setting status to "suspended" or "revoked" immediately causes all subsequent authorization requests for this agent to be denied without policy evaluation.
Returns the updated agent object. 
curl -X PATCH https://api.veto.tools/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer veto_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "suspended" }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Email assistant",
  "description": "Handles inbox triage and draft responses",
  "status": "suspended",
  "createdAt": "2026-01-15T10:00:00.000Z",
  "updatedAt": "2026-01-15T11:00:00.000Z"
}

​
DELETE /v1/agents/:id

Permanently delete an agent. This cascades to all policies and audit logs associated with the agent.
Requires an API key with admin scope.
Returns 204 No Content on success. 
curl -X DELETE https://api.veto.tools/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer veto_..."