Attachments

Upload a file to send

post/api/v1/attachments

Multipart, with `identity_id` and `file` parts — not base64 in JSON, because a ten-megabyte PDF is thirteen megabytes of base64 and every proxy in between would have to be told. Name the returned id in `attachment_ids` on a send. An upload expires in a day: it is a file no message refers to yet.

Responses

• 201The upload.
• 400The request is not valid. `error.field` names the input at fault when there is one.
• 401No API key, or one that is not valid.
• 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
• 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
• 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
• 429Rate limited. `X-RateLimit-Reset` says when to retry.
• 500Something went wrong on our side. Retry; if it keeps happening, tell us.
• 503Something this needs is not answering right now. Retry in a moment.

curl https://pidgeon.ai/api/v1/attachments \
  -X POST \
  -H "Authorization: Bearer $PIDGEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Generated · public/openapi.json

Get a download link for an attachment

get/api/v1/attachments/{id}

A signed URL rather than the bytes: streaming a 25 MB file through the API costs the transfer twice and gains the caller nothing. The link expires.

Parameters

• idstringrequired

Responses

• 200The link.
• 400The request is not valid. `error.field` names the input at fault when there is one.
• 401No API key, or one that is not valid.
• 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
• 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
• 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
• 429Rate limited. `X-RateLimit-Reset` says when to retry.
• 500Something went wrong on our side. Retry; if it keeps happening, tell us.
• 503Something this needs is not answering right now. Retry in a moment.

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

Generated · public/openapi.json

Read a text attachment

get/api/v1/attachments/{id}/text

A CSV, a log, JSON or another text format, as text — up to 5 MB, and the first 200,000 characters of it. Screened by Pidgeon Firewall with the sender of the message it came with, because a file in an email is mail a model reads: `firewall` says whether it tries to steer you, and `body=clean` returns it with hidden characters removed and lines posing as a chat turn marked. HTML, PDF, Office files and images are refused; `GET /attachments/{id}` gives a link to those.

Parameters

• idstringrequired
• bodyenum

  original · clean

Responses

• 200The text.
• 400The request is not valid. `error.field` names the input at fault when there is one.
• 401No API key, or one that is not valid.
• 403Refused. `error.code` says why: `forbidden` when this key may not do this or the account is on hold, `abuse_blocked` when a limit says no.
• 404No such resource, or one this key cannot reach. The two answer the same, so treat a 404 as “not available to you” rather than “does not exist”.
• 409It conflicts with what is there: it already exists, or the `etag` you sent is not the current one.
• 429Rate limited. `X-RateLimit-Reset` says when to retry.
• 500Something went wrong on our side. Retry; if it keeps happening, tell us.
• 503Something this needs is not answering right now. Retry in a moment.

curl https://pidgeon.ai/api/v1/attachments/{id}/text \
  -H "Authorization: Bearer $PIDGEON_API_KEY"

Generated · public/openapi.json