Send a reply with a key that has the send scope. The Idempotency-Key makes a retry safe: a retry with the same key returns the first result and does not send again.
Send a reply
IDEMPOTENCY_KEY=$(uuidgen) # make it once; reuse it on a retry
curl -X POST https://app.teamchirp.io/v1/conversations/1042/replies \
-H "Authorization: Bearer $CHIRP_API_KEY" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{"body":"Thanks, Dana. The refund is on its way."}'
Authentication
Create a key in Chirp under Settings → API keys. Chirp shows the secret once; it starts with chirp_. Send it in the Authorization header of every request:
Authorization: Bearer chirp_…
A key acts as the user who created it: it has that user's role and sees only the inboxes that user can see. A conversation the user cannot see answers 404, as if it did not exist. A key stops working when it is revoked or expires, or when its user is disabled or leaves the workspace.
Scopes
A key holds one or more scopes. Each operation names the scope it needs in x-required-scope.
read: list inboxes, teammates and conversations, read a conversation and its linked issues, and download attachments.
write: change the status or assignee, add and remove tags, add notes, and link and unlink Linear issues.
send: send replies and start conversations.
A call without the scope answers 403 with the code insufficient_scope. A Viewer's key keeps only read, whatever scopes it was made with.
Rate limits
Each key may make a fixed number of requests per minute. Every authenticated response carries X-RateLimit-Limit and X-RateLimit-Remaining. When the limit is used up, the API answers 429 with a Retry-After header in seconds. Attachment downloads have a second, lower limit per key, which answers the same way.
Pagination
GET /conversations returns one page and a nextCursor. Pass it as cursor to get the next page; it is null on the last page.
Idempotency
The send operations and adding a note accept an Idempotency-Key header holding a UUID. A retry with the same key returns the first result instead of sending or adding again.
Conflicts
Each conversation has a version that goes up with each change. Send it back as expectedVersion to have a change refused with 409 if someone changed the conversation first.
Errors
Every error has the same body: {"error": {"code": "not_found", "message": "Conversation not found"}}. Branch on code; the message is for people. The codes are listed in the Error schema.
Conversations in the inboxes the key's user can see, newest activity first, in every status unless you filter.
Filters use the app's search syntax: pass tokens in q (such as status:open tag:"billing issue") or as parameters. Different filters must all match; a repeated status, assignee, inbox or linked matches any of its values, and a repeated tag needs every tag. q and the filters together may hold at most 200 characters.
Each row has its linked Linear issues as issueLinks, and snoozedUntil for a snooze that ends at a time.
The result is one page. Pass nextCursor as cursor to get the next one. A conversation that gets new activity during a walk moves to the front, so a walk that started earlier does not return it again.
Parameters
qquery · string
Search text, matched in addresses, subjects, bodies and notes; may hold filter tokens.
statusquery · array of string
open, pending, snoozed or closed.
assigneequery · array of string
me, none, a teammate's id (from `GET /users`) or a teammate's display name.
tagquery · array of string
A tag name; every tag given must be on the conversation.
inboxquery · array of string
An inbox id, name, address or local part.
afterquery · string
Latest activity on or after this day, in the user's time zone: YYYY-MM-DD, today, a weekday such as mon, lastweek, 1d–365d days back, or a month day such as sep15.
beforequery · string
Latest activity before this day, in the same forms as after.
linkedquery · array of string
open, done, any, none or a Linear issue identifier.
isquery · string
attention: the Needs attention list (open and waiting on you, or with a delivery problem).
A filter, limit or cursor is not valid, or q and the filters exceed 200 characters. An `assignee` value that matches no teammate answers with the code `unknown_assignee`, and an `inbox` value that matches no inbox the key's user can see with `unknown_inbox`; before 2026-10, both returned an empty list.
401unauthorized
The API key is missing, invalid, revoked or expired.
Change the status or the assignee: one of the two per call. To snooze, send status snoozed with snoozedUntil: a future time, or null to wait for the customer's reply. The change shows in the timeline as the key's user.
Parameters
idpath · stringrequired
The conversation's id.
Request body
statusstring
The new status. One of open, pending, snoozed, closed.
assigneeIdstring | null
The teammate to assign, or null to unassign. The teammate must be able to see the inbox.
snoozedUntilstring (date-time) | null
Required with status snoozed: when to wake it, or null to wait for the customer's reply.
expectedVersioninteger
Refuse the change with 409 if the conversation's version is no longer this.
The content of one attachment of a message: the bytes of the file, not JSON. Take messageId and index from the messages of GET /conversations/{id}. The inline images of an HTML email are in the same list.
The response is always a download (Content-Disposition: attachment, with the file name). Content-Type is the attachment's type for PNG, JPEG, GIF and WebP images, PDF and plain text; every other type is sent as application/octet-stream. Do not show the content in a browser without a check of your own: it is a file that a customer sent.
The largest attachment the API serves is 25 MB. A key may download 30 attachments per minute; these calls also count in the key's request limit.
Parameters
idpath · stringrequired
The conversation's id.
messageIdpath · stringrequired
The message's id.
indexpath · stringrequired
The attachment's index in the message, from 0.
Response
200 The file's bytes
Errors
401unauthorized
The API key is missing, invalid, revoked or expired.
403insufficient_scope
The key lacks the scope this operation needs.
404not_found
No such conversation, or the key's user cannot see its inbox. Also sent when the message is not in this conversation or has no attachment at this index.
413attachment_too_large
The attachment exceeds 25 MB (`attachment_too_large`).
429rate_limited
The key used up its requests for this minute, or its 30 downloads for this minute.
The Linear issues linked to a conversation, oldest link first, with each issue's title and state as Chirp last saw them. GET /conversations/{id} returns the same list as issueLinks.
Link an existing Linear issue to the conversation, by its identifier (such as ENG-42) or its Linear URL. Chirp reads the issue through the workspace's Linear connection. The API does not create a Linear issue.
The link does what a link in the app does: it shows in the timeline as the key's user, the inbox's automations for a linked issue run, and Chirp writes a link back to the conversation on the Linear issue. If Linear refuses the link back, the link is still made and Chirp tries again later. The API does not post the customer's message on the issue as a comment.
With snooze true, the conversation is snoozed until the issue is completed or canceled; an issue that is closed already does not snooze it. Linking an issue that is linked already changes nothing: the answer has created false and the link that exists.
Parameters
idpath · stringrequired
The conversation's id.
Request body
issuestringrequired
The issue's identifier, such as ENG-42, or its Linear URL.
snoozeboolean
Snooze the conversation until the issue closes. The default is false.
expectedVersioninteger
Refuse the change with 409 if the conversation's version is no longer this.
Response
200 The link and the conversation's workflow state · IssueLinkResult
Errors
400invalid_request
A field is missing, unknown or not valid, or Linear has no such issue in the connected workspace (`linear_issue_not_found`).
401unauthorized
The API key is missing, invalid, revoked or expired.
402payment_required
The workspace is read-only until an admin adds a payment method. Read operations still work.
403insufficient_scope
The key lacks the scope this operation needs.
404not_found
No such conversation, or the key's user cannot see its inbox.
409conflict
The inbox has Linear off (`linear_disabled`), or the workspace has no working Linear connection (`linear_not_connected`): an admin connects Linear in Chirp under Settings → Integrations. Also sent with `conflict` when expectedVersion no longer matches.
413payload_too_large
The JSON body exceeds 64 KB.
429rate_limited
The key used up its requests for this minute.
500internal_error
The server failed to complete the request.
502upstream_error
Linear failed or refused the request. Nothing was linked.
Remove a link by its id, from the list of linked issues. The removal shows in the timeline as the key's user, and Chirp removes its link back from the Linear issue. The Linear issue itself does not change. If Linear refuses the removal, the local link is still removed and the response includes attachmentError: remove the link back manually in Linear.
If this issue kept the conversation snoozed and no other linked issue does, the conversation goes back to open: nothing else could wake it.
Parameters
idpath · stringrequired
The conversation's id.
linkIdpath · stringrequired
The issue link's id.
Response
200 The conversation's workflow state
Errors
401unauthorized
The API key is missing, invalid, revoked or expired.
402payment_required
The workspace is read-only until an admin adds a payment method. Read operations still work.
403insufficient_scope
The key lacks the scope this operation needs.
404not_found
No such conversation, or the key's user cannot see its inbox. Also sent when the conversation has no link with this id.
Start a new conversation with one message, sent now from the inbox with its From name and signature. The app's undo window does not apply. Send an Idempotency-Key so a retry cannot send twice.
A 201 means Chirp recorded the message, not that it was delivered. Check state: only sent means the mail provider accepted it. On failed the provider refused it; on unknown, read the conversation before you send again.
Parameters
Idempotency-Keyheader · string (uuid)
A UUID. A retry with the same key returns the first result instead of doing the work again.
Request body
inboxIdintegerrequired
The inbox to send from. The key's user must be able to see it.
tostring (email)required
One recipient address.
subjectstringrequired
The subject, 1–200 characters.
bodystringrequired
The text, 1–10000 characters. The inbox signature is added. A URL in the text (`https://…`) is a link in the HTML part of the mail, and `[text](https://…)` is a link on that text; only http, https and mailto targets count, and each other character is sent as text, never as HTML. The plain text part has `text (url)`.
A field is missing, unknown or not valid, or Idempotency-Key is not a UUID.
401unauthorized
The API key is missing, invalid, revoked or expired.
402payment_required
The workspace is read-only until an admin adds a payment method. Read operations still work.
403insufficient_scope
The key lacks the scope this operation needs.
404not_found
No such inbox, or the key's user cannot see it.
409conflict
The inbox cannot send mail right now; its connection needs attention in Chirp.
413payload_too_large
The JSON body exceeds 64 KB.
429rate_limited
The key used up its requests for this minute.
500internal_error
The server failed to complete the request.
Request
curl -X POST https://app.teamchirp.io/v1/conversations \
-H "Authorization: Bearer $CHIRP_API_KEY" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{"inboxId":1,"to":"[email protected]","subject":"Your refund for order 5521","body":"Hi Dana, we have refunded the second charge."}'
Send a reply now, from the conversation's inbox with its From name and signature. The app's undo window does not apply. Send an Idempotency-Key so a retry cannot send twice.
A reply goes to all people of the latest incoming message (reply-all). To is the sender of that message. Cc is each other address in its To and Cc lists, without the addresses of your workspace's inboxes and without a duplicate, at most 50 addresses. Send cc to name the Cc addresses yourself; cc: [] sends to the sender only. The response returns the to and cc of the sent message. Before 2026-10, a reply went to the sender only.
A 201 means Chirp recorded the message, not that it was delivered. Check state: only sent means the mail provider accepted it. On failed the provider refused it; on unknown, read the conversation before you send again.
Parameters
idpath · stringrequired
The conversation's id.
Idempotency-Keyheader · string (uuid)
A UUID. A retry with the same key returns the first result instead of doing the work again.
Request body
bodystringrequired
The reply's text, 1–10000 characters. The inbox signature is added. A URL in the text (`https://…`) is a link in the HTML part of the mail, and `[text](https://…)` is a link on that text; only http, https and mailto targets count, and each other character is sent as text, never as HTML. The plain text part has `text (url)`.
ccarray of string
The Cc addresses of the reply. It replaces the default list; an empty list sends to the sender only. Each address must be in the default list (compare without case): you can leave a person out, but you cannot add one. Another address answers 400 with the code `cc_not_allowed`, and nothing is sent. When the Cc header of the latest incoming message is not read yet (its `cc` is null), the default list has the people of its To header only.
The body is empty or too long, a field is unknown, `cc` is not a list of at most 50 strings, or Idempotency-Key is not a UUID. A `cc` address that is not on the latest incoming message answers with the code `cc_not_allowed`.
401unauthorized
The API key is missing, invalid, revoked or expired.
402payment_required
The workspace is read-only until an admin adds a payment method. Read operations still work.
403insufficient_scope
The key lacks the scope this operation needs.
404not_found
No such conversation, or the key's user cannot see its inbox.
413payload_too_large
The JSON body exceeds 64 KB. Also sent when the finished message exceeds 10 MB.
429rate_limited
The key used up its requests for this minute.
500internal_error
The server failed to complete the request.
Request
curl -X POST https://app.teamchirp.io/v1/conversations/1042/replies \
-H "Authorization: Bearer $CHIRP_API_KEY" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{"body":"Sorry about that, Dana. We have refunded the second charge."}'
A machine-readable code. Branch on this, not on the message. One of invalid_request, unauthorized, payment_required, forbidden, not_found, conflict, payload_too_large, rate_limited, upstream_error, insufficient_scope, internal_error, unknown_assignee, unknown_inbox, cc_not_allowed, attachment_too_large, linear_disabled, linear_not_connected, linear_issue_not_found.
The customer's address: the latest incoming sender, or the recipient when no message came in.
previewstringrequired
The first line of the latest message.
latestAtstring (date-time)required
When the latest message arrived or was sent. The list is ordered by this, newest first.
messageCountintegerrequired
How many messages the conversation holds.
statusstringrequired
The conversation's status. One of open, pending, snoozed, closed.
snoozedUntilstring (date-time) | nullrequired
When a snoozed conversation wakes. Null when the status is not snoozed. Null also for a snoozed conversation that no time wakes: it waits for the customer's reply, or for a linked issue whose `snooze` is true. A customer's reply always wakes it.
A conversation's workflow state: what a write call changes.
idstringrequired
The conversation's id.
inboxobjectrequired
The conversation's inbox.
inbox.idintegerrequired
The inbox's id.
inbox.addressstring (email)required
The inbox's email address.
statusstringrequired
The conversation's status. One of open, pending, snoozed, closed.
snoozedUntilstring (date-time) | nullrequired
When a snoozed conversation wakes. Null when the status is not snoozed. Null also for a snoozed conversation that no time wakes: it waits for the customer's reply, or for a linked issue whose `snooze` is true. A customer's reply always wakes it.
assigneeobject | nullrequired
The assigned teammate, or null when unassigned.
tagsarray of objectrequired
Its tags, by name.
tags[].idstringrequired
The tag's id.
tags[].namestringrequired
The tag name, 1–32 characters.
versionintegerrequired
Goes up by one with each change. Send it back as expectedVersion to refuse a change made on stale data.
incoming from the customer, or sent from the inbox. One of incoming, sent.
fromstringrequired
The From address.
tostringrequired
The To address.
ccarray of string | nullrequired
The Cc addresses, in the order of the header; empty when the message has none. Null when Chirp has not read them yet (a message from before this field); do not read null as "no Cc". Bcc is never returned.
subjectstringrequired
The subject.
bodystringrequired
The plain-text body. For a message without usable plain text, text derived from its HTML part when available. For a sent message with a link, the link reads `text (url)`.
createdAtstring (date-time)required
When it arrived or was sent.
authorstring | nullrequired
The id of the teammate who sent it, or null for an incoming message.
attachmentsarray of objectrequired
Its attachments, with the inline images of an HTML email. The download operation takes the message's id and the attachment's index.
attachments[].indexintegerrequired
Its position in the message, from 0. Use it to download the content.
attachments[].filenamestringrequired
The file name.
attachments[].contentTypestringrequired
The MIME type.
attachments[].sizeintegerrequired
The size in bytes.
statestring | nullrequired
For a sent message, its outbox state: held (in the app's undo window), sending, sent, failed or unknown. Null for an incoming message. One of held, sending, sent, failed, unknown.
One entry in a conversation's timeline: a note or a change.
idstringrequired
The entry's id.
kindstringrequired
What happened. A note carries its text in body; a change carries its data in detail. One of note, status, assignment, tag_add, tag_remove, reopened, issue_link, issue_unlink, issue_state, automation.
bodystring | nullrequired
A note's text; null for other kinds.
detailobjectrequired
The change's data, which depends on kind (for example from and to for status). Empty for a note.
actorobject | nullrequired
Who made it, or null for the system (an automation or an incoming message).
createdAtstring (date-time)required
When it happened.
parentNoteIdstring | nullrequired
For a reply to a note, the note's id; otherwise null.
A conversation with its messages, timeline and linked issues.
idstringrequired
The conversation's id.
inboxobjectrequired
The conversation's inbox.
inbox.idintegerrequired
The inbox's id.
inbox.addressstring (email)required
The inbox's email address.
statusstringrequired
The conversation's status. One of open, pending, snoozed, closed.
snoozedUntilstring (date-time) | nullrequired
When a snoozed conversation wakes. Null when the status is not snoozed. Null also for a snoozed conversation that no time wakes: it waits for the customer's reply, or for a linked issue whose `snooze` is true. A customer's reply always wakes it.
assigneeobject | nullrequired
The assigned teammate, or null when unassigned.
tagsarray of objectrequired
Its tags, by name.
tags[].idstringrequired
The tag's id.
tags[].namestringrequired
The tag name, 1–32 characters.
versionintegerrequired
Goes up by one with each change. Send it back as expectedVersion to refuse a change made on stale data.
The outcome of a send. The response is 201 whenever Chirp recorded the message, even when delivery failed: check state.
conversationIdstringrequired
The conversation's id.
messageIdstringrequired
The sent message's id.
tostringrequired
The address in the To header of the sent message.
ccarray of stringrequired
The addresses in the Cc header of the sent message; empty when it has none. Each of them receives the message.
statestringrequired
sent: the mail provider accepted the message. failed: the provider refused it. unknown: the outcome is not known, for example after a timeout; check the conversation before you send again. sending: a retry with the same Idempotency-Key arrived while the first send was still running. One of sending, sent, failed, unknown.