Endpoint reference

POST /api/extract-text

Get the text and tables out of a born-digital PDF: reading-order text for each page, every line with its position, and tables as rows of cells. Returns JSON, or plain text with format=text.

Born-digital means the PDF was made by software (an invoice system, a bank, a word processor, a reporting tool), so the text is stored in it. Scanned pages are pictures of text and need OCR, which this endpoint does not do; they come back empty and listed in pagesWithoutText.

Request

Method: POST. URL: https://pdfops.dev/api/extract-text. Body: multipart/form-data.

FieldTypeRequiredDescription
pdfFile (PDF binary)YesExactly one PDF, up to 4 MB and 2,000 pages. The whole request must stay under 4.5 MB, Vercel's platform request limit.
pagesStringNoPages to read, 1-based: 1-3,5,8-. Default: every page. At most 200 pages are returned per call.
formatStringNojson (default) or text.
tables_formatStringNojson (default) or csv. With csv, each table also carries a csv string. Applies to format=json only; ignored with format=text. See Tables as CSV.
passwordStringNoOpens a PDF that needs a user password. Not needed for owner-locked files with an empty user password.

The optional X-API-Key header works as on /api/merge: no header is anonymous, 100 requests per IP per month; a valid key uses your tier's quota; an invalid or revoked key returns 401 invalid_api_key. A successful (2xx) call counts 1 request, however many pages it reads. Check consumption with GET /api/usage.

Response

On success with format=json: 200 OK, Content-Type: application/json.

{
  "pageCount": 1,
  "pages": [
    {
      "page": 1,
      "width": 612,
      "height": 792,
      "text": "INVOICE INV-1001\nDate: 2026-11-01\n...",
      "lines": [
        { "text": "INVOICE", "x": 54, "y": 728, "width": 106.91, "fontSize": 26 },
        { "text": "USD 1,200.00", "x": 495.19, "y": 538, "width": 62.81, "fontSize": 10 }
      ],
      "tables": [
        {
          "x": 54, "y": 478, "width": 504, "height": 95,
          "rows": [
            ["DESCRIPTION", "QTY", "UNIT", "AMOUNT"],
            ["API integration work", "10", "USD 120.00", "USD 1,200.00"],
            ["Edge deployment", "1", "USD 450.50", "USD 450.50"]
          ]
        }
      ]
    }
  ],
  "pagesWithoutText": [],
  "truncated": false
}
KeyDescription
pageCountPages in the whole document, whichever ones you asked for.
pages[].textThe page's text in the order the PDF stores it, which is reading order for almost every document. Lines are joined with \n.
pages[].linesEach run of text on one baseline with no wide gap, with its position. A table row or a two-column layout gives several lines with the same y.
pages[].tablesTables found on the page: rows is an array of rows, each an array of cell strings, every row the same length. Empty cells are "".
pages[].tables[].csvOnly with tables_format=csv: the same table as CSV text. See Tables as CSV.
pagesWithoutTextRequested pages with no text layer, usually scans.
truncatedtrue when more than 200 pages were asked for or the output passed 4 million characters. pages is then the first part; ask for the rest with pages.

With format=text: 200 OK, Content-Type: text/plain, the pages' text separated by a form feed (\f), the same convention as pdftotext. A capped response carries the header X-PDFops-Truncated: true.

On any failure: 4xx or 500, Content-Type: application/json, body is { "error": "<code>", "details": "<explanation>" }.

Coordinates

Positions are in PDF points, 72 to the inch, measured from the bottom-left corner of the page as a viewer shows it, after any rotation or crop box. x is where the text starts and y is its baseline. That is the frame /api/edit uses, so a label you find here can be written next to with one more call. width and height on each page are its displayed size.

How tables are found

Tables are detected from where the text sits, not from drawn lines, so borderless tables work. Three or more consecutive rows that each split into two or more cells, with the cells lining up in columns, make a table. Left-, right- and centre-aligned columns are all handled, and a header cell that spans two columns lands in one of them without merging them. Known limits:

Tables as CSV

Send tables_format=csv with format=json and every table gains a csv field next to rows, which is unchanged. The string is RFC 4180 CSV: a cell is quoted when it contains a comma, a double quote, a carriage return or a line feed, quotes inside a cell are doubled, and every record, the last included, ends with \r\n. The default, tables_format=json, leaves the response as described above. With format=text the field is ignored. The csv text counts toward the response's 4 million character cap, so a very large result can stop earlier than without it.

"rows": [["DESCRIPTION", "QTY", "AMOUNT"], ["API integration work", "10", "USD 1,200.00"], ["Support, annual", "1", "=SUM(A1)"]],
"csv": "DESCRIPTION,QTY,AMOUNT\r\nAPI integration work,10,\"USD 1,200.00\"\r\n\"Support, annual\",1,=SUM(A1)\r\n"

Spreadsheet formulas. Cell values are returned exactly as found in the PDF; nothing is added or changed. A cell that begins with =, +, - or @ (or a tab or carriage return) can be run as a formula when the CSV is opened in Excel, Google Sheets or similar. If you open the file in a spreadsheet, sanitise those cells first (for example by prefixing a single quote), or import the column as text.

Error codes

Error codeStatusTrigger
invalid_multipart400Request body could not be parsed as multipart/form-data.
missing_pdf400The request does not have exactly one pdf file field.
pdf_too_large400The pdf file is over 4 MB.
invalid_pdf400The PDF could not be parsed (corrupt, or not a PDF).
encrypted_pdf400The PDF needs a password we were not given. Send it as the password form field.
decompressed_too_large400Streams inside the PDF decompress to over 32 MB.
too_many_pages400The PDF has over 2,000 pages.
invalid_pages400pages is not a valid page spec or names a page past the end.
invalid_format400format is not json or text.
invalid_tables_format400tables_format is not json or csv.
request_too_large413The whole request body is over 4.5 MB (Vercel's platform request limit). Rejected before anything is parsed.
invalid_api_key401An X-API-Key header was sent but the key is unknown or revoked. Get a fresh key at /pricing.
rate_limited429The anonymous per-IP limit (100/month) or your key's monthly quota is used up. Retry-After gives seconds until next calendar month.

Example

Pull the line items out of an invoice:

curl -X POST https://pdfops.dev/api/extract-text \
  -F "pdf=@invoice.pdf" \
  -H "X-API-Key: pdfops_live_..." \
  | jq '.pages[0].tables[0].rows'   # optional key raises your quota to your tier

Plain text of pages 1 to 3, for a search index or a prompt:

curl -X POST https://pdfops.dev/api/extract-text \
  -F "pdf=@report.pdf" -F "pages=1-3" -F "format=text" -o report.txt

Each table as CSV, ready to write to a file:

curl -X POST https://pdfops.dev/api/extract-text \
  -F "pdf=@invoice.pdf" -F "tables_format=csv" \
  | jq -r '.pages[0].tables[0].csv' > table.csv

Keyless calls work: 100 requests per IP per month with no key.

Using this for real? A free API key raises the keyless 100 calls per IP to 250 requests a month, with no card.

Get a free API key

Code examples

Have an API key? Add an X-API-Key header to any request. It is optional, and it raises your quota from 100/IP/month to your tier's.

JavaScript (Node.js 22+) — built-in fetch + FormData
import { readFile } from 'node:fs/promises';

const fd = new FormData();
fd.append('pdf', new Blob([await readFile('invoice.pdf')], { type: 'application/pdf' }), 'invoice.pdf');

const res = await fetch('https://pdfops.dev/api/extract-text', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.PDFOPS_API_KEY }, // optional
  body: fd,
});
if (!res.ok) {
  const err = await res.json();
  throw new Error(`PDFops extract failed: ${err.error}: ${err.details}`);
}
const { pages } = await res.json();
for (const table of pages[0].tables) console.table(table.rows);
Python — requests
import os, requests

with open("invoice.pdf", "rb") as pdf:
    res = requests.post(
        "https://pdfops.dev/api/extract-text",
        headers={"X-API-Key": os.environ.get("PDFOPS_API_KEY", "")},  # optional
        files={"pdf": pdf},
    )
res.raise_for_status()
for page in res.json()["pages"]:
    print(page["text"])
    for table in page["tables"]:
        for row in table["rows"]:
            print(" | ".join(row))

From an AI agent (MCP)

The hosted MCP server at https://pdfops.dev/api/mcp exposes this as the pdf_extract_text tool. It takes the PDF as an https:// URL or a data:application/pdf;base64,… URI, returns text and tables, and adds the positioned lines only when you set include_lines, to keep the output small. See PDFops for AI agents.

Behavioral notes

FAQ

How do I extract text from a PDF with an API?

POST the PDF as the pdf field of a multipart request to https://pdfops.dev/api/extract-text. The response has one entry per page with its text in reading order, every line with its position, and any tables. Add format=text to get plain text instead, with pages separated by a form feed.

How do I extract a table from a PDF?

Call /api/extract-text and read pages[].tables. Each table has rows, an array of rows that are each an array of cell strings, plus its position on the page. Tables are found from where the text sits, so they work without ruling lines; check the output on a sample of your documents, because a cell that wraps onto a second line comes back as its own row.

Does it work on scanned PDFs?

No. A scanned page is a picture of text with no text layer, and this endpoint does not run OCR. Those pages come back with empty text and are listed in pagesWithoutText, so you can route them elsewhere.

How do I extract text from only some pages?

Send a pages field with a page spec such as 1-3,5 or 10-. Up to 200 pages come back per call; for longer documents, call again with the next range.

Can I use the positions to add something next to the text?

Yes. Line coordinates use the same frame as /api/edit: points from the bottom-left of the page as displayed, with y on the text baseline. Find the label you want, then send an /api/edit item at its x plus width to write beside it.

Related: Add text and images at a position · List form fields · Read page count and metadata.

Get a free API key. Keyless calls get 100 requests per IP per month; a free key raises that to 250, with no card. Enter your email and the key arrives in your inbox.

Get a free API key