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.

Email

Method and pathAccessDoes
GET /v1/email/inboxesreadList inboxes. Inboxes
POST /v1/email/inboxesadminCreate an inbox. Create an inbox
GET /v1/email/inboxes/{id}readOne inbox. Inboxes
PATCH /v1/email/inboxes/{id}readTurn 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}adminRemove an inbox; its address is retired for good. Inboxes
GET /v1/email/inboxes/{id}/messagesreadThe inbox’s mail, sent and received, newest first. Reading mail
GET /v1/email/inboxes/{id}/messages/awaitreadWait for mail: answers when some arrives, or after timeout. Reading mail
GET /v1/email/messages/{id}readOne message, with the Firewall’s verdict. Reading mail
PATCH /v1/email/messages/{id}draftMark a received message read or unread. Reading mail
POST /v1/email/inboxes/{id}/messagessendSend mail. Send mail
POST /v1/email/inboxes/{id}/draftsdraftWrite a draft. Drafts
GET /v1/email/drafts/{id}readA draft, held or scheduled message. Drafts
PATCH /v1/email/drafts/{id}draftReplace a draft’s addresses and body; its thread stays. Drafts
DELETE /v1/email/drafts/{id}draftThrow away a draft, or a held or scheduled message. Drafts
POST /v1/email/drafts/{id}/approvaldraftHold a draft for a person to approve. Drafts
POST /v1/email/drafts/{id}/sendsendSend a draft now, or at send_at. Drafts
POST /v1/email/inboxes/{id}/attachmentsdraftUpload a file to send, up to 4 MB. Attachments
POST /v1/email/inboxes/{id}/attachments/uploadsdraftStart uploading a file up to 25 MB; put its bytes at the link. Attachments
POST /v1/email/attachments/{id}/completedraftFinish an upload: the file becomes sendable. Attachments
GET /v1/email/attachments/{id}readA file, with a link to its bytes for five minutes. Attachments
GET /v1/email/storagereadHow much of the account’s 10 GB its mail and files use. Storage
GET /v1/email/threadsreadConversations across your inboxes, newest first. Conversations
GET /v1/email/threads/{id}readOne conversation and its messages, oldest first. Conversations
PATCH /v1/email/threads/{id}draftFile, star, or hand a conversation to a person. Conversations
DELETE /v1/email/threads/{id}adminDelete a conversation, its messages and files, for good. Conversations
GET /v1/email/inboxes/{id}/labelsreadAn inbox’s labels, by name. Labels
POST /v1/email/inboxes/{id}/labelsdraftMake a label. Labels
PATCH /v1/email/labels/{id}draftRename or recolour a label. Labels
DELETE /v1/email/labels/{id}draftDelete a label; its conversations stay. Labels
POST /v1/email/threads/{id}/labelsdraftPut a label on a conversation. Labels
DELETE /v1/email/threads/{id}/labels/{labelId}draftTake a label off a conversation. Labels
GET /v1/email/searchreadFind messages by words in their subject, sender or text. Search
GET /v1/email/contactsreadWho your inboxes correspond with, most recently seen first. Contacts
GET /v1/email/contacts/{id}readOne contact. Contacts
PATCH /v1/email/contacts/{id}draftName a contact or note something; mail no longer renames it. Contacts
DELETE /v1/email/contacts/{id}draftForget a contact; new mail adds it again. Contacts
POST /v1/email/test/inboundsend, test keyDeliver test mail to one of your inboxes, as if from outside. Test keys
GET /v1/email/domainsreadYour proved domains, and whether mail is on; a key of one pod, its pod’s. Your own domain
GET /v1/email/domains/{id}readOne domain, its mail status and the records to set. Your own domain
POST /v1/email/domains/{id}/mailadminTurn mail on for a proved domain. Your own domain
DELETE /v1/email/domains/{id}/mailadminTurn mail off for a domain. Your own domain
POST /v1/email/domains/{id}/checkreadCheck a domain’s records now. Your own domain
GET /v1/email/inboxes/{id}/app-passwordsadminAn inbox’s app passwords, never the passwords themselves. Mail apps
POST /v1/email/inboxes/{id}/app-passwordsadminMake an app password for IMAP, SMTP and CalDAV; shown once. Mail apps
DELETE /v1/email/app-passwords/{id}adminRevoke an app password. Mail apps
GET /v1/email/inboxes/{id}/eventsreadAn inbox’s calendar events, in start order. Calendar
POST /v1/email/inboxes/{id}/eventsdraftPut an event on an inbox’s calendar. Calendar
GET /v1/email/events/{id}readOne calendar event. Calendar
PATCH /v1/email/events/{id}draftChange an event; what you leave out stays. Calendar
DELETE /v1/email/events/{id}draftDelete an event; calendar apps drop it at their next sync. Calendar
GET /v1/email/rulesread, account keySend and receive rules. Rules
POST /v1/email/rulesadmin, account keyAllow or block an address or a domain. Rules
DELETE /v1/email/rules/{id}admin, account keyRemove a rule. Rules
GET /v1/email/suppressionsread, account keyThe do-not-send list, newest first. Rules
POST /v1/email/suppressionsadmin, account keyPut an address on the do-not-send list. Rules
DELETE /v1/email/suppressionsadmin, account keyTake an address off the do-not-send list. Rules

Platform

Method and pathAccessDoes
GET /v1/podsreadList pods. Pods
POST /v1/podsadmin, account keyMake a pod. Pods
PATCH /v1/pods/{id}admin, account keyRename a pod. Pods
POST /v1/pods/{id}/moveadmin, account keyMove an agent identity, address, domain, webhook endpoint or site into a pod. Pods
DELETE /v1/pods/{id}admin, account keyRemove an empty pod. Pods
GET /v1/eventsreadThe account’s event log, newest first. Event log
GET /v1/keysread, account keyYour API keys, never the keys themselves. Keys from the API
POST /v1/keysadmin, account keyMake 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 keyRevoke an API key; it stops working at once. Keys from the API
GET /v1/webhooksreadYour webhook endpoints, never their secrets; a key of one pod, its pod’s. Webhooks
POST /v1/webhooksadminAdd a webhook endpoint; its secret is answered once. Webhooks
DELETE /v1/webhooks/{id}adminRemove a webhook endpoint; a key of one pod, its pod’s only. Webhooks
GET /v1/openapi.jsonNoneThis API as an OpenAPI 3.1 document. No key needed. OpenAPI

Sign in with Pidgeon

Method and pathAccessDoes
GET /v1/auth/clientsreadYour Auth sites, without their secrets. Register a site
POST /v1/auth/clientsadminRegister a site; its secret is answered once. Register a site
PATCH /v1/auth/clients/{id}adminRename a site or replace its return addresses; its id and secret stay. Edit a site, rotate its secret
POST /v1/auth/clients/{id}/rotate-secretadminA new secret, answered once; the old one stops working at once. Edit a site, rotate its secret
DELETE /v1/auth/clients/{id}adminRemove a site; its sign-ins end. Register a site
GET /v1/auth/mandatesreadYour mandates, newest first, up to 100. Mandates
POST /v1/auth/mandatessendAsk a person to let an agent act for them at a site. Mandates
DELETE /v1/auth/mandates/{id}sendEnd a mandate, asked or granted. Mandates

Agent identities

Method and pathAccessDoes
GET /v1/agentsreadList agent identities. Register an agent
POST /v1/agentsadminRegister an agent identity. Register an agent
GET /v1/agents/{id}readOne agent identity, its keys and its operator’s reputation. Get an agent
POST /v1/agents/{id}/keysadminPublish an agent identity’s public key, in a request signed with it. Publish a key
PATCH /v1/agents/{id}adminRename an agent identity, or change what its agent does. Rename and revoke
DELETE /v1/agents/{id}adminRevoke an agent identity and every key it has. It cannot be undone. Rename and revoke
DELETE /v1/agents/{id}/keys/{kid}adminRevoke one of an agent identity’s keys. Rename and revoke
GET /v1/domainsreadYour domains, waiting and proved; a key of one pod, its pod’s. Domains from the API
POST /v1/domainsadminAdd a domain; answers the TXT record that proves it. Domains from the API
GET /v1/domains/{id}readOne domain: whether it is proved, its mail, and every DNS record to publish. Domains from the API
POST /v1/domains/{id}/verifyreadLook for the domain’s _pidgeon TXT record now. Domains from the API
DELETE /v1/domains/{id}adminRemove 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
curl https://pidgeon.ai/v1/openapi.json
curl https://pidgeon.ai/asyncapi.json
curl https://pidgeon.ai/.well-known/api-catalog

OAuth and OpenID Connect

Method and pathDoes
GET /.well-known/openid-configurationOpenID Connect discovery.
GET /.well-known/jwks.jsonThe keys ID tokens and ID-JAGs are signed with (RS256).
GET /.well-known/oauth-authorization-serverOAuth metadata (RFC 8414), for apps.
GET /.well-known/oauth-protected-resourceResource metadata (RFC 9728), named by every 401.
GET /oauth/authorizeWhere a person signs in and consents. People
POST /oauth/tokenCodes, refresh tokens, and agents’ token exchange. Agents
GET, POST /oauth/userinfoA signed-in person’s claims.
POST /oauth/registerDynamic client registration (RFC 7591), for apps.
POST /oauth/revokeRevoke an app’s token (RFC 7009).
POST /oauth/introspectA site asks whether an ID token it holds still stands, its mandate’s above all (RFC 7662). Mandates

Key directories

Method and pathDoes
GET https://<slug>.agents.pidgeon.ai/.well-known/http-message-signatures-directoryAn operator’s live keys, as a JWK Set. Passport

Conventions

  • Ids are UUIDs, except a key’s kid (a thumbprint) and a site’s client_id (site_…).
  • Times are ISO 8601 in UTC.
  • Lists answer {data, has_more, next_cursor}; pass next_cursor back as cursor.
  • Errors answer {"error": {"code", "message"}}: Errors.
  • 600 requests a minute per key; every answer carries RateLimit and RateLimit-Policy, and RateLimit-Limit, RateLimit-Remaining and RateLimit-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.