Reference
API reference
Every endpoint Pidgeon answers, with the access it needs and the page that documents it. The API is at https://pidgeon.ai, takes and answers JSON (OAuth endpoints take forms), and authenticates /v1 with Authorization: Bearer pgn_….
/v1
The /v1 operations, 89 of them, by product. The same list is an OpenAPI document. An account key is a key of the whole account: a key of one pod gets 403.
| Method and path | Access | Does |
|---|---|---|
GET /v1/email/inboxes | read | List inboxes. Inboxes |
POST /v1/email/inboxes | admin | Create an inbox. Create an inbox |
GET /v1/email/inboxes/{id} | read | One inbox. Inboxes |
PATCH /v1/email/inboxes/{id} | read | Turn on holding suspicious mail for a person (a key never turns it off), set the signature (admin), or link an agent identity (admin). Held for a person |
DELETE /v1/email/inboxes/{id} | admin | Remove an inbox; its address is retired for good. Inboxes |
GET /v1/email/inboxes/{id}/messages | read | The inbox’s mail, sent and received, newest first. Reading mail |
GET /v1/email/inboxes/{id}/messages/await | read | Wait for mail: answers when some arrives, or after timeout. Reading mail |
GET /v1/email/messages/{id} | read | One message, with the Firewall’s verdict. Reading mail |
PATCH /v1/email/messages/{id} | draft | Mark a received message read or unread. Reading mail |
POST /v1/email/inboxes/{id}/messages | send | Send mail. Send mail |
POST /v1/email/inboxes/{id}/drafts | draft | Write a draft. Drafts |
GET /v1/email/drafts/{id} | read | A draft, held or scheduled message. Drafts |
PATCH /v1/email/drafts/{id} | draft | Replace a draft’s addresses and body; its thread stays. Drafts |
DELETE /v1/email/drafts/{id} | draft | Throw away a draft, or a held or scheduled message. Drafts |
POST /v1/email/drafts/{id}/approval | draft | Hold a draft for a person to approve. Drafts |
POST /v1/email/drafts/{id}/send | send | Send a draft now, or at send_at. Drafts |
POST /v1/email/inboxes/{id}/attachments | draft | Upload a file to send, up to 4 MB. Attachments |
POST /v1/email/inboxes/{id}/attachments/uploads | draft | Start uploading a file up to 25 MB; put its bytes at the link. Attachments |
POST /v1/email/attachments/{id}/complete | draft | Finish an upload: the file becomes sendable. Attachments |
GET /v1/email/attachments/{id} | read | A file, with a link to its bytes for five minutes. Attachments |
GET /v1/email/storage | read | How much of the account’s 10 GB its mail and files use. Storage |
GET /v1/email/threads | read | Conversations across your inboxes, newest first. Conversations |
GET /v1/email/threads/{id} | read | One conversation and its messages, oldest first. Conversations |
PATCH /v1/email/threads/{id} | draft | File, star, or hand a conversation to a person. Conversations |
DELETE /v1/email/threads/{id} | admin | Delete a conversation, its messages and files, for good. Conversations |
GET /v1/email/inboxes/{id}/labels | read | An inbox’s labels, by name. Labels |
POST /v1/email/inboxes/{id}/labels | draft | Make a label. Labels |
PATCH /v1/email/labels/{id} | draft | Rename or recolour a label. Labels |
DELETE /v1/email/labels/{id} | draft | Delete a label; its conversations stay. Labels |
POST /v1/email/threads/{id}/labels | draft | Put a label on a conversation. Labels |
DELETE /v1/email/threads/{id}/labels/{labelId} | draft | Take a label off a conversation. Labels |
GET /v1/email/search | read | Find messages by words in their subject, sender or text. Search |
GET /v1/email/contacts | read | Who your inboxes correspond with, most recently seen first. Contacts |
GET /v1/email/contacts/{id} | read | One contact. Contacts |
PATCH /v1/email/contacts/{id} | draft | Name a contact or note something; mail no longer renames it. Contacts |
DELETE /v1/email/contacts/{id} | draft | Forget a contact; new mail adds it again. Contacts |
POST /v1/email/test/inbound | send, test key | Deliver test mail to one of your inboxes, as if from outside. Test keys |
GET /v1/email/domains | read | Your proved domains, and whether mail is on; a key of one pod, its pod’s. Your own domain |
GET /v1/email/domains/{id} | read | One domain, its mail status and the records to set. Your own domain |
POST /v1/email/domains/{id}/mail | admin | Turn mail on for a proved domain. Your own domain |
DELETE /v1/email/domains/{id}/mail | admin | Turn mail off for a domain. Your own domain |
POST /v1/email/domains/{id}/check | read | Check a domain’s records now. Your own domain |
GET /v1/email/inboxes/{id}/app-passwords | admin | An inbox’s app passwords, never the passwords themselves. Mail apps |
POST /v1/email/inboxes/{id}/app-passwords | admin | Make an app password for IMAP, SMTP and CalDAV; shown once. Mail apps |
DELETE /v1/email/app-passwords/{id} | admin | Revoke an app password. Mail apps |
GET /v1/email/inboxes/{id}/events | read | An inbox’s calendar events, in start order. Calendar |
POST /v1/email/inboxes/{id}/events | draft | Put an event on an inbox’s calendar. Calendar |
GET /v1/email/events/{id} | read | One calendar event. Calendar |
PATCH /v1/email/events/{id} | draft | Change an event; what you leave out stays. Calendar |
DELETE /v1/email/events/{id} | draft | Delete an event; calendar apps drop it at their next sync. Calendar |
GET /v1/email/rules | read, account key | Send and receive rules. Rules |
POST /v1/email/rules | admin, account key | Allow or block an address or a domain. Rules |
DELETE /v1/email/rules/{id} | admin, account key | Remove a rule. Rules |
GET /v1/email/suppressions | read, account key | The do-not-send list, newest first. Rules |
POST /v1/email/suppressions | admin, account key | Put an address on the do-not-send list. Rules |
DELETE /v1/email/suppressions | admin, account key | Take an address off the do-not-send list. Rules |
Platform
| Method and path | Access | Does |
|---|---|---|
GET /v1/pods | read | List pods. Pods |
POST /v1/pods | admin, account key | Make a pod. Pods |
PATCH /v1/pods/{id} | admin, account key | Rename a pod. Pods |
POST /v1/pods/{id}/move | admin, account key | Move an agent identity, address, domain, webhook endpoint or site into a pod. Pods |
DELETE /v1/pods/{id} | admin, account key | Remove an empty pod. Pods |
GET /v1/events | read | The account’s event log, newest first. Event log |
GET /v1/keys | read, account key | Your API keys, never the keys themselves. Keys from the API |
POST /v1/keys | admin, account key | Make an API key, never stronger than the one making it; the key is answered once. A test key makes only test keys. Keys from the API |
DELETE /v1/keys/{id} | admin, account key | Revoke an API key; it stops working at once. Keys from the API |
GET /v1/webhooks | read | Your webhook endpoints, never their secrets; a key of one pod, its pod’s. Webhooks |
POST /v1/webhooks | admin | Add a webhook endpoint; its secret is answered once. Webhooks |
DELETE /v1/webhooks/{id} | admin | Remove a webhook endpoint; a key of one pod, its pod’s only. Webhooks |
GET /v1/openapi.json | None | This API as an OpenAPI 3.1 document. No key needed. OpenAPI |
Sign in with Pidgeon
| Method and path | Access | Does |
|---|---|---|
GET /v1/auth/clients | read | Your Auth sites, without their secrets. Register a site |
POST /v1/auth/clients | admin | Register a site; its secret is answered once. Register a site |
PATCH /v1/auth/clients/{id} | admin | Rename a site or replace its return addresses; its id and secret stay. Edit a site, rotate its secret |
POST /v1/auth/clients/{id}/rotate-secret | admin | A new secret, answered once; the old one stops working at once. Edit a site, rotate its secret |
DELETE /v1/auth/clients/{id} | admin | Remove a site; its sign-ins end. Register a site |
GET /v1/auth/mandates | read | Your mandates, newest first, up to 100. Mandates |
POST /v1/auth/mandates | send | Ask a person to let an agent act for them at a site. Mandates |
DELETE /v1/auth/mandates/{id} | send | End a mandate, asked or granted. Mandates |
Agent identities
| Method and path | Access | Does |
|---|---|---|
GET /v1/agents | read | List agent identities. Register an agent |
POST /v1/agents | admin | Register an agent identity. Register an agent |
GET /v1/agents/{id} | read | One agent identity, its keys and its operator’s reputation. Get an agent |
POST /v1/agents/{id}/keys | admin | Publish an agent identity’s public key, in a request signed with it. Publish a key |
PATCH /v1/agents/{id} | admin | Rename an agent identity, or change what its agent does. Rename and revoke |
DELETE /v1/agents/{id} | admin | Revoke an agent identity and every key it has. It cannot be undone. Rename and revoke |
DELETE /v1/agents/{id}/keys/{kid} | admin | Revoke one of an agent identity’s keys. Rename and revoke |
GET /v1/domains | read | Your domains, waiting and proved; a key of one pod, its pod’s. Domains from the API |
POST /v1/domains | admin | Add a domain; answers the TXT record that proves it. Domains from the API |
GET /v1/domains/{id} | read | One domain: whether it is proved, its mail, and every DNS record to publish. Domains from the API |
POST /v1/domains/{id}/verify | read | Look for the domain’s _pidgeon TXT record now. Domains from the API |
DELETE /v1/domains/{id} | admin | Remove a domain; a proved one’s mail is turned off first. Domains from the API |
OpenAPI
GET /v1/openapi.json answers this API as an OpenAPI 3.1 document, with no key: every operation above with its parameters, request body and answers, an example of each, the rate-limit headers and Idempotency-Key, for a client generator or an agent’s tool list. It is made from the same list as this page, so the two never differ.
The webhooks Pidgeon sends are an AsyncAPI 3.0 document at /asyncapi.json. /.well-known/api-catalog (RFC 9727) links both, the docs, the changelog, the status page and the MCP server.
curl https://pidgeon.ai/v1/openapi.json
curl https://pidgeon.ai/asyncapi.json
curl https://pidgeon.ai/.well-known/api-catalogOAuth and OpenID Connect
| Method and path | Does |
|---|---|
GET /.well-known/openid-configuration | OpenID Connect discovery. |
GET /.well-known/jwks.json | The keys ID tokens and ID-JAGs are signed with (RS256). |
GET /.well-known/oauth-authorization-server | OAuth metadata (RFC 8414), for apps. |
GET /.well-known/oauth-protected-resource | Resource metadata (RFC 9728), named by every 401. |
GET /oauth/authorize | Where a person signs in and consents. People |
POST /oauth/token | Codes, refresh tokens, and agents’ token exchange. Agents |
GET, POST /oauth/userinfo | A signed-in person’s claims. |
POST /oauth/register | Dynamic client registration (RFC 7591), for apps. |
POST /oauth/revoke | Revoke an app’s token (RFC 7009). |
POST /oauth/introspect | A site asks whether an ID token it holds still stands, its mandate’s above all (RFC 7662). Mandates |
Key directories
| Method and path | Does |
|---|---|
GET https://<slug>.agents.pidgeon.ai/.well-known/http-message-signatures-directory | An operator’s live keys, as a JWK Set. Passport |
Conventions
- Ids are UUIDs, except a key’s
kid(a thumbprint) and a site’sclient_id(site_…). - Times are ISO 8601 in UTC.
- Lists answer
{data, has_more, next_cursor}; passnext_cursorback ascursor. - Errors answer
{"error": {"code", "message"}}: Errors. - 600 requests a minute per key; every answer carries
RateLimitandRateLimit-Policy, andRateLimit-Limit,RateLimit-RemainingandRateLimit-Reset. Rate limit - Sending and creating calls take
Idempotency-Key, so a retry is never done twice. Idempotency - What changed, newest first: the changelog. Whether it is up: status.pidgeon.ai.