PapyDocs for developers

The Papy API brings PapyDocs document processing into your applications, websites and software through a simple, versioned REST interface.

Every documented endpoint runs the same engines as the PapyDocs tools.
Keys are stored as hashes, shown once, and can be rotated or revoked.
Files are processed in memory and never stored; only usage counters are kept.

Checking availability…

Quick start

Ask the administrator of this PapyDocs deployment for an API key (created in “Keys and usage” below).
Send a multipart/form-data POST request to /api/v1/OPERATION with your PDF files and parameters.
Add the header Authorization: Bearer YOUR_KEY to every request.
Read the JSON result, or save the PDF or ZIP returned. Errors always come back as JSON with a stable code.

List the operations available on this deployment

curl https://papydocs.com/api/v1

Authentication

Every request is authenticated with an API key sent in the Authorization header.

HTTP

Authorization: Bearer papy_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

PapyDocs stores only a SHA-256 hash of each key, never the key itself.
A new key is displayed once, when it is created. Store it in your secrets manager: it cannot be shown again.
Rotation issues a new key and revokes the old one immediately; revocation takes effect on the next request.
Call the API from your server. Never put a key in a web page or a mobile app bundle.

Endpoint reference

All operations are POST requests to /api/v1/OPERATION with a multipart/form-data body. JSON operations return application/json; file operations return the PDF or ZIP directly.

Document operations

POST`/api/v1/info`— Document information

Returns the page count, size and metadata of a PDF.

Field	Type	Required
file	PDF file	Yes

Response: JSON

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/info" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "file=@document.pdf"

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("file", await openAsBlob("document.pdf"), "document.pdf");

const response = await fetch("https://papydocs.com/api/v1/info", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
const data = await response.json();
console.log(data);

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/info",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("file", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ],
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
print(response.json())

Example response (abridged)

{
  "pages": 2,
  "bytes": 48213,
  "metadata": {
    "title": "Contract",
    "author": "",
    "subject": "",
    "keywords": "",
    "creator": "",
    "producer": "pdf-lib",
    "creationDate": "2026-10-14T09:00:00.000Z",
    "modificationDate": null,
    "customKeys": [],
    "hasXmp": false,
    "hasJavaScript": false,
    "hasEmbeddedFiles": false,
    "pageCount": 2
  }
}

POST`/api/v1/merge`— Merge

Merges several PDFs in the order they are sent.

Field	Type	Required
files	Several PDF files	Yes

Response: PDF file

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/merge" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "files=@document.pdf" \
  -F "files=@other.pdf" \
  -o result.pdf

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";
import { writeFile } from "node:fs/promises";

const form = new FormData();
form.append("files", await openAsBlob("document.pdf"), "document.pdf");
form.append("files", await openAsBlob("other.pdf"), "other.pdf");

const response = await fetch("https://papydocs.com/api/v1/merge", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
await writeFile("result.pdf", Buffer.from(await response.arrayBuffer()));

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/merge",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("files", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ("files", ("other.pdf", open("other.pdf", "rb"), "application/pdf")),
    ],
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
with open("result.pdf", "wb") as out:
    out.write(response.content)

POST`/api/v1/split`— Split

Splits a PDF by page ranges (e.g. 1-2,5) or into one file per page; returns a ZIP.

Field	Type	Required
file	PDF file	Yes
mode	One of (ranges \| every-page)	No
ranges	Text	No

Response: ZIP archive of PDF files

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/split" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "file=@document.pdf" \
  -F 'mode=ranges' \
  -F 'ranges=1-2,5' \
  -o result.zip

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";
import { writeFile } from "node:fs/promises";

const form = new FormData();
form.append("file", await openAsBlob("document.pdf"), "document.pdf");
form.append("mode", "ranges");
form.append("ranges", "1-2,5");

const response = await fetch("https://papydocs.com/api/v1/split", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
await writeFile("result.zip", Buffer.from(await response.arrayBuffer()));

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/split",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("file", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ],
    data={"mode": "ranges", "ranges": "1-2,5"},
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
with open("result.zip", "wb") as out:
    out.write(response.content)

POST`/api/v1/compress`— Compress

Lossless structural optimisation of a PDF (images are not re-encoded).

Field	Type	Required
file	PDF file	Yes

Response: PDF file

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/compress" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "file=@document.pdf" \
  -o result.pdf

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";
import { writeFile } from "node:fs/promises";

const form = new FormData();
form.append("file", await openAsBlob("document.pdf"), "document.pdf");

const response = await fetch("https://papydocs.com/api/v1/compress", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
await writeFile("result.pdf", Buffer.from(await response.arrayBuffer()));

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/compress",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("file", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ],
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
with open("result.pdf", "wb") as out:
    out.write(response.content)

POST`/api/v1/rotate`— Rotate

Rotates every page by 90, 180 or 270 degrees.

Field	Type	Required
file	PDF file	Yes
angle	One of (90 \| 180 \| 270)	No

Response: PDF file

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/rotate" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "file=@document.pdf" \
  -F 'angle=90' \
  -o result.pdf

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";
import { writeFile } from "node:fs/promises";

const form = new FormData();
form.append("file", await openAsBlob("document.pdf"), "document.pdf");
form.append("angle", "90");

const response = await fetch("https://papydocs.com/api/v1/rotate", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
await writeFile("result.pdf", Buffer.from(await response.arrayBuffer()));

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/rotate",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("file", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ],
    data={"angle": "90"},
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
with open("result.pdf", "wb") as out:
    out.write(response.content)

POST`/api/v1/page-numbers`— Page numbers

Adds page numbers from a template using the {page} and {total} placeholders (Latin characters).

Field	Type	Required
file	PDF file	Yes
format	Text	No
start	Number	No

Response: PDF file

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/page-numbers" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "file=@document.pdf" \
  -F 'format={page} / {total}' \
  -F 'start=1' \
  -o result.pdf

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";
import { writeFile } from "node:fs/promises";

const form = new FormData();
form.append("file", await openAsBlob("document.pdf"), "document.pdf");
form.append("format", "{page} / {total}");
form.append("start", "1");

const response = await fetch("https://papydocs.com/api/v1/page-numbers", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
await writeFile("result.pdf", Buffer.from(await response.arrayBuffer()));

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/page-numbers",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("file", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ],
    data={"format": "{page} / {total}", "start": "1"},
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
with open("result.pdf", "wb") as out:
    out.write(response.content)

POST`/api/v1/watermark`— Watermark

Adds a diagonal text watermark on every page (Latin characters).

Field	Type	Required
file	PDF file	Yes
text	Text	Yes
opacity	Number	No

Response: PDF file

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/watermark" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "file=@document.pdf" \
  -F 'text=CONFIDENTIAL' \
  -F 'opacity=0.2' \
  -o result.pdf

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";
import { writeFile } from "node:fs/promises";

const form = new FormData();
form.append("file", await openAsBlob("document.pdf"), "document.pdf");
form.append("text", "CONFIDENTIAL");
form.append("opacity", "0.2");

const response = await fetch("https://papydocs.com/api/v1/watermark", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
await writeFile("result.pdf", Buffer.from(await response.arrayBuffer()));

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/watermark",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("file", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ],
    data={"text": "CONFIDENTIAL", "opacity": "0.2"},
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
with open("result.pdf", "wb") as out:
    out.write(response.content)

Document intelligence

POST`/api/v1/text`— Extract text

Returns the text of each page and whether the document looks scanned (needsOcr). No OCR is performed on the server.

Field	Type	Required
file	PDF file	Yes

Response: JSON

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/text" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "file=@document.pdf"

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("file", await openAsBlob("document.pdf"), "document.pdf");

const response = await fetch("https://papydocs.com/api/v1/text", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
const data = await response.json();
console.log(data);

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/text",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("file", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ],
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
print(response.json())

Example response (abridged)

{
  "pages": [
    {
      "page": 1,
      "text": "Facture N° FAC-2026-0042\nTotal TTC 144,00 €"
    }
  ],
  "characters": 41,
  "needsOcr": false
}

POST`/api/v1/search`— Search several PDFs

Full-text search across the PDFs sent: results with document, page, occurrences and an excerpt copied from the page. Use quotes for an exact phrase.

Field	Type	Required
files	Several PDF files	Yes
query	Text	Yes

Response: JSON

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/search" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "files=@document.pdf" \
  -F "files=@other.pdf" \
  -F 'query="notice period"'

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("files", await openAsBlob("document.pdf"), "document.pdf");
form.append("files", await openAsBlob("other.pdf"), "other.pdf");
form.append("query", "\"notice period\"");

const response = await fetch("https://papydocs.com/api/v1/search", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
const data = await response.json();
console.log(data);

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/search",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("files", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ("files", ("other.pdf", open("other.pdf", "rb"), "application/pdf")),
    ],
    data={"query": "\"notice period\""},
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
print(response.json())

Example response (abridged)

{
  "query": "\"notice period\"",
  "results": [
    {
      "document": "contract.pdf",
      "documentIndex": 0,
      "page": 2,
      "score": 6,
      "occurrences": 1,
      "snippet": {
        "before": "…may terminate with a ",
        "match": "notice period",
        "after": " of three months…"
      }
    }
  ]
}

POST`/api/v1/invoice`— Extract invoice data

Extracts supplier, customer, number, dates, currency, amounts, line items, payment terms and order reference, each with its source page and line, plus consistency checks. Missing values are returned as null, never estimated.

Field	Type	Required
file	PDF file	Yes

Response: JSON

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/invoice" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "file=@document.pdf"

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("file", await openAsBlob("document.pdf"), "document.pdf");

const response = await fetch("https://papydocs.com/api/v1/invoice", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
const data = await response.json();
console.log(data);

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/invoice",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("file", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ],
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
print(response.json())

Example response (abridged)

{
  "fields": {
    "invoiceNumber": {
      "value": "FAC-2026-0042",
      "status": "found",
      "source": {
        "pageNumber": 1,
        "excerpt": "Facture N° FAC-2026-0042"
      }
    },
    "total": {
      "value": "144",
      "status": "found",
      "source": {
        "pageNumber": 1,
        "excerpt": "Total TTC 144,00 €"
      }
    },
    "dueDate": {
      "value": null,
      "status": "missing",
      "source": null
    }
  },
  "lineItems": [
    {
      "description": "Ramette papier A4",
      "quantity": 10,
      "unitPrice": 5,
      "amount": 50,
      "source": {
        "pageNumber": 1,
        "excerpt": "Ramette papier A4 10 5,00 € 50,00 €"
      }
    }
  ],
  "checks": [
    {
      "code": "missing",
      "field": "dueDate"
    }
  ]
}

POST`/api/v1/contract`— Analyse a contract

Returns clause headings, passages by topic (parties, payment, duration, termination…), dates, amounts, notice periods and passages to check, all copied from the document with their page. Keyword-based pointers, not legal advice.

Field	Type	Required
file	PDF file	Yes

Response: JSON

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/contract" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "file=@document.pdf"

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("file", await openAsBlob("document.pdf"), "document.pdf");

const response = await fetch("https://papydocs.com/api/v1/contract", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
const data = await response.json();
console.log(data);

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/contract",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("file", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ],
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
print(response.json())

Example response (abridged)

{
  "notice": "Passages are copied from the document; categories and flags are keyword-based pointers to verify, not legal advice.",
  "pageCount": 2,
  "clauses": [
    {
      "heading": "Article 7 - Résiliation",
      "pageNumber": 2
    }
  ],
  "findings": [
    {
      "category": "termination",
      "pageNumber": 2,
      "clause": "Article 7 - Résiliation",
      "excerpt": "Chaque partie peut résilier le contrat moyennant un préavis de 3 mois."
    }
  ],
  "flags": [
    {
      "reason": "auto-renewal",
      "pageNumber": 1,
      "clause": "Article 2 - Durée",
      "excerpt": "Il est renouvelé par tacite reconduction…",
      "match": "tacite reconduction"
    }
  ],
  "facts": [
    {
      "type": "notice",
      "value": "préavis de 3 mois",
      "pageNumber": 2,
      "clause": "Article 7 - Résiliation",
      "excerpt": "…"
    }
  ],
  "sentenceCount": 14
}

POST`/api/v1/compare`— Compare two versions

Compares the text of two PDFs page by page and returns the added, deleted and modified passages with their context.

Field	Type	Required
original	PDF file	Yes
revised	PDF file	Yes

Response: JSON

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/compare" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "original=@contract-v1.pdf" \
  -F "revised=@contract-v2.pdf"

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("original", await openAsBlob("contract-v1.pdf"), "contract-v1.pdf");
form.append("revised", await openAsBlob("contract-v2.pdf"), "contract-v2.pdf");

const response = await fetch("https://papydocs.com/api/v1/compare", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
const data = await response.json();
console.log(data);

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/compare",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("original", ("contract-v1.pdf", open("contract-v1.pdf", "rb"), "application/pdf")),
    ("revised", ("contract-v2.pdf", open("contract-v2.pdf", "rb"), "application/pdf")),
    ],
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
print(response.json())

Example response (abridged)

{
  "identical": false,
  "pageCountOriginal": 2,
  "pageCountRevised": 2,
  "wordsAdded": 11,
  "wordsRemoved": 1,
  "changes": [
    {
      "type": "modified",
      "pageNumber": 1,
      "before": "12",
      "after": "24",
      "context": "Le contrat est conclu pour une durée de 24 mois."
    }
  ]
}

POST`/api/v1/proofread`— Proofread

Runs the PapyDocs local proofreading rules (spacing, punctuation, repeated words, capitals, common misspellings) and returns each issue with its correction and position.

Field	Type	Required
file	PDF file	Yes
language	One of (auto \| fr \| en \| es \| pt)	No

Response: JSON

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/proofread" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "file=@document.pdf" \
  -F 'language=auto'

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("file", await openAsBlob("document.pdf"), "document.pdf");
form.append("language", "auto");

const response = await fetch("https://papydocs.com/api/v1/proofread", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
const data = await response.json();
console.log(data);

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/proofread",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("file", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ],
    data={"language": "auto"},
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
print(response.json())

Example response (abridged)

{
  "language": "fr",
  "engine": "local-rules",
  "issues": [
    {
      "page": 1,
      "start": 11,
      "end": 15,
      "original": "recu",
      "suggestion": "reçu",
      "category": "spelling",
      "rule": "misspelling"
    }
  ]
}

Security and privacy

POST`/api/v1/remove-metadata`— Remove metadata

Removes document metadata and active content (JavaScript, embedded files).

Field	Type	Required
file	PDF file	Yes

Response: PDF file

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/remove-metadata" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "file=@document.pdf" \
  -o result.pdf

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";
import { writeFile } from "node:fs/promises";

const form = new FormData();
form.append("file", await openAsBlob("document.pdf"), "document.pdf");

const response = await fetch("https://papydocs.com/api/v1/remove-metadata", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
await writeFile("result.pdf", Buffer.from(await response.arrayBuffer()));

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/remove-metadata",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("file", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ],
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
with open("result.pdf", "wb") as out:
    out.write(response.content)

POST`/api/v1/protect`— Protect with a password

Encrypts a PDF (AES-256) with an opening password.

Field	Type	Required
file	PDF file	Yes
password	Text	Yes
owner_password	Text	No

Response: PDF file

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/protect" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "file=@document.pdf" \
  -F 'password=your-password' \
  -o result.pdf

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";
import { writeFile } from "node:fs/promises";

const form = new FormData();
form.append("file", await openAsBlob("document.pdf"), "document.pdf");
form.append("password", "your-password");

const response = await fetch("https://papydocs.com/api/v1/protect", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
await writeFile("result.pdf", Buffer.from(await response.arrayBuffer()));

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/protect",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("file", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ],
    data={"password": "your-password"},
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
with open("result.pdf", "wb") as out:
    out.write(response.content)

POST`/api/v1/unlock`— Remove a password

Decrypts a PDF when the correct password is supplied.

Field	Type	Required
file	PDF file	Yes
password	Text	Yes

Response: PDF file

Code samples and example response

cURL

curl -X POST "https://papydocs.com/api/v1/unlock" \
  -H "Authorization: Bearer $PAPY_API_KEY" \
  -F "file=@document.pdf" \
  -F 'password=your-password' \
  -o result.pdf

JavaScript / TypeScript

// Node.js 20+ (TypeScript or JavaScript). Keep the key on your server.
import { openAsBlob } from "node:fs";
import { writeFile } from "node:fs/promises";

const form = new FormData();
form.append("file", await openAsBlob("document.pdf"), "document.pdf");
form.append("password", "your-password");

const response = await fetch("https://papydocs.com/api/v1/unlock", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAPY_API_KEY}` },
  body: form,
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Papy API ${response.status}: ${error.code}`);
}
await writeFile("result.pdf", Buffer.from(await response.arrayBuffer()));

Python

import os
import requests

response = requests.post(
    "https://papydocs.com/api/v1/unlock",
    headers={"Authorization": f"Bearer {os.environ['PAPY_API_KEY']}"},
    files=[
    ("file", ("document.pdf", open("document.pdf", "rb"), "application/pdf")),
    ],
    data={"password": "your-password"},
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"Papy API {response.status_code}: {response.json()['error']['code']}")
with open("result.pdf", "wb") as out:
    out.write(response.content)

Key-management endpoints

Reserved for the deployment administrator, authenticated with the administrator token (not with an API key). They are used by the “Keys and usage” section of this page.

GET/api/v1/keys— List keys (without secrets)
POST/api/v1/keys— Create a key (JSON body with a name); the secret is returned once
DELETE/api/v1/keys/{id}— Revoke a key
POST/api/v1/keys/{id}/rotate— Rotate a key; the new secret is returned once
GET/api/v1/usage?days=30— Usage counters per day, key and operation

Errors and limits

Errors use standard HTTP status codes and a JSON body with a stable, machine-readable code. Messages are not localised: map the code in your application.

Error format

{
  "error": {
    "code": "authorization-required"
  }
}

Status	Meaning	Error codes
200	Success
400	Missing or invalid parameter	invalid-options, empty-selection
401	Missing, invalid or revoked key (or administrator token)	authorization-required
404	Unknown operation or key	invalid-options
413	Request or file too large	request-too-large, file-too-large
415	The file is not a PDF	unsupported-type
422	The PDF cannot be processed (damaged, encrypted, wrong password, no text…)	corrupt, encrypted, wrong-password, no-text, invalid-range
429	Hourly limit reached: wait for the number of seconds given in Retry-After	rate-limited
503	The API, or key management, is not enabled on this deployment	server-unavailable

Limits

Default limit: 120 requests per hour and per key (configurable by the deployment).
Each response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds).
Up to 100 MB per PDF, 200 MB per request and 60 files per request.
Text operations read up to 500 pages per document; search queries are limited to 200 characters and 100 results.
Scanned documents without a text layer are refused by the analysis operations (error no-text): run OCR first, for example with the PapyDocs OCR tool.

Test console

Send a real request to this deployment with your key. The key stays in this page’s memory, is sent only to this site and is never stored. The files you choose are sent to the API for this request only.

API key

Starts with papy_. Not saved.

Operation

file *

Keys and usage

For the administrator of this deployment. Enter the administrator token configured on the server (its hash is set in PAPY_ADMIN_TOKEN_HASH). The token stays in this page’s memory only.

Data protection

Files sent to the API are processed in memory for the duration of the request and are not stored.
PapyDocs does not write document content, file names, parameters or keys to its logs.
Usage statistics are aggregate counters kept for 90 days.
Use HTTPS only. The API runs PapyDocs’ own engines on this server; it does not send your documents to an AI provider.

PapyDocs for developers

Quick start

Authentication

Endpoint reference

Document operations

POST/api/v1/info— Document information

POST/api/v1/merge— Merge

POST/api/v1/split— Split

POST/api/v1/compress— Compress

POST/api/v1/rotate— Rotate

POST/api/v1/page-numbers— Page numbers

POST/api/v1/watermark— Watermark

Document intelligence

POST/api/v1/text— Extract text

POST/api/v1/search— Search several PDFs

POST/api/v1/invoice— Extract invoice data

POST/api/v1/contract— Analyse a contract

POST/api/v1/compare— Compare two versions

POST/api/v1/proofread— Proofread

Security and privacy

POST/api/v1/remove-metadata— Remove metadata

POST/api/v1/protect— Protect with a password

POST/api/v1/unlock— Remove a password

Key-management endpoints

Errors and limits

Limits

Test console

Keys and usage

Data protection

POST`/api/v1/info`— Document information

POST`/api/v1/merge`— Merge

POST`/api/v1/split`— Split

POST`/api/v1/compress`— Compress

POST`/api/v1/rotate`— Rotate

POST`/api/v1/page-numbers`— Page numbers

POST`/api/v1/watermark`— Watermark

POST`/api/v1/text`— Extract text

POST`/api/v1/search`— Search several PDFs

POST`/api/v1/invoice`— Extract invoice data

POST`/api/v1/contract`— Analyse a contract

POST`/api/v1/compare`— Compare two versions

POST`/api/v1/proofread`— Proofread

POST`/api/v1/remove-metadata`— Remove metadata

POST`/api/v1/protect`— Protect with a password

POST`/api/v1/unlock`— Remove a password