> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veto.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Create, list, get, update, and delete agents via the REST API.

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

<ResponseField name="id" type="string">
  UUID uniquely identifying the agent.
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable name for the agent.
</ResponseField>

<ResponseField name="description" type="string | null">
  Optional description of the agent's purpose.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the agent. One of `"active"`, `"suspended"`, or `"revoked"`. Only `"active"` agents can receive `"allowed"` authorization decisions.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the agent was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of the last update.
</ResponseField>

***

## POST /v1/agents

Create a new agent in your workspace.

<Note>Requires an API key with `admin` scope.</Note>

<ParamField body="name" type="string" required>
  Human-readable name for the agent. Must be between 1 and 255 characters.
</ParamField>

<ParamField body="description" type="string">
  Optional description. Maximum 2,000 characters.
</ParamField>

Returns the created agent object with HTTP `201`.

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```typescript Node.js theme={null}
  const agent = await veto.createAgent({
    name: 'Email assistant',
    description: 'Handles inbox triage and draft responses',
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

***

## GET /v1/agents

List all agents in your workspace.

<ParamField query="limit" type="number" default="100">
  Maximum number of agents to return. Must be between 1 and 200.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of agents to skip. Use with `limit` for pagination.
</ParamField>

Returns a paginated envelope with an array of agent objects.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.veto.tools/v1/agents?limit=50&offset=0" \
    -H "Authorization: Bearer veto_..."
  ```

  ```typescript Node.js theme={null}
  const agents = await veto.listAgents();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

***

## 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.

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.veto.tools/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer veto_..."
  ```

  ```typescript Node.js theme={null}
  const agent = await veto.getAgent('550e8400-e29b-41d4-a716-446655440000');
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

***

## PATCH /v1/agents/:id

Update an existing agent. All fields are optional — only the fields you include are updated.

<Note>Requires an API key with `admin` scope.</Note>

<ParamField body="name" type="string">
  New name for the agent. Must be between 1 and 255 characters.
</ParamField>

<ParamField body="description" type="string | null">
  New description. Set to `null` to clear it. Maximum 2,000 characters.
</ParamField>

<ParamField body="status" type="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.
</ParamField>

Returns the updated agent object.

<RequestExample>
  ```bash cURL theme={null}
  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" }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

***

## DELETE /v1/agents/:id

Permanently delete an agent. This cascades to all policies and audit logs associated with the agent.

<Note>Requires an API key with `admin` scope.</Note>

Returns `204 No Content` on success.

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE https://api.veto.tools/v1/agents/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer veto_..."
  ```

  ```typescript Node.js theme={null}
  await veto.deleteAgent('550e8400-e29b-41d4-a716-446655440000');
  ```
</RequestExample>