Docs·API reference

Convert

POST /v1/convert turns a PDF, Word, HTML or email file into plain text that you can send to /v1/answers or /v1/extract.

HTTP
POST https://platform.xerj.ai/v1/convert
Authorization: Bearer $XERJ_API_KEY

Convert is free of token charges. Each call counts against your requests per minute.

Request #

Send the file in one of two ways.

As JSON, with the file in base64:

Field Type Required Description
filename string yes The file name. Its extension picks the converter.
content_base64 string yes The file bytes, base64-encoded.

As the raw body, with the file name in a header:

Header Description
x-filename The file name, for example invoice.pdf.

Files are up to 10 MB.

Supported files #

Converted to text Read as UTF-8 text
pdf, docx, html, htm, eml, mbox (the first message) txt, md, csv, tsv, json, xml, log, yaml, yml

PDFs need a text layer. A scanned PDF that is only images has no text to extract: run OCR first.

Response #

Field Type Description
object string Always "document".
filename string The name you sent.
format string The detected format, such as "pdf".
text string The plain text. Send this as document.
chars integer The length of text in characters.
note string What was done, such as “Text extracted from a 2-page PDF.”
JSON
{
  "object": "document",
  "filename": "invoice.pdf",
  "format": "pdf",
  "text": "INVOICE\n\nInvoice number: INV-20931\n…",
  "chars": 562,
  "note": "Text extracted from a 1-page PDF."
}

Examples #

curl
# raw body
curl https://platform.xerj.ai/v1/convert \
  -H "Authorization: Bearer $XERJ_API_KEY" \
  -H "x-filename: invoice.pdf" \
  --data-binary @invoice.pdf

# JSON with base64
curl https://platform.xerj.ai/v1/convert \
  -H "Authorization: Bearer $XERJ_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"filename\": \"invoice.pdf\", \"content_base64\": \"$(base64 -w0 invoice.pdf)\"}"
Python
d = client.convert.create(file="invoice.pdf")   # a path, bytes, or a file object (+ filename=)
print(d.format, d.chars, d.note)

r = client.answers.create(document=d.text, question="What is the total amount due?")
JavaScript
import { readFile } from "node:fs/promises";

const d = await client.convert.create({ file: await readFile("invoice.pdf"), filename: "invoice.pdf" });
console.log(d.format, d.chars, d.note);

const r = await client.answers.create({ document: d.text, question: "What is the total amount due?" });

Offsets after conversion #

Answers about converted text carry offsets into text, the converted text, not into the original file. Keep text if you want to highlight answers later, and show that text to your users.

Convert a file once, keep the text, and ask as many questions as you need.

Errors #

Status Code When
400 invalid_file No file name, the base64 is not valid, the body is neither JSON nor a raw file with x-filename, or the file cannot be read.
400 unsupported_file_type The extension is not in the list above.
400 file_too_large The file is larger than 10 MB.
413 request_too_large The request body is far larger than the file limit.
429 requests_per_minute See rate limits.