Pigeon

Preview Base URL: https://sl56paabx2.execute-api.us-east-1.amazonaws.com

Overview

Pigeon is a messaging app for talking to agents. People sign in at https://app.pigeons.chat with their ChirpAuth account and talk to agents. Pigeon keeps the conversations; it does not run agents or call models.

This API is what Pigeon’s own apps call. It holds:

• conversations (threads) and their messages, each belonging to one person’s account;
• contacts: the agents a person can message;
• rooms: one conversation among several people and at least one agent;
• contact requests: a message to an agent that another account published waits until that account approves;
• agents and deliveries: how a message to an agent reaches the agent’s own server, and how its reply comes back.

Concepts explains each of these and the rules Pigeon enforces.

What preview means here: Pigeon runs in production and serves its own web and Android apps. Third-party apps and agents cannot act in a person’s Pigeon yet: people’s sign-in tokens are accepted only from Pigeon’s own apps, and Pigeon’s apps do not yet let a person connect an app or create a token for an agent. These pages describe how the API behaves today, and each missing piece is marked “Not yet”.

Quickstart

1. Check that Pigeon is reachable

No credentials needed:

curl -fsS https://sl56paabx2.execute-api.us-east-1.amazonaws.com/health

{"service":"pigeon","status":"ok"}

2. See what a call without a credential returns

Every other route needs a bearer token, and answers 401 without one:

curl -sS https://sl56paabx2.execute-api.us-east-1.amazonaws.com/v1/threads | grep -Fx '{"error":"unauthorized"}'

3. Use Pigeon as a person

Sign in at https://app.pigeons.chat with your ChirpAuth account. The web app calls this API with your Pigeon sign-in; Concepts shows what a conversation and its messages look like in the API.

Not yet: a credential your own app can use to read or send messages for a person. See Authentication for what each credential can do today.

Authentication

Every call except GET /health sends Authorization: Bearer <token>. Pigeon accepts a person’s Pigeon sign-in (a ChirpAuth ID token issued to Pigeon’s own apps), a ChirpAuth machine token, and, on agent routes, a Pigeon agent token (exr_...). Authentication says who holds each one and what it may do.

API reference

The full route list is in the generated API reference. Most of those routes are called only by Pigeon’s own apps today.

Conventions shared by every route:

• Base URL https://sl56paabx2.execute-api.us-east-1.amazonaws.com; every path except /health starts with /v1/.
• Request and response bodies are JSON; send Content-Type: application/json.
• Times are RFC 3339 in UTC. Ids are UUIDs.
• Lists are not paged. Thread and contact lists are newest-updated first; messages are oldest first.
• A caller sees only its own account’s records. Another account’s thread reads as 404, the same as one that does not exist.
• Creating a thread or a message takes an optional client_thread_id or client_message_id (a UUID you choose). Retrying with the same id and the same content returns the existing record with 200 instead of 201; the same id with different content returns 400.
• Archiving a thread or contact hides it from the normal list and can be undone. It deletes nothing.
• Browsers can call the API only from Pigeon’s own web app. Call it from a server.

Errors and limits

Errors are JSON, {"error": "<message>"}, except request-parsing errors, which are plain text. Each account may make 600 requests a minute, and request bodies are capped at 256 KiB. Errors and limits lists the status codes, the limits and where each applies.

Data and privacy

Pigeon stores each person’s contacts, conversations and messages under an id specific to Pigeon; it stores no email address or name. It deletes nothing on a schedule, and there is not yet a way to delete your conversations. Data and privacy says what is stored, who can see it, and what is not yet possible.