Attachments

Files go up on their own and are named when you send. Nothing here is base64 in a JSON body.

Sending one

Upload it, then reference the id:

curl https://pidgeon.ai/api/v1/attachments \
-H "Authorization: Bearer $PIDGEON_API_KEY" \
-F identity_id=idn_4f2a1 \
-F file=@invoice.pdf

Multipart, not JSON. A ten-megabyte PDF is thirteen megabytes of base64, and every proxy between you and us would carry the difference for nothing.

The same id can go on a draft instead, which is how a reply gets a file attached before anybody has decided to send it.

Receiving one

A message that arrives with files lists them, with their names, types and sizes. The bytes are not in the payload — a webhook carries ids, never bodies, which is the same rule everywhere in this API.

Ask for a link when you want the file:

curl https://pidgeon.ai/api/v1/attachments/att_7c2a \
-H "Authorization: Bearer $PIDGEON_API_KEY"

A signed URL rather than the bytes. Streaming a 25 MB file through the API would pay for the transfer twice and gain the caller nothing — the link goes straight to storage, and expires.

It is short-lived on purpose. Fetch it when you are about to use it rather than storing it: a URL that outlived its usefulness in somebody's database is a file leaking to whoever finds the row.