Skip to main content

Automate document ingestion

Your documents don't live in Docana. They arrive from somewhere: a CRM export, a nightly report, an upload form in your product. This guide covers the loop that keeps Docana current: upload a file, wait for processing, and check what came out.

The four steps below paste in order. The CLI authenticates through docana login; only the curl variants need the key:

export DOCANA_API_KEY=your_api_key_here    # see Generating API Keys

1. Create a place for files​

Documents live in collections, and collections live in libraries. Create the structure once, in the UI or from the terminal, and keep the collection id it prints:

docana libraries create -n "Operations"
docana collections create -n "Contracts" -l <library-id>

export COLLECTION_ID=<the id from the output>

2. Upload​

From a script or your shell, the CLI is the shortest path:

docana documents push "$COLLECTION_ID" contracts/*.pdf

From your backend, it's one multipart request:

curl -X POST "https://platform.docana.com/api/v1/collections/${COLLECTION_ID}/documents/" \
  -H "Authorization: ApiKey ${DOCANA_API_KEY}" \
  -F "[email protected]"

The response returns one result per file, each carrying the new document:

{
  "success": true,
  "results": [
    { "document": { "id": 12345, "name": "contract-2026-08.pdf", … } }
  ]
}

Grab each document.id and keep it for the next step (export DOCUMENT_ID=12345), or look it up later with docana documents list -c "$COLLECTION_ID". Any file type Docana understands works: PDFs, Office documents, images, audio, video.

3. Wait for processing​

Ingestion is asynchronous: Docana extracts text, transcribes media, and indexes everything for search. Poll the status until it settles:

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

Or the same call from the terminal, no auth headers to manage:

docana api GET /api/v1/documents/12345/status/
{ "id": 12345, "status": "PROCESSING" }

The status moves from QUEUED through PROCESSING to COMPLETED or FAILED. Only act on those last two; the response is never cached, so polling is safe.

4. Check what came out​

Once a document is COMPLETED, two things are true.

It's searchable. Verify from the terminal, or from your own systems through the search API:

docana documents search "termination clause" -c "$COLLECTION_ID"
Document ID   Title                  Collection   Summary
12345         contract-2026-08.pdf   Contracts    Services agreement with 30-day termination…

Its content is readable. The extracted text, transcription, or image description is one GET away. See Read Document Content for what each file type returns.

Or let Docana do the syncing​

If your documents live in Google Drive, SharePoint, Notion, or similar, you may not need any of this: connectors sync those sources on a schedule. Build your own ingestion when the documents come from your product or a system without a connector.

Next steps​