Skip to content

Files on tickets

A ticket can carry two kinds of document:

  • Attachments are links. You send a url and a name with POST /tickets and they are stored as given. Use them only for documents that are already public.
  • Files are stored by tkana, privately. You upload the bytes, and nobody can read them without a key that may read tickets. Use them for a customer’s own documents: an invoice, an ID, a photo of a damaged item.

A file never has a URL. That is the point of uploading it rather than linking it: a link works for anyone who has it, for as long as it exists, and a customer’s document must not be one forwarded email away from a stranger.

Send the file as multipart/form-data with one part named file. The key needs write:tickets.

  • Size: at most 10 MB.
  • Types: JPEG, PNG, GIF, WebP and HEIC images; PDF; plain text and CSV; Word (.doc, .docx) and Excel (.xls, .xlsx); MP4, MP3 and Ogg.
  • A JPEG, PNG, GIF, WebP or PDF must really be one: its bytes are checked against the type you declare, so a file declared application/pdf that is not a PDF is refused. Every other type, HEIC included, is accepted on its declared type alone.
  • A file is stored with the ticket’s customer’s data, so it is erased with them.
Terminal window
curl -s -X POST "$TKANA_API/tickets/$TICKET_ID/files" \
-H "Authorization: Bearer $TKANA_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-F "file=@invoice-1042.pdf;type=application/pdf"

Do not set Content-Type yourself: curl and every HTTP library write the multipart boundary into it, and a hand-written header without one cannot be parsed.

You get 201 with the stored file:

{
"id": "6f1c2a4e-8d0b-4b8e-9a51-1c3f0f6f2b7d",
"name": "invoice-1042.pdf",
"type": "application/pdf",
"size": 48213
}

name is the part’s filename and type is the part’s media type. The file appears at once on the ticket in the tkana portal, where the team works it.

Send an Idempotency-Key: a retried upload without one stores the file twice. See idempotency.

Code Status What to do
insufficient_scope 403 The key lacks write:tickets. An owner can widen it in the portal.
not_found 404 No ticket with that id in this organization.
payload_too_large 413 The file is over 10 MB.
validation_failed 422 No file part, an empty file, a type tickets do not accept, or a JPEG, PNG, GIF, WebP or PDF whose bytes are not one. errors names file and detail says which.

A refused upload stores nothing.

Every ticket response carries files, in the order they were added, beside attachments:

{
"id": "0d6a…",
"subject": "Refund for order 1042",
"attachments": [],
"files": [
{
"id": "6f1c2a4e-8d0b-4b8e-9a51-1c3f0f6f2b7d",
"name": "invoice-1042.pdf",
"type": "application/pdf",
"size": 48213
}
]
}

files also lists what staff uploaded in the portal, and what the customer sent over WhatsApp with their request when the AI agent filed the ticket from that conversation. All of them are downloaded the same way. For a customer’s WhatsApp file, type and size are null when WhatsApp did not report them.

Terminal window
curl -s "$TKANA_API/tickets/$TICKET_ID/files/$FILE_ID" \
-H "Authorization: Bearer $TKANA_KEY" \
-o invoice-1042.pdf

The response is the file itself, with its Content-Type and a Content-Disposition naming it. The key needs read:tickets; each download is checked against the key, so revoking a key or removing the scope stops it at once.

A file that is no longer stored answers 404.