Skip to main content

Read document content

Read the extracted content of a processed document from your own system. This includes text from a PDF and the transcription of an audio attachment, such as an employee's voice brief or a WhatsApp message. First find its document ID and wait for processing, then retrieve the content:

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

For employee creation, send the brief through preparation so it is saved with the conversation. For lasting sources, upload into a connected collection. Both use document processing, but they serve different purposes and retain their own access boundaries.

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 DOCANA_API_KEY=your_api_key_here    # see Generating API Keys

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 ${DOCANA_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​

Processing starts after upload. Poll until COMPLETED, or stop and inspect the failure if the status is FAILED:

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

3. Read the content​

curl "https://platform.docana.com/api/v1/documents/67508/content/" \
  -H "Authorization: ApiKey ${DOCANA_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​