Document Upload API
Every PDF Editor operation starts with an upload. The POST /pdf/documents endpoint takes the file as multipart/form-data, returns a document id (doc_...) right away and runs the processing in the background. If scanned pages are detected, OCR runs automatically.
Prepare an API Key
Create a key with the pdf:write scope under Settings → API Keys and put it in the INCAPON_API_KEY environment variable. Use inc_test_... keys for experiments; documents uploaded with test keys are deleted after 24 hours and no credits are charged.
Upload the File
The file field is required in the request body. The optional ocr_languages field sets the OCR languages, and the metadata field carries a free-form JSON object for matching against your own system.
Wait for Processing to Finish
A document moves through uploaded → processing → processed; on an error it becomes failed. Instead of polling, listen for the document.processed webhook event; its payload contains the page count, the pages OCR was applied to and the credits charged.
Upload Examples
import fs from 'node:fs';
import Incapon from '@incapon/node';
const incapon = new Incapon(process.env.INCAPON_API_KEY);
const doc = await incapon.pdf.documents.create({
file: fs.createReadStream('./contract-scanned.pdf'),
ocrLanguages: ['tur', 'eng'],
metadata: { customer_id: 'C-1042' },
});
console.log(doc.id, doc.status); // doc_4b7e... processingimport os
import incapon
client = incapon.Client(api_key=os.environ["INCAPON_API_KEY"])
with open("contract-scanned.pdf", "rb") as f:
doc = client.pdf.documents.create(
file=f,
ocr_languages=["tur", "eng"],
metadata={"customer_id": "C-1042"},
)
print(doc.id, doc.status)curl -X POST https://api.incapon.com/v2.4/pdf/documents \
-H "Authorization: Bearer $INCAPON_API_KEY" \
-F file=@contract-scanned.pdf \
-F ocr_languages=tur,eng \
-F 'metadata={"customer_id": "C-1042"}'Limits
| Parameter | Value | Note |
|---|---|---|
| max_file_size | 200 MB | Larger files return 422 |
| max_pages | 2,000 pages | Per document |
| mime_types | application/pdf, image/tiff, image/png, image/jpeg | Multi-page TIFF is supported |
| encrypted | Not supported | Password-protected PDFs return 422 document_encrypted |
the upload is rejected with 402 and no document is created. Before long batch uploads, check your balance with GET /credits/balance or turn on auto top-up.