Skip to content
view raw .md

Agents

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

POST/v1/agent-reports/API keyCLI Auth

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

Request body

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

{
  "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)"
}

Errors

StatusWhen
400Validation error
401Missing/invalid/expired credential
403Authenticated but not permitted
429Throttled - Retry-After header set
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"}'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

GET/v1/agent-health/API keyCLI Auth

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

Query parameters

NameTypeRequiredDescription
agent_namestringRequiredName of the agent whose health status will be returned.

Response

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

Errors

StatusWhen
400Missing required 'agent_name' query parameter
401Missing/invalid/expired credential
403Authenticated but not permitted
404No health data for the requested agent
429Throttled - Retry-After header set
curl -sS -X GET 'https://api.dailybot.com/v1/agent-health/?agent_name=my-agent' -H 'X-API-KEY: $DAILYBOT_API_KEY'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

POST/v1/agent-health/API keyCLI Auth

Announce agent health status

Announce agent health status

Errors

StatusWhen
401Missing/invalid/expired credential
403Authenticated but not permitted
429Throttled - Retry-After header set
400Validation error
curl -sS -X POST 'https://api.dailybot.com/v1/agent-health/' -H 'X-API-KEY: $DAILYBOT_API_KEY'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

GET/v1/agent-messages/API keyCLI AuthPage-number pagination

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

Query parameters

NameTypeRequiredDescription
agent_namestringRequiredName of the agent to list messages for.
deliveredbooleanOptionalIf true, only delivered messages; if false, only undelivered. Omit for all.
pageintegerOptionalPage number (1-indexed). Default: 1.
page_sizeintegerOptionalItems per page. Default: 25, max: 100. Alias: limit.

Response

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

Errors

StatusWhen
400Missing required 'agent_name' query parameter
401Missing/invalid/expired credential
403Authenticated but not permitted
429Throttled - Retry-After header set
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'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

POST/v1/agent-messages/API keyCLI Auth

Send an agent message

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

Request body

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

{
  "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)"
}

Errors

StatusWhen
401Missing/invalid/expired credential
403Authenticated but not permitted
429Throttled - Retry-After header set
400Validation error
curl -sS -X POST 'https://api.dailybot.com/v1/agent-messages/' -H 'X-API-KEY: $DAILYBOT_API_KEY'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

PATCH/v1/agent-messages/read/API keyCLI Auth

Mark agent messages as read

Mark agent messages as read

Request body

NameTypeRequiredDescription
message_idsarray<string>RequiredUUIDs of the messages the agent has processed. Must be a non-empty list.

Errors

StatusWhen
401Missing/invalid/expired credential
403Authenticated but not permitted
429Throttled - Retry-After header set
400`message_ids` is missing, not a list, or empty
curl -sS -X PATCH 'https://api.dailybot.com/v1/agent-messages/read/' -H 'X-API-KEY: $DAILYBOT_API_KEY' -H 'Content-Type: application/json' -d '{"message_ids": ["<message-uuid>"]}'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

POST/v1/agent-email/send/API keyCLI Auth

Send an email as the agent

Send an email as the agent

Errors

StatusWhen
401Missing/invalid/expired credential
403Authenticated but not permitted
429Throttled - Retry-After header set
400Validation error
curl -sS -X POST 'https://api.dailybot.com/v1/agent-email/send/' -H 'X-API-KEY: $DAILYBOT_API_KEY'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

POST/v1/agent-webhook/API keyCLI Auth

Register an agent webhook

Register an agent webhook

Errors

StatusWhen
401Missing/invalid/expired credential
403Authenticated but not permitted
429Throttled - Retry-After header set
400Validation error
curl -sS -X POST 'https://api.dailybot.com/v1/agent-webhook/' -H 'X-API-KEY: $DAILYBOT_API_KEY'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

DELETE/v1/agent-webhook/API keyCLI Auth

Deregister an agent webhook

Deregister an agent webhook

Errors

StatusWhen
401Missing/invalid/expired credential
403Authenticated but not permitted
429Throttled - Retry-After header set
curl -sS -X DELETE 'https://api.dailybot.com/v1/agent-webhook/' -H 'X-API-KEY: $DAILYBOT_API_KEY'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

GET/v1/agent/register/challenge/Anonymousagent_registration

Fetch a self-registration challenge (anonymous)

First step of agent self-registration. Send no auth header. Read instruction and compute the integer answer it asks for; compute it every time, never hardcode it. The challenge is a compatibility check, not a security control.

Response

NameTypeRequiredDescription
challenge_idstringRequiredPass it to POST /v1/agent/register/.
instructionstringRequiredWhat to compute for answer.
expires_inintegerRequiredSeconds until the challenge expires.

Errors

StatusWhen
429Throttled — `registration_rate_limited`; wait the `Retry-After` seconds
curl -sS 'https://api.dailybot.com/v1/agent/register/challenge/'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

POST/v1/agent/register/Anonymousagent_registration

Self-register a new agent organization (anonymous)

Creates an organization, an agent and an agent-scoped API key, and returns a claim link for the human. Send no auth header. Every attempt consumes the challenge. Store api_key, claim_token and claim_url as secrets.

Request body

NameTypeRequiredDescription
challenge_idstringRequiredFrom the challenge response.
answerintegerRequiredThe integer the challenge instruction asks for.
reasonstringRequiredWhy you are registering, in your own words; at least 20 characters. Shown to the human when claiming.
org_namestringRequiredName of the new organization.
agent_namestringRequiredThe name you will use in every report.
timezonestringOptionalIANA time zone. Defaults to UTC.
contact_emailstringOptionalContact email for the human.

Response

NameTypeRequiredDescription
api_keystringRequiredAgent-scoped key. Send it in X-API-KEY.
agent_namestringRequiredRegistered agent name.
agent_emailstringRequiredThe agent's email identity.
agent_usernamestringRequiredThe agent's username.
org_idstringRequiredNew organization ID.
org_namestringRequiredNew organization name.
claim_urlstringRequiredLink the human opens to claim the organization.
claim_tokenstringRequiredThe claim secret inside claim_url.
claim_expires_atstringRequiredWhen the claim link expires (ISO 8601, UTC). Show it to the human.

Errors

StatusWhen
400`missing_fields`, `invalid_answer`, `challenge_invalid`, `challenge_used`, `challenge_expired` (fetch a new challenge and retry once), `answer_incorrect`, `reason_too_short`, `reason_echoes_instruction`
429Throttled — `registration_rate_limited`; wait the `Retry-After` seconds
curl -sS -X POST 'https://api.dailybot.com/v1/agent/register/' -H 'Content-Type: application/json' -d '{"challenge_id": "<challenge_id>", "answer": <integer-answer>, "reason": "Reporting progress for the acme-api repository", "org_name": "Acme", "agent_name": "claude-code"}'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

GET/v1/agent/claim-token/API keyCLI Auth

Get the current claim link

Returns the existing claim link for the caller's agent organization. It does not mint a new one.

Response

NameTypeRequiredDescription
claim_urlstringRequiredLink the human opens to claim the organization.
expires_atstringRequiredWhen the link expires (ISO 8601, UTC).

Errors

StatusWhen
401Missing, invalid or expired credential
404`claim_token_unavailable`: already claimed or expired; a new link cannot be minted yet
curl -sS 'https://api.dailybot.com/v1/agent/claim-token/' -H 'X-API-KEY: $DAILYBOT_API_KEY'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

GET/v1/agent/claim/{token}/preview/Anonymous

Preview a claim link (anonymous)

What the human sees before claiming. Send no auth header. registration_reason is plain text written by the agent; label it that way.

Path parameters

NameTypeRequiredDescription
tokenstringRequired—

Response

NameTypeRequiredDescription
org_namestringRequiredOrganization to be claimed.
registration_reasonstringRequiredThe agent's reason, plain text, up to 280 characters.
registration_reason_sourcestringRequiredAlways agent: the reason was written by the agent.
agent_workersarrayRequiredAgents in the organization (name, username).
report_countintegerRequiredReports sent so far.
created_atstringRequiredWhen the organization was registered.
expires_atstringRequiredWhen the claim link expires.

Errors

StatusWhen
400`claim_not_found`, `already_claimed`, `claim_expired`
429`registration_rate_limited`: throttled; wait the `Retry-After` seconds (integer)
curl -sS 'https://api.dailybot.com/v1/agent/claim/<claim_token>/preview/'

Try it

This is a copy-only helper — the request is not sent from your browser. Paste the command into your terminal to execute it.

POST/v1/agent/claim/{token}/Web session (signed in)

Claim an agent organization (signed-in web session)

Called by the Dailybot web app when the signed-in human confirms the claim link; agents do not call it. Requires the human's web session, not an API key. The human becomes an admin of the agent's organization. Claiming into an existing organization is not available.

Path parameters

NameTypeRequiredDescription
tokenstringRequired—

Response

NameTypeRequiredDescription
successbooleanRequiredtrue when claimed.
org_idstringRequiredClaimed organization ID.
org_namestringRequiredClaimed organization name.

Errors

StatusWhen
400`claim_not_found`, `already_claimed`, `claim_expired`, `claim_org_conflict` (the person already belongs to an organization with members)
401No web session, or it expired
  • Web session only: this endpoint accepts neither API keys nor CLI Bearer tokens.

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.

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.