Agents

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

string

UUID uniquely identifying the agent.

string

Human-readable name for the agent.

string | null

Optional description of the agent’s purpose.

string

Current status of the agent. One of "active", "suspended", or "revoked". Only "active" agents can receive "allowed" authorization decisions.

string

ISO 8601 timestamp of when the agent was created.

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.

string

required

Human-readable name for the agent. Must be between 1 and 255 characters.

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"
  }'

const agent = await veto.createAgent({
  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.

number

default:"100"

Maximum number of agents to return. Must be between 1 and 200.

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_..."

const agents = await veto.listAgents();

{
  "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_..."

const agent = await veto.getAgent('550e8400-e29b-41d4-a716-446655440000');

{
  "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.

string

New name for the agent. Must be between 1 and 255 characters.

string | null

New description. Set to null to clear it. Maximum 2,000 characters.

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_..."

await veto.deleteAgent('550e8400-e29b-41d4-a716-446655440000');

Overview

Endpoints

The agent object

POST /v1/agents

GET /v1/agents

GET /v1/agents/:id

PATCH /v1/agents/:id

DELETE /v1/agents/:id

​The agent object

​POST /v1/agents

​GET /v1/agents

​GET /v1/agents/:id

​PATCH /v1/agents/:id

​DELETE /v1/agents/:id

The agent object

POST /v1/agents

GET /v1/agents

GET /v1/agents/:id

PATCH /v1/agents/:id

DELETE /v1/agents/:id