API reference

Extract text, build knowledge graphs and ask questions about documents over HTTP. Every endpoint has cURL, Python and TypeScript examples.

Base URL

https://textview.ai

Authentication

Create a key on the API keys page and send it with every request.

Authorization: Bearer YOUR_API_KEY

Or send it as X-API-Key: YOUR_API_KEY. An invalid or revoked key returns 401.

Text extraction

Send a document and get its text with the layout preserved: columns, tables and reading order. Scans and images also come back with a document profile and page summaries.

Try it with a sample document

Download this sample invoice and send it to /api/v1/text.

PNG

Also accepts PDF, JPEG, TIFF, BMP, HEIF, DOCX, XLSX, PPTX, HTML.

POST/api/v1/textExtract text with its layout Auth

Extract text with its layout

https://textview.ai/api/v1/text

Send the file as multipart/form-data in the "file" field.
service=free is the default and fails with 422 on scans and images; the error names the services that can read the file. Use service=standard for a scan when plain text is enough, and service=premium when you need table borders, region geometry or page summaries.
When only some pages of a PDF are scans, the 422 lists them in scanned_pages. Send the same file again with page_services naming a service for each of those pages, or "skip", and the text pages are read for free in the same document.
Read text for the whole document, or pages[] for each page.

Details

Method	POST
Path	/api/v1/text
Authorization	API key
Credits	Free: no credits for the first 10,000 pages a calendar month, then about 0.09 a page. Standard: about 0.09 a page. Premium: about 0.69 a page, charged for the pages actually processed.

Headers

AuthorizationBearer YOUR_API_KEY

Content-Typemultipart/form-data

X-Project-Idoptional — file the document under a project

Form fields

Name	Type	Required	Description
file	file	Yes	PDF, PNG, JPEG, TIFF, BMP, HEIF, DOCX, XLSX, PPTX or HTML.
service	string	No	"free" (default) reads only PDFs that contain text — their words and their table borders both come from the file, so on such a file it is the most faithful option as well as the cheapest. "standard" reads any document and keeps its layout, without drawing table borders. "premium" draws table borders, recovers faint or shaded text the other two miss, returns region geometry, and summarises pages for chat.
page_numbers	string	No	Pages to extract: "1,3,5", a range such as "1-5", or both ("1-2,4,8"). Default: all pages. A value that is not a page or a range is a 400.
page_services	string	No	A service for some pages, as JSON: {"1": "premium", "2": "skip"}. Each named page is read with its own service ("free", "standard" or "premium"), or left out with "skip"; every other page uses service. One document comes back, charged for what each service read.
force_ocr	boolean	No	true re-extracts pages that are already cached, and charges for them.
session_id	string	No	Cache scope. Pages already extracted in the same session aren’t charged again.

Status codes

200Text extracted400Unsupported file, or page_numbers or page_services that cannot be read401Invalid token or key402Not enough credits422service=free on pages that are pictures. The body lists text_pages and scanned_pages, a preview of each scanned page, and an options array naming each service that can read them, with its price a page.

Example request

POST

bash

curl -X POST https://textview.ai/api/v1/text \
  -H "Authorization: Bearer $TEXTVIEW_API_KEY" \
  -F "file=@sample_image.png" \
  -F "service=standard"

Example response

200 OK

Bodyjson

{
  "status": "success",
  "text": "--- Page 1 · powered by textview.ai ---\n\n    TAX INVOICE ...",
  "pages": [
    { "page_number": 1, "text": "--- Page 1 · powered by textview.ai ---\n..." }
  ],
  "processed_pages": 1,
  "cached_pages": 0,
  "document_profile": {
    "doc_type": "invoice",
    "title": "Tax Invoice TVAI-2526-7788 for AlphaBeta Traders",
    "summary": "A tax invoice issued by Textview.AI to AlphaBeta Traders ...",
    "identifiers": [
      { "label": "invoice_number", "value": "TVAI-2526-7788" }
    ]
  },
  "page_cards": [
    { "page_number": 1, "page_title": "Tax Invoice Page (TVAI-2526-7788)" }
  ],
  "credits_charged": 0.444918,
  "ocr_cost": {
    "pages": 1,
    "lines": [
      { "item": "Text reading", "pages": 1, "usd_per_page": 0.006, "usd": 0.006 },
      { "item": "Line geometry", "pages": 1, "usd_per_page": 0.0018, "usd": 0.0018 },
      { "item": "Page summaries for chat, from text", "tokens": 9153, "usd": 0.00109836 }
    ],
    "cost_usd": 0.00889836,
    "credits": 0.444918
  },
  "history_id": "5b4e50ce-6d20-4c45-8026-9120e43c2f3c"
}

Document OCR

Every line, word and checkbox with its bounding box and confidence. Use it for form processing and annotation. For readable text, use /api/v1/text.

POST/api/v1/ocrGet lines, words and checkboxes with positions Auth

Get lines, words and checkboxes with positions

https://textview.ai/api/v1/ocr

Send the file as multipart/form-data in the "file" field.
Positions are in pixels for images and inches for PDFs (see unit).

Details

Method	POST
Path	/api/v1/ocr
Authorization	API key
Credits	About 0.09 credits a page, for the pages actually read.

Headers

AuthorizationBearer YOUR_API_KEY

Content-Typemultipart/form-data

Form fields

Name	Type	Required	Description
file	file	Yes	A PDF or image.
page_numbers	string	No	Pages to read: "1,3", a range such as "1-5", or both. Default: all pages. A value that is not a page or a range is a 400.
include_lines	boolean	No	Include lines. Default: true.
include_words	boolean	No	Include words with confidence. Default: true.
include_selection_marks	boolean	No	Include checkboxes and radio buttons with their state. Default: true.

Status codes

200Document read400Unsupported file401Invalid token or key402Not enough credits

Example request

POST

bash

curl -X POST https://textview.ai/api/v1/ocr \
  -H "Authorization: Bearer $TEXTVIEW_API_KEY" \
  -F "file=@sample_image.png"

Example response

200 OK

Bodyjson

{
  "status": "success",
  "document_info": {
    "metadata": {
      "filename": "sample_image.png",
      "processing_time_ms": 9252.6,
      "file_size_bytes": 2662876
    },
    "lines": [
      {
        "line_id": 1,
        "text": "Checked OK",
        "bounding_box": {
          "top_left": { "x": 880, "y": 17 },
          "top_right": { "x": 990, "y": 17 },
          "bottom_right": { "x": 990, "y": 21 },
          "bottom_left": { "x": 880, "y": 21 }
        },
        "dimensions": { "width": 1024, "height": 1536 },
        "unit": "pixel",
        "page": 1
      }
    ],
    "words": [
      { "word_id": 32, "text": "OK", "line_id": 1, "confidence": 0.997, "unit": "pixel", "page": 1 }
    ],
    "selection_marks": [],
    "statistics": {
      "total_lines": 344,
      "total_words": 600,
      "total_selection_marks": 0,
      "average_word_confidence": 0.973
    }
  },
  "credits_charged": 0.09,
  "ocr_cost": {
    "pages": 1,
    "lines": [
      { "item": "Word positions", "pages": 1, "usd_per_page": 0.0018, "usd": 0.0018 }
    ],
    "cost_usd": 0.0018,
    "credits": 0.09
  }
}

Knowledge graph

Build a graph of a document’s pages and identifiers, and ask questions about the document. Answers cite the passages they come from.

Chat models

Each request costs credits at the model’s price. Limits are per model, in tokens a minute and requests a second. If a model is busy, the API uses a lighter one and reports it in model_used and auto_switched.

Model id	Name	Available with	Best for	Tokens/min	Requests/s
compact-3bdefault	Compact 3B	Any credits	Cheapest and fastest, and reads document images. Short questions on short documents.	1,300,000	12.50
compact-8b	Compact 8B	Any credits	Finds more than Compact 3B and reads document images, but slower.	625,000	3.13
compact-14b	Compact 14B	Purchased credits	Best quality for detailed extraction and chat. Reads document images.	937,500	0.50
coder	Coder	Purchased credits	Code snippets, configs and technical references. Text only.	625,000	2.08

Any account can use compact-3b and compact-8b. The others need purchased credits; without them the API returns 403.

POST/api/v1/knowledge-graph/structuralBuild a page graph of a document Auth

Build a page graph of a document

https://textview.ai/api/v1/knowledge-graph/structural

Send the history_id from /api/v1/text.
Nodes are the document, its pages, and the identifiers each page prints.
Edges connect a page to what it prints, with the text as the citation.
The response also reports offer_model_graph: whether this document would be worth reading with a model instead.

Details

Method	POST
Path	/api/v1/knowledge-graph/structural
Authorization	API key
Credits	Free. No model runs.

Headers

AuthorizationBearer YOUR_API_KEY

Content-Typeapplication/json

Body

Name	Type	Required	Description
document_ids	string[]	No	history_id values from /api/v1/text, up to 6. Shared identifiers become one node.
text	string	No	Document text, if it wasn’t extracted here. Send this or document_ids.
doc_name	string	No	Name for the document node when you send text.

Status codes

200Graph built400Neither document_ids nor text sent401Not signed in404No readable documents for those ids

Example request

POST

bash

curl -X POST https://textview.ai/api/v1/knowledge-graph/structural \
  -H "Authorization: Bearer $TEXTVIEW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["5b4e50ce-6d20-4c45-8026-9120e43c2f3c"]}'

POST/api/v1/knowledge-graph/generate/estimateWhat a model-built graph would cost Auth

What a model-built graph would cost

https://textview.ai/api/v1/knowledge-graph/generate/estimate

Call this before /generate so a price can be shown before anything is spent.
The completion figure is also the cap the model is given, so the estimate cannot be quietly exceeded.
The charge that follows is the real usage, which is usually lower.

Details

Method	POST
Path	/api/v1/knowledge-graph/generate/estimate
Authorization	API key
Credits	Free. No model runs, so asking the price costs nothing.

Headers

AuthorizationBearer YOUR_API_KEY

Content-Typeapplication/json

Body

Name	Type	Required	Description
document_ids	string[]	No	history_id values from /api/v1/text, up to 6.
document_text	string	No	Document text, if it was not extracted here. Send this or document_ids.
model	string	No	Model id from GET /api/v1/knowledge-graph/models. Prices follow the model.

Status codes

200Estimate returned: prompt_tokens, completion_tokens, cost_usd, credits, model_label400No document selected401Not signed in404No readable documents for those ids

Example request

POST

bash

curl -X POST https://textview.ai/api/v1/knowledge-graph/generate/estimate \
  -H "Authorization: Bearer $TEXTVIEW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["5b4e50ce-6d20-4c45-8026-9120e43c2f3c"]}'

POST/api/v1/knowledge-graph/generateBuild a graph of what the document discusses Auth

Build a graph of what the document discusses

https://textview.ai/api/v1/knowledge-graph/generate

Unlike /structural, this reads the pages and lists what the document is about: the parties, places, amounts and dates.
Every successful build is kept and listed by GET /builds — you were charged for it, so it is not lost if you do not save it.
Nothing is charged for a call that returns no graph.

Details

Method	POST
Path	/api/v1/knowledge-graph/generate
Authorization	API key
Credits	Charged for the tokens the model used, like a chat request. The response reports credits_charged.

Headers

AuthorizationBearer YOUR_API_KEY

Content-Typeapplication/json

Body

Name	Type	Required	Description
document_ids	string[]	No	history_id values from /api/v1/text, up to 6.
document_text	string	No	Document text, if it was not extracted here. Send this or document_ids.
signature	string	No	Your own key for this document selection, so the build can be found again with GET /builds.
model	string	No	Model id from GET /api/v1/knowledge-graph/models.

Status codes

200Graph built, charged, and kept400No document selected401Not signed in402Not enough credits404No readable documents for those ids

Example request

POST

bash

curl -X POST https://textview.ai/api/v1/knowledge-graph/generate \
  -H "Authorization: Bearer $TEXTVIEW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["5b4e50ce-6d20-4c45-8026-9120e43c2f3c"]}'

GET/api/v1/knowledge-graph/buildsGraphs you have kept: built for a price, saved, or edited Auth

Graphs you have kept: built for a price, saved, or edited

https://textview.ai/api/v1/knowledge-graph/builds

The graphs themselves are not in this list — fetch one with GET /api/v1/knowledge-graph/builds/{id}, which also returns its schema: the entity and relationship types it uses.
origin says who made each version: system (a free graph you saved), model (built for a price) or user (a graph whose schema you edited, with parent_id naming the version it came from).
POST /api/v1/knowledge-graph/builds keeps a graph as a system or user version, free; PATCH /api/v1/knowledge-graph/builds/{id} with {"name": "…"} names one.
Only your own builds are returned; another account’s id comes back as 404.

Details

Method	GET
Path	/api/v1/knowledge-graph/builds
Authorization	API key
Credits	Free.

Headers

AuthorizationBearer YOUR_API_KEY

Body

Name	Type	Required	Description
signature	string	No	Only builds for this document selection. Omit for every build you own.
limit	integer	No	How many to return, newest first. Up to 50; 20 by default.

Status codes

200A list: id, name, origin, parent_id, node_count, edge_count, credits_charged, model_label, created_at401Not signed in

Example request

GET

bash

curl https://textview.ai/api/v1/knowledge-graph/builds \
  -H "Authorization: Bearer $TEXTVIEW_API_KEY"

Example response

200 OK

Bodyjson

{
  "nodes": [
    { "id": "doc", "label": "Tax Invoice TVAI-2526-7788 for AlphaBeta Traders", "type": "document", "level": 0, "doc_type": "invoice" },
    { "id": "page_1", "label": "Page 1", "type": "page", "level": 1, "page_number": 1 },
    { "id": "ident_invoice_number_tvai_2526_7788", "label": "TVAI-2526-7788", "type": "identifier", "level": 2,
      "pages": [1], "key": "invoice_number", "value": "TVAI-2526-7788" }
  ],
  "edges": [
    { "source": "doc", "target": "page_1", "relation": "has_page", "citation": null },
    { "source": "page_1", "target": "ident_invoice_number_tvai_2526_7788", "relation": "invoice_number",
      "citation": "invoice_number: TVAI-2526-7788" }
  ]
}

POST/api/v1/knowledge-graph/chatAsk a question about one or more documents Auth

Ask a question about one or more documents

https://textview.ai/api/v1/knowledge-graph/chat

Send the document text and the conversation.
For several documents, send document_ids instead. pages_used counts pages across all of them, and page_sources maps each to its file and page.
Read reply. citations quotes the passages it used.
If a model is busy, the API uses a lighter one and sets auto_switched.

Details

Method	POST
Path	/api/v1/knowledge-graph/chat
Authorization	API key
Credits	The model’s price for the tokens used. A 4,000-token Compact 3B answer costs about 0.03 credits.

Headers

AuthorizationBearer YOUR_API_KEY

Content-Typeapplication/json

Body

Name	Type	Required	Description
document_text	string	No	The document’s text, usually text from /api/v1/text. Required unless you send document_ids.
document_ids	string[]	No	Two to six history_id values from /api/v1/text, to ask about those documents together. Every page of each is searched, and page_sources names each page’s file.
messages	object[]	Yes	The conversation so far, oldest first: { role: "user" \| "assistant", content }.
model	string	No	A model id. Default: compact-3b. Unknown ids use the default.
max_reply_tokens	integer	No	The most tokens the reply may use, from 1 up to 32,000. Default: 32,000. Longer replies take longer: up to about 3 minutes on compact-3b and 12 on coder at the maximum. A reply that reaches the limit ends with output_incomplete set.
graph	object	No	A graph from /structural, to steer which pages are read.

Status codes

200Answer400No message sent401Not signed in402Not enough credits403Model needs purchased credits404None of the document_ids are yours429Model busy

Example request

POST

bash

curl -X POST https://textview.ai/api/v1/knowledge-graph/chat \
  -H "Authorization: Bearer $TEXTVIEW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_text": "TEXT_FROM_API_V1_TEXT",
    "messages": [{ "role": "user", "content": "What is the carrier and the effective date?" }],
    "model": "compact-3b"
  }'

Example response

200 OK

Bodyjson

{
  "reply": "- **Carrier Name**: RoadRunner Express\n- **Effective Date**: 16-Feb-2026",
  "citations": ["Transporter : RoadRunner Express"],
  "model_used": "Compact 3B",
  "auto_switched": false,
  "usage": { "prompt_tokens": 4076, "completion_tokens": 135, "total_tokens": 4211, "finish_reason": "stop" },
  "pages_used": [1],
  "cost_usd": 0.00050532,
  "credits_charged": 0.025266
}

Credits

Every call is paid from your credit balance. Check it before a large batch: a call the balance can’t cover fails with 402.

What calls cost

POST /api/v1/text with service=free (PDFs that contain text)	Free for the first 10,000 pages each calendar month, then about 0.09 credits a page. Reads the text and the table borders the PDF already carries, so on such a file it is also the most faithful reading available.
POST /api/v1/text with service=standard	About 0.09 credits a page. Reads any document and keeps its layout, without drawing table borders. Faint or shaded text that Premium recovers may be missed.
POST /api/v1/text with service=premium	About 0.69 credits a page: reading, line geometry and page summaries for chat, charged for the pages each step actually processed. A one-page document is summarised from its text, so it costs less. The response lists each step in ocr_cost.
POST /api/v1/ocr	About 0.09 credits a page, for the pages actually read.
POST /api/v1/knowledge-graph/chat	The model's price for the tokens used. A 4,000-token Compact 3B answer costs about 0.03 credits.
POST /api/v1/knowledge-graph/structural	Free
POST /api/v1/knowledge-graph/generate/estimate	Free. Quotes a price and runs nothing.
POST /api/v1/knowledge-graph/generate	Charged for the tokens the model used, like a chat request. Estimate it first.
GET /api/v1/knowledge-graph/builds	Free
POST /api/v1/knowledge-graph/builds	Free. Keeps a graph you saved or whose schema you edited.
Pages already extracted	Free, from cache

1 credit is $0.02. When your balance can’t cover a call, it fails with 402. There are no token limits.

GET/api/v1/credits/balanceRead your credit balance Auth

Read your credit balance

https://textview.ai/api/v1/credits/balance

Send your API key. There is no body.
balance is what you can spend. total_used is total_granted plus total_purchased, minus balance.

Details

Method	GET
Path	/api/v1/credits/balance
Authorization	API key
Credits	Free.

Headers

AuthorizationBearer YOUR_API_KEY

Status codes

200Balance401Invalid token or key429Too many requests

Example request

GET

bash

curl https://textview.ai/api/v1/credits/balance \
  -H "Authorization: Bearer $TEXTVIEW_API_KEY"

Example response

200 OK

Bodyjson

{
  "balance": 947.66339,
  "total_granted": 1000.0,
  "total_purchased": 0.0,
  "total_used": 52.33661
}