---
title: "Agents API | Gazebo Docs"
description: "Create, list, and revoke Gazebo agents using the supported account administration API."
url: "https://gazebohq.com/docs/api/agents"
---

Use the Agents API to list, create, and revoke agent identities in your Gazebo account. These operations require an [account API token](/docs/api/authentication).

## List agents

```
GET /api/v1/agents
```

```bash
curl https://app.gazebohq.com/api/v1/agents \
  -H "Authorization: Bearer YOUR_ACCOUNT_API_TOKEN"
```

The response is ordered newest first. Revoked agents are omitted.

```json
[
  {
    "id": "agent-id",
    "name": "Support triage",
    "createdAt": "2026-09-04T05:42:18.000Z",
    "lastActiveAt": null,
    "revokedAt": null,
    "expiresAt": null,
    "services": ["github", "linear"]
  }
]
```

## Create an agent

```
POST /api/v1/agents
```

```bash
curl https://app.gazebohq.com/api/v1/agents \
  -X POST \
  -H "Authorization: Bearer YOUR_ACCOUNT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Support triage"}'
```

`name` is required and must contain between 1 and 100 characters. `expiresAt` is an optional ISO 8601 timestamp or `null`.

### Response

The endpoint returns `201 Created`. The agent token is returned only in this response.

```json
{
  "id": "agent-id",
  "name": "Support triage",
  "token": "YOUR_NEW_AGENT_TOKEN",
  "createdAt": "2026-09-04T05:42:18.000Z",
  "expiresAt": null
}
```

Store the token securely. Gazebo cannot show it again.

New agents have no service access until you configure their [access policy](/docs/api/access-policies).

## Revoke an agent

```
DELETE /api/v1/agents/{agent_id}
```

```bash
curl https://app.gazebohq.com/api/v1/agents/AGENT_ID \
  -X DELETE \
  -H "Authorization: Bearer YOUR_ACCOUNT_API_TOKEN"
```

Revocation is immediate and invalidates the agent token. The response is:

```json
{ "ok": true }
```