Skip to main content
An agent represents an AI agent or automated process that you want to govern with Veto policies. You assign policies to agents; every authorization check references an agent by ID.

​
The agent object

​
id
string
required
UUID of the agent.
​
name
string
required
Display name of the agent.
​
description
string | null
required
Optional description of the agent’s purpose.
​
status
string
required
Current status of the agent. One of "active", "suspended", or "revoked".
​
createdAt
string
required
ISO 8601 timestamp of when the agent was created.
​
updatedAt
string
required
ISO 8601 timestamp of when the agent was last updated.

​
POST /v1/agents

Create a new agent in your workspace.
Requires an API key with the admin scope.

​
Request body

​
name
string
required
Display name for the agent. Between 1 and 255 characters.
​
description
string
Optional description. Maximum 2000 characters.
Returns 201 with the created Agent object.

​
GET /v1/agents

List all agents in your workspace. Returns an array of Agent objects.

​
GET /v1/agents/:id

Retrieve a single agent by its UUID. Returns the Agent object, or 404 with AGENT_NOT_FOUND if no agent with that ID exists in your workspace.

​
PATCH /v1/agents/:id

Update an agent’s name, description, or status.
Requires an API key with the admin scope.

​
Request body

All fields are optional. Supply only the fields you want to change.
​
name
string
New display name. Between 1 and 255 characters.
​
description
string | null
New description. Set to null to clear it. Maximum 2000 characters.
​
status
string
New status. One of "active", "suspended", or "revoked".
Returns the updated Agent object, or 404 with AGENT_NOT_FOUND.

​
DELETE /v1/agents/:id

Delete an agent. This action cascades and removes all policies and audit logs associated with the agent.
Requires an API key with the admin scope.
Deleting an agent is irreversible and will also delete all of its policies and audit log entries.
Returns 204 No Content on success, or 404 with AGENT_NOT_FOUND. 
curl --request POST \
  --url https://api.veto.tools/v1/agents \
  --header 'Authorization: Bearer veto_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Customer support bot",
    "description": "Handles tier-1 support tickets and can read the CRM"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Customer support bot",
  "description": "Handles tier-1 support tickets and can read the CRM",
  "status": "active",
  "createdAt": "2024-11-15T10:00:00.000Z",
  "updatedAt": "2024-11-15T10:00:00.000Z"
}