API Reference

Documentation

REST API for digital PDF text extraction. No OCR — embedded text layer only.

Basehttps://rosettafolio.com

llms.txt llms-full openapi mcp playground

Endpoints

POST/api/v2/parse

Parse

PDF → markdown + JSON

POST/api/v2/extract

Extract

Schema extraction

POST/api/v2/split

Split

Section detection

POST/api/v2/ask

Ask

Multi-doc Q&A

Quick start

Get an API key — 200 free credits/mo.
Make your first parse request:

const formData = new FormData();
formData.append("url", "https://example.com/document.pdf");
formData.append("quality", "standard");
formData.append("lang_list", JSON.stringify(["en"]));
formData.append("llm", "false");

const res = await fetch("https://rosettafolio.com/api/v2/parse", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
  body: formData,
});

const data = await res.json();

response.json

{
  "success": true,
  "markdown": "## Page 1\n\nDocument text...",
  "contents": [
    { "content": "Document text...", "pageNumber": 1, "type": "text" }
  ],
  "pageCount": 12,
  "docId": "doc_abc123"
}

Use docId with extract, split, or ask.

Authentication

Pass your API key in the X-API-Key header on every request.

auth.sh

curl https://rosettafolio.com/api/v2/credit-usage \
  -H "X-API-Key: YOUR_API_KEY"

Credits

Condition	Credits
Parse — standard quality	1 credit / page
Parse — advanced quality	2 credits / page
Parse — cached (same params)	0 credits
Extract — ≤5 schema fields	2 credits / page
Extract — >5 schema fields	4 credits / page
Split	2 credits / page
Ask	3 credits / page (total across docs)
Credit usage / Delete	Free

POST/api/v2/parse

Convert a digital PDF to markdown and structured JSON. Provide one of docId, url, or file.

Parameters

Parameter	Type	Required	Description
docId	string	One of*	Existing document ID to re-parse
url	string	One of*	Public URL to a PDF file
file	file	One of*	PDF file (multipart upload)
quality	string	No	standard (default) or advanced
lang_list	JSON string	No	Language codes, e.g. ["en"]. Default: ["en"]
llm	string	No	"true" to enable LLM post-processing. Default: false

* Exactly one of docId, url, or file is required.

Credits per page

Condition	Credits
quality = standard	1 credit / page
quality = advanced	2 credits / page
Cached parse (identical params)	0 credits

request.sh

curl -X POST https://rosettafolio.com/api/v2/parse \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "url=https://example.com/document.pdf" \
  -F "quality=standard" \
  -F 'lang_list=["en"]' \
  -F "llm=false"

response.json

{
  "success": true,
  "markdown": "## Page 1\n\nDocument text...",
  "contents": [
    { "content": "Document text...", "pageNumber": 1, "type": "text" }
  ],
  "images": [],
  "pageCount": 12,
  "docId": "doc_abc123"
}

POST/api/v2/extract

Extract structured fields from a parsed document using a JSON schema.

Parameters

Parameter	Type	Required	Description
docId	string	One of*	Previously parsed document ID
url	string	One of*	URL to PDF (auto-parsed first)
file	file	One of*	PDF file (auto-parsed first)
schema	JSON string	Yes	JSON Schema defining fields to extract
system_prompt	string	No	Custom system prompt for extraction

Credits per page

Condition	Credits
≤5 schema fields	2 credits / page
>5 schema fields	4 credits / page

request.sh

curl -X POST https://rosettafolio.com/api/v2/extract \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "docId=doc_abc123" \
  -F 'schema={"type":"object","properties":{"invoice_number":{"type":"string"},"total":{"type":"number"}}}'

response.json

{
  "success": true,
  "result": {
    "invoice_number": "INV-2024-001",
    "total": 1250.00
  },
  "citations": [],
  "docId": "doc_abc123"
}

POST/api/v2/split

Detect and split a document into named sections. Returns page ranges per section.

Parameters (JSON body)

Parameter	Type	Required	Description
docId	string	Yes	Previously parsed document ID
split_description	array	Yes	Array of { name, description } objects defining sections

Credits

Condition	Credits
All pages	2 credits / page

request.sh

curl -X POST https://rosettafolio.com/api/v2/split \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "docId": "doc_abc123",
    "split_description": [
      { "name": "Introduction", "description": "Opening overview" },
      { "name": "Terms", "description": "Legal terms and conditions" }
    ]
  }'

response.json

{
  "success": true,
  "splits": [
    { "name": "Introduction", "pages": [1, 2], "confidence": 0.92 },
    { "name": "Terms", "pages": [3, 4, 5, 6, 7, 8], "confidence": 0.88 }
  ]
}

POST/api/v2/ask

Ask a natural-language question across one or more parsed documents.

Parameters (JSON body)

Parameter	Type	Required	Description
prompt	string	Yes	Question to ask across documents
docIds	string[]	Yes	Array of previously parsed document IDs

Credits

Condition	Credits
Total pages across all docs	3 credits / page

request.sh

curl -X POST https://rosettafolio.com/api/v2/ask \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What are the key terms in this contract?",
    "docIds": ["doc_abc123"]
  }'

response.json

{
  "success": true,
  "answer": "The key terms include a 12-month term with automatic renewal..."
}

Utility endpoints

GET/api/v2/credit-usage

Check credit usage and plan for the current billing period.

request.sh

curl https://rosettafolio.com/api/v2/credit-usage \
  -H "X-API-Key: YOUR_API_KEY"

response.json

{
  "creditsUsed": 47,
  "creditsLimit": 200,
  "plan": "free",
  "recentUsage": [
    { "operation": "parse", "credits": 12, "doc_id": "doc_abc123", "created_at": "2026-08-11T12:00:00Z" }
  ]
}

POST/api/v2/delete

Delete a document and its stored content.

Parameter	Type	Required	Description
docId	string	Yes	Document ID to delete

request.sh

curl -X POST https://rosettafolio.com/api/v2/delete \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"docId": "doc_abc123"}'

response.json

{ "success": true }

MCP server

pdf_parse, pdf_extract, pdf_split, pdf_ask as MCP tools. Install guide →

For AI agents

If you are an AI assistant (ChatGPT, Claude, Gemini, Cursor agent, etc.) helping a developer integrate Rosetta, start here:

Read /llms.txt for a concise product summary, endpoints, pricing, and MCP setup.
Read /llms-full.txt for full parameter tables and Python examples.
Open /openapi.json for machine-readable API paths.
Typical flow: POST /api/v2/parse → get docId → call extract, split, or ask.
MCP install: /mcp — npx -y docchat-mcp with DOCCHAT_API_KEY.
Digital PDFs with embedded text only — do not promise OCR for scanned documents.

Limitations

Digital PDFs only. Parse uses text-layer extraction (unpdf). Scanned images and image-only PDFs without embedded text are not supported.
No OCR or VLM. We do not perform optical character recognition or visual layout analysis.
Tables. Returned as plain text, not structured cells. Use extract with a JSON schema for field-level structure.
File size. Maximum upload size is 50 MB per document.

200 free credits/month. Paid plans from $49/mo.

View pricing →