Cognita — The document understanding engine for AI

Introduction

Integrating with an AI assistant?

Copy the entire API reference as Markdown and paste it into Cursor, Claude, or ChatGPT to wire Cognita into your code.

Cognita is a document-understanding engine. Send a file, get structured, AI-native JSON — an Intermediate Representation (headings, paragraphs, tables, lists, images, reading order, bounding boxes) plus ready-to-use Markdown, plain text and retrieval-ready chunks. Output is deterministic: identical input yields byte-identical output.

All endpoints are served under a single base URL:

base URL

https://api.cognita.rahulrawat.in

Authentication

Every route except GET /health requires authentication. Create an account, generate an API key from your dashboard, and pass it in the X-API-Key header (a Bearer token also works).

Create an account Manage your key

curl

curl -s -H "X-API-Key: cog_your_key" \
  -F "file=@report.pdf" \
  https://api.cognita.rahulrawat.in/v1/parse

One key per account, shown in full only once. Rotate it from the dashboard to revoke the old key and issue a new one.

Quickstart

Upload a document as multipart form data (field file) — or send the raw bytes as the request body. Both work on every parsing endpoint.

request

curl -s -H "X-API-Key: cog_your_key" \
  -F "file=@q3-report.docx" \
  "https://api.cognita.rahulrawat.in/v1/parse?include=markdown,metadata"

response · application/json

{
  "markdown": "# Q3 Report\n\nRevenue grew **18%** this quarter.",
  "metadata": { "title": "Q3 Report", "page_count": 1 }
}

Parse a document

POST/v1/parse

Returns the full IR plus rendered Markdown, text, metadata and one image per page.

Parameter	Values	Default
include	comma list of document,markdown,text,metadata,page_images	all	Select response fields.
image_data	omit	included	Strip embedded image bytes from the IR (dimensions/MIME stay).
languages	e.g. eng+deu	server default	OCR language override for scanned pages.

smaller response — Markdown only

curl -s -H "X-API-Key: cog_your_key" \
  -F "file=@contract.pdf" \
  "https://api.cognita.rahulrawat.in/v1/parse?include=markdown"

Response (200):

application/json

{
  "document": {
    "id": "324b1b83a80680d9",
    "source_format": "docx",
    "metadata": { "title": "Q3 Report", "page_count": 1 },
    "pages": [
      { "number": 1, "width": 612, "height": 792, "unit": "pt",
        "blocks": [
          { "id": "p1-b0", "type": "heading", "level": 1, "reading_order": 0, "confidence": 1, "text": "Q3 Report" },
          { "id": "p1-b1", "type": "paragraph", "reading_order": 1, "text": "Revenue grew 18% this quarter.",
            "spans": [ { "text": "Revenue grew " }, { "text": "18%", "style": { "bold": true } }, { "text": " this quarter." } ] }
        ] }
    ]
  },
  "markdown": "# Q3 Report\n\nRevenue grew **18%** this quarter.",
  "text": "Q3 Report\n\nRevenue grew 18% this quarter.",
  "metadata": { "title": "Q3 Report", "page_count": 1 },
  "page_images": [ { "page": 1, "mime": "image/png", "data": "<base64>", "source": "rendered" } ]
}

RAG chunks

POST/v1/chunk

Structure-aware chunks that never split mid-block, carry heading breadcrumbs, and cite the exact pages and block IDs they came from. Accepts a file upload or a previously returned IR document as application/json.

Parameter	Values	Default
max_chars	integer	2000	Target maximum characters per chunk.
overlap	integer	0	Character overlap between adjacent chunks.

curl -s -H "X-API-Key: cog_your_key" \
  -F "file=@handbook.pdf" \
  "https://api.cognita.rahulrawat.in/v1/chunk?max_chars=800"

Response (200):

application/json

{
  "document_id": "324b1b83a80680d9",
  "count": 1,
  "chunks": [
    { "id": "c0", "text": "Q3 Report\n\nRevenue grew 18% this quarter.",
      "heading_path": ["Q3 Report"], "pages": [1], "block_ids": ["p1-b0", "p1-b1"], "chars": 42 }
  ]
}

Export / re-render

POST/v1/export?format=markdown|html|text|json

Re-render an IR document (the document object from a parse response) to another format.

curl -s -H "X-API-Key: cog_your_key" \
  -H "Content-Type: application/json" \
  --data-binary @document.json \
  "https://api.cognita.rahulrawat.in/v1/export?format=html"

Stored documents

Parse once, then retrieve, export, chunk or fetch page images later.

POST/v1/parsefile → IR + Markdown + text + metadata + page images

POST/v1/parse/streamsame, streamed live — every stage as it happens (SSE)

POST/v1/chunkfile or IR JSON → structure-aware RAG chunks

GET/v1/searchfull-text search across your stored documents

GET/v1/documents/{id}/contextpack the top blocks into a token budget, cited

POST/v1/documents/{id}/queryselect blocks by a deterministic selector

POST/v1/documents/{id}/transformrecompile: drop / keep / filter / redact

GET/v1/documents/{id}/fidelityreconstruction fidelity score + issues

GET/v1/documents/{id}/locateresolve a citation ref to its page region

GET/v1/documents/{id}/pages/{n}/imageone page as a rendered image

Async jobs

For large files or long parses, submit a job instead of holding a request open. You get a job id immediately, poll for status, then fetch the result. The finished result is also saved to your library, so its document_id works with every stored-document route above.

POST/v1/jobs

Same body and query parameters as /v1/parse. Returns 202 with the job; counts against your daily limit.

GET/v1/jobsList your jobs, newest first.

GET/v1/jobs/{id}The job's current status.

GET/v1/jobs/{id}/resultThe result (like /v1/parse). 409 while running, 422 if failed.

A job moves through pending → running → succeeded | failed.

submit → poll → fetch result

JOB=$(curl -s -H "X-API-Key: cog_your_key" -F "file=@big-report.pdf" \
  https://api.cognita.rahulrawat.in/v1/jobs | jq -r .id)

# poll until the job finishes
while :; do
  S=$(curl -s -H "X-API-Key: cog_your_key" https://api.cognita.rahulrawat.in/v1/jobs/$JOB | jq -r .status)
  [ "$S" = "succeeded" ] || [ "$S" = "failed" ] && break
  sleep 2
done

curl -s -H "X-API-Key: cog_your_key" \
  "https://api.cognita.rahulrawat.in/v1/jobs/$JOB/result?include=markdown,metadata"

Job object:

application/json

{
  "id": "8dbeed8db9e120c4976b3b417998b81f",
  "status": "succeeded",
  "filename": "big-report.pdf",
  "size_bytes": 91234,
  "document_id": "95f63a17bd452836",
  "created_at": "2025-09-12T10:02:33Z",
  "started_at": "2025-09-12T10:02:34Z",
  "finished_at": "2025-09-12T10:02:51Z"
}

The IR

Every output is rendered from one common Intermediate Representation:

Document { id, source_format, metadata, pages }
  Page  { number, width, height, unit, blocks, images? }
    Block { id, type, page, bbox?, reading_order,
            confidence, level?, text, spans, style?,
            children?, table?, image?, image_ref? }
      Span { text, style?, link? }

Block IDs are deterministic (p2-b7 = page 2, reading order 7). Geometry survives for PDFs and scans, so answers can be highlighted on the page image.

Rate limits

Accounts on the free tier get 4 successful parses per day, counted per user and reset at 00:00 UTC. Every parse response carries the current budget:

response headers

X-RateLimit-Limit: 4
X-RateLimit-Remaining: 3
X-RateLimit-Reset: 1757635200

Once the limit is reached, parses return 429 Too Many Requests until the reset time.

Errors

Errors are uniform JSON with an HTTP status code:

{ "error": { "code": 415, "message": "unsupported format" } }

Status	Meaning
401	missing or invalid API key
413	upload too large
415	unsupported file format
422	unparseable document
429	daily parse limit reached