API Reference

Documentation

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

Basehttps://rosettafolio.com

pdf to markdown 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");

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	1 credit / page
Parse — cached (same docId)	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. Browser preview: pdf to markdown.

Parameters

Parameter	Type	Required	Description
docId	string	One of*	Existing document ID you own (re-parse is free)
url	string	One of*	Public https URL to a PDF (max 20 MB)
file	file	One of*	PDF file (multipart, max 4.5 MB)

* Exactly one of docId, url, or file is required. Max 100 pages. Digital text-layer PDFs only.

Credits per page

Condition	Credits
New parse	1 credit / page
Cached parse (same docId)	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"

response.json

{
  "success": true,
  "markdown": "## Page 1\n\nDocument text...",
  "contents": [
    { "content": "Document text...", "pageNumber": 1, "type": "text" }
  ],
  "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
  },
  "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, pdf_credit_usage, pdf_delete. Local npx also accepts a file path. 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 — remote /api/mcp or local npx -y rosetta-mcp (0.2.2) with ROSETTA_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 ~4.5 MB per document on current hosting (Vercel serverless request body limit). URL fetches allow up to 20 MB. Max 100 pages per document.

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

View pricing →