Skip to main content

Read document content

A customer sends a voice note on WhatsApp. A PDF lands in a collection. By the time you ask, Docana has already done the hard part: transcribed the audio, extracted the text, read the charts, described the images. This guide is about taking that out. One GET returns the words from any file, ready for your own system:

GET /api/v1/documents/{id}/content/

What you get, by file type​

The same endpoint serves every type. Only the kind of content differs:

File typeWhat comes back
AudioVerbatim transcription with speaker labels, split into time windows
VideoPer time window: the spoken transcription, a description of the scene, and any text shown on screen
ImageA detailed visual description, plus the text read from the image (OCR)
PDF, Word, spreadsheetsThe extracted text, split into chunks. Embedded images and charts are described too

Scanned PDFs work too: Docana runs OCR, so a PDF with no selectable text still returns its content. Transcriptions and descriptions follow the user's locale. There is no per-request language parameter.

Set up once​

export API_KEY=your_api_key_here

Every curl below also runs from the terminal through the CLI's raw client, which reuses your docana login instead of headers. docana api GET /api/v1/documents/67508/content/ is the whole call.

1. Find the document id​

Ids come from wherever the document entered Docana:

  • You just uploaded it: the upload response carries the id. See Automate Document Ingestion.
  • It lives in a collection: list the documents and take each id. CLI: docana documents list -c <collection-id>.
  • It arrived in a conversation: read the thread's messages. Every attachment carries its document id:
curl "https://platform.docana.com/api/v1/threads/${THREAD_ID}/messages/" \
  -H "Authorization: ApiKey ${API_KEY}"
{
  "role": "USER",
  "content": [
    {
      "type": "file",
      "mediaType": "audio/mp4",
      "documentId": 67508,
      "url": "https://platform.docana.com/api/v1/documents/67508/download/",
      "viewUrl": "https://platform.docana.com/api/documents/67508/download/?vid=…"
    }
  ]
}

The documentId is what you need. The two links serve the original file: url needs your API key, and viewUrl works without credentials for a few hours. Hand the viewUrl to anything that can't send your key, like a chat client rendering an image.

:::note Older WhatsApp attachments Messages from before document-backed attachments are repaired the first time you fetch them by id. If the call returns 202, 409, or 503 with a Retry-After header, retry after the delay; within a few seconds the message comes back complete with its documentId. :::

2. Wait until it's ready​

Transcription runs right after a file arrives, usually seconds. Poll until COMPLETED:

curl "https://platform.docana.com/api/v1/documents/67508/status/" \
  -H "Authorization: ApiKey ${API_KEY}"
{ "id": 67508, "status": "COMPLETED" }

3. Read the content​

curl "https://platform.docana.com/api/v1/documents/67508/content/" \
  -H "Authorization: ApiKey ${API_KEY}"

For audio and video, each chunk is one transcribed time window:

{
  "id": 67508,
  "status": "COMPLETED",
  "chunks": [
    {
      "index": 0,
      "content": "# Timestamp: [0:00 - 0:28]\n\n# Transcription:\nSpeaker 1: Good afternoon, I'd like to ask about...",
      "startOffsetSec": 0,
      "endOffsetSec": 28
    }
  ],
  "totalCount": 1
}

For a PDF or document, each chunk is a piece of the document, including described images:

{
  "id": 12345,
  "status": "COMPLETED",
  "chunks": [
    { "index": 0, "content": "Customer Satisfaction Report — Q2 2026" },
    { "index": 1, "content": "3. Satisfaction by segment\nMost respondents rated..." },
    { "index": 2, "content": "[Image: bar chart of satisfaction by age group; '18-25' at ~72%, '26-40' at ~85%]" }
  ],
  "totalCount": 8
}

Join the chunks in index order to rebuild the whole document. Long documents are paginated: pass page and limit, and use totalCount to know when you have everything.

Next steps​