# Agents

> The full agent-facing surface: reports, health, messages, email, webhooks, claim tokens, and registration. Every endpoint accepts either an API key or a CLI Bearer token.

Language: en
Canonical: https://www.dailybot.com/developers/api/agents
Markdown: send header `Accept: text/markdown` on any URL to receive Markdown instead of HTML.
Last Updated: 2026-07-02

---

## Agents

The full agent-facing surface: reports, health, messages, email, webhooks, claim tokens, and registration. Every endpoint accepts either an API key or a CLI Bearer token.

See the full endpoint reference — with parameters, request/response schemas, error codes, and code samples — at the interactive page: [/developers/api/agents](/developers/api/agents).

Every endpoint in this group accepts either an API key (`X-API-KEY`) or a CLI Bearer token (`Authorization: Bearer …`) unless explicitly marked otherwise, per the parity guarantee at [/developers/authentication#parity-guarantee](/developers/authentication#parity-guarantee).

## Endpoints in this group

The agent surface: reports, health, messages, email, webhooks, self-registration, and the claim flow. Accepts both API keys and CLI Bearer tokens.

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/v1/agent-reports/` | Post an agent report |
| GET | `/v1/agent-health/` | Read agent health status |
| POST | `/v1/agent-health/` | Announce agent health status |
| GET | `/v1/agent-messages/` | List agent messages |
| POST | `/v1/agent-messages/` | Send an agent message |
| POST | `/v1/agent-messages/read/` | Mark agent messages as read |
| POST | `/v1/agent-email/send/` | Send an email as the agent |
| POST | `/v1/agent-webhook/` | Register an agent webhook |
| DELETE | `/v1/agent-webhook/` | Deregister an agent webhook |
| GET | `/v1/agent/register/challenge/` | Fetch an agent-registration challenge (anonymous) |
| POST | `/v1/agent/register/` | Self-register a new agent org (anonymous) |
| POST | `/v1/agent/claim-token/` | Mint a claim token (API-Key only) |
| GET | `/v1/agent/claim/{token}/preview/` | Preview an agent-claim token (anonymous) |
| POST | `/v1/agent/claim/{token}/` | Consume an agent-claim token (anonymous) |

### POST `/v1/agent-reports/`

**Post an agent report**

Body: agent_name, content, optional structured, metadata, is_milestone, co_authors. Response returns the created report with both id and uuid (same UUID value).

- **Auth:** API key (`X-API-KEY`), CLI Bearer (write)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Request body

```json
{
  "agent_name": "string (required, max 128)",
  "content": "string (required)",
  "structured": "object (optional)",
  "metadata": "object (optional)",
  "is_milestone": "boolean (optional, default false)",
  "co_authors": "string[] (optional)"
}
```

#### Response body

```json
{
  "id": "string (uuid) — same value as uuid, kept for backward compatibility",
  "uuid": "string (uuid)",
  "agent_name": "string",
  "content": "string",
  "structured": "object",
  "metadata": "object",
  "is_milestone": "boolean",
  "co_authors": "array",
  "url": "string",
  "created_at": "string (ISO 8601)"
}
```

#### Error codes

| Status | When |
|--------|------|
| `400` | Validation error |
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |

#### Example (curl)

```bash
curl -sS -X POST 'https://api.dailybot.com/v1/agent-reports/' -H 'X-API-KEY: $DAILYBOT_API_KEY' -H 'Content-Type: application/json' -d '{"agent_name":"my-agent","content":"Implemented the new dashboard"}'
```

### GET `/v1/agent-health/`

**Read agent health status**

Returns the current health status for the given agent, including any pending messages queued for it. Each pending message includes both id and uuid (same UUID value).

- **Auth:** API key (`X-API-KEY`), CLI Bearer (write)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `agent_name` | string | Yes | Name of the agent whose health status will be returned. |

#### Response body

```json
{
  "agent_name": "string",
  "status": "string (healthy|unhealthy|stale)",
  "last_check_at": "string (ISO 8601)",
  "history": "array",
  "pending_messages": "array<{ id, uuid, content, message_type, sender_type, sender_name, metadata, created_at }>"
}
```

#### Error codes

| Status | When |
|--------|------|
| `400` | Missing required 'agent_name' query parameter |
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `404` | No health data for the requested agent |
| `429` | Throttled - Retry-After header set |

#### Example (curl)

```bash
curl -sS -X GET 'https://api.dailybot.com/v1/agent-health/?agent_name=my-agent' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### POST `/v1/agent-health/`

**Announce agent health status**

Announce agent health status

- **Auth:** API key (`X-API-KEY`), CLI Bearer (write)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |
| `400` | Validation error |

#### Example (curl)

```bash
curl -sS -X POST 'https://api.dailybot.com/v1/agent-health/' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### GET `/v1/agent-messages/`

**List agent messages**

Paginated list of messages for the given agent. Returns the standard envelope ({count, next, previous, results}). Each message includes both id and uuid (same UUID value).

- **Auth:** API key (`X-API-KEY`), CLI Bearer (write)
- **Rate limit:** `default`
- **Pagination:** Page-number pagination

#### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `agent_name` | string | Yes | Name of the agent to list messages for. |
| `delivered` | boolean | No | If true, only delivered messages; if false, only undelivered. Omit for all. |
| `page` | integer | No | Page number (1-indexed). Default: 1. |
| `page_size` | integer | No | Items per page. Default: 25, max: 100. Alias: limit. |

#### Response body

```json
{
  "count": "integer",
  "next": "string|null",
  "previous": "string|null",
  "results": "array<{ id, uuid, agent_name, content, message_type, sender_type, sender_name, metadata, delivered, delivered_via, delivered_at, created_at }>"
}
```

#### Error codes

| Status | When |
|--------|------|
| `400` | Missing required 'agent_name' query parameter |
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |

#### Example (curl)

```bash
curl -sS -X GET 'https://api.dailybot.com/v1/agent-messages/?agent_name=my-agent&page=1&page_size=25' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### POST `/v1/agent-messages/`

**Send an agent message**

Send a message to the given agent. The created message is returned with both id and uuid (same UUID value).

- **Auth:** API key (`X-API-KEY`), CLI Bearer (write)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Request body

```json
{
  "agent_name": "string (required, max 128)",
  "content": "string (required)",
  "message_type": "string (optional, one of text|command|system)",
  "metadata": "object (optional)",
  "expires_at": "string (optional, ISO 8601)",
  "sender_type": "string (optional, one of human|agent|system)",
  "sender_name": "string (optional)"
}
```

#### Response body

```json
{
  "id": "string (uuid) — same value as uuid, kept for backward compatibility",
  "uuid": "string (uuid)",
  "agent_name": "string",
  "content": "string",
  "message_type": "string",
  "sender_type": "string",
  "sender_name": "string|null",
  "metadata": "object",
  "delivered": "boolean",
  "delivered_via": "string|null",
  "delivered_at": "string|null (ISO 8601)",
  "created_at": "string (ISO 8601)"
}
```

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |
| `400` | Validation error |

#### Example (curl)

```bash
curl -sS -X POST 'https://api.dailybot.com/v1/agent-messages/' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### POST `/v1/agent-messages/read/`

**Mark agent messages as read**

Mark agent messages as read

- **Auth:** API key (`X-API-KEY`), CLI Bearer (write)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |
| `400` | Validation error |

#### Example (curl)

```bash
curl -sS -X POST 'https://api.dailybot.com/v1/agent-messages/read/' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### POST `/v1/agent-email/send/`

**Send an email as the agent**

Send an email as the agent

- **Auth:** API key (`X-API-KEY`), CLI Bearer (write)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |
| `400` | Validation error |

#### Example (curl)

```bash
curl -sS -X POST 'https://api.dailybot.com/v1/agent-email/send/' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### POST `/v1/agent-webhook/`

**Register an agent webhook**

Register an agent webhook

- **Auth:** API key (`X-API-KEY`), CLI Bearer (write)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |
| `400` | Validation error |

#### Example (curl)

```bash
curl -sS -X POST 'https://api.dailybot.com/v1/agent-webhook/' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### DELETE `/v1/agent-webhook/`

**Deregister an agent webhook**

Deregister an agent webhook

- **Auth:** API key (`X-API-KEY`), CLI Bearer (write)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |

#### Example (curl)

```bash
curl -sS -X DELETE 'https://api.dailybot.com/v1/agent-webhook/' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### GET `/v1/agent/register/challenge/`

**Fetch an agent-registration challenge (anonymous)**

Fetch an agent-registration challenge (anonymous)

- **Auth:** Anonymous
- **Rate limit:** `agent_registration`
- **Pagination:** No pagination

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |

#### Example (curl)

```bash
curl -sS -X GET 'https://api.dailybot.com/v1/agent/register/challenge/' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### POST `/v1/agent/register/`

**Self-register a new agent org (anonymous)**

Self-register a new agent org (anonymous)

- **Auth:** Anonymous
- **Rate limit:** `agent_registration`
- **Pagination:** No pagination

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |
| `400` | Validation error |

#### Example (curl)

```bash
curl -sS -X POST 'https://api.dailybot.com/v1/agent/register/' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### POST `/v1/agent/claim-token/`

**Mint a claim token (API-Key only)**

Mint a claim token (API-Key only)

- **Auth:** API key (`X-API-KEY`)
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |
| `400` | Validation error |

#### Example (curl)

```bash
curl -sS -X POST 'https://api.dailybot.com/v1/agent/claim-token/' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### GET `/v1/agent/claim/{token}/preview/`

**Preview an agent-claim token (anonymous)**

Preview an agent-claim token (anonymous)

- **Auth:** Anonymous
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `token` | string | Yes | — |

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |
| `404` | Not found or not visible |

#### Example (curl)

```bash
curl -sS -X GET 'https://api.dailybot.com/v1/agent/claim/{token}/preview/' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

### POST `/v1/agent/claim/{token}/`

**Consume an agent-claim token (anonymous)**

Consume an agent-claim token (anonymous)

- **Auth:** Anonymous
- **Rate limit:** `default`
- **Pagination:** No pagination

#### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `token` | string | Yes | — |

#### Error codes

| Status | When |
|--------|------|
| `401` | Missing/invalid/expired credential |
| `403` | Authenticated but not permitted |
| `429` | Throttled - Retry-After header set |
| `400` | Validation error |
| `404` | Not found or not visible |

#### Example (curl)

```bash
curl -sS -X POST 'https://api.dailybot.com/v1/agent/claim/{token}/' -H 'X-API-KEY: $DAILYBOT_API_KEY'
```

---

## Developer portal navigation

**Getting Started**

- [Overview](/developers)
- [Quick start](/developers/getting-started)
- [Authentication](/developers/authentication)

**API Reference**

- [API Overview](/developers/api)
- [Users](/developers/api/users)
- [Organization](/developers/api/organization)
- [Teams](/developers/api/teams)
- [Invitations](/developers/api/invitations)
- [Check-ins](/developers/api/check-ins)
- [Forms](/developers/api/forms)
- [Report channels](/developers/api/report-channels)
- [Templates](/developers/api/templates)
- [Kudos](/developers/api/kudos)
- [Mood tracking](/developers/api/mood)
- [Important dates](/developers/api/important-dates)
- [Messaging](/developers/api/messaging)
- [Automations](/developers/api/workflows)
- [Webhooks](/developers/api/webhooks)
- [Commands platform](/developers/api/commands-platform)
- [Agents](/developers/api/agents) (this page)
- [OAuth2](/developers/api/oauth2)
- [Integrations](/developers/api/integrations)
- [CLI](/developers/api/cli)

**API guides**

- [Errors & Status Codes](/developers/errors)
- [Rate Limits](/developers/rate-limits)
- [Conventions](/developers/conventions)
- [API Changelog](/developers/api-changelog)
- [Recipes](/developers/recipes)

**Developer Features**

- [Custom commands](/developers/custom-commands)
- [Serverless commands](/developers/serverless)
- [Webhooks & events](/developers/webhooks)
- [Automation API trigger](/developers/workflow-trigger)
- [Activity API](/developers/activity-api)

**CLI**

- [Overview](/developers/cli)
- [Authentication](/developers/cli-authentication)
- [Command reference](/developers/cli-reference)
- [CI/CD recipes](/developers/cli-ci-cd)
- [Configuration](/developers/cli-configuration)
- [Troubleshooting](/developers/cli-troubleshooting)

**Agent Skill**

- [Overview](/developers/agent-skill)
- [Skills catalog](/skills)

---

## Site navigation

**Product:**
- [Home](/)
- [Product](/product)
- [Pricing](/pricing)
- [Enterprise](/enterprise)
- [Integrations](/integrations)
- [Templates](/templates)

**Resources:**
- [Blog](/blog)
- [Academy](/academy)
- [Changelog](/changelog)
- [Help Center](/help)
- [Developers](/developers)
- [Agents](/agents)

**Company:**
- [About](/about)
- [Careers](/careers)
- [Security](/security)
- [Contact Sales](/demo)

**Connect:**
- [LinkedIn](https://www.linkedin.com/company/dailybot/)
- [X/Twitter](https://twitter.com/dailybot)
- [GitHub](https://github.com/Dailybot-Inc)
- [YouTube](https://www.youtube.com/channel/UC3uM9V52vwX7e3vQpCc4qvA)