API Documentation

Parse academic PDFs into structured data and generate shareable links programmatically.

Authentication

All API requests require an API key. Create one in Settings → API Keys. Include it as a Bearer token:

Authorization: Bearer dp_live_your_key_here

Base URL

https://www.deconstructedpapers.com

Endpoints

POST/api/papers/auto-parse— Parse a PDF, return structured data

Fetches a PDF from a URL, parses it into structured sections using an LLM, saves it to your library, and returns the parsed data. Costs 1 credit per fresh parse (cached results are free).

Request

curl -X POST https://www.deconstructedpapers.com/api/papers/auto-parse \
  -H "Authorization: Bearer dp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://arxiv.org/abs/1706.03762"}'

Request body

Field	Type	Required	Description
`url`	string	Yes	URL to the PDF. ArXiv `/abs/` URLs auto-convert to PDF.
`model`	string	No	LLM model ID. Default: `anthropic/claude-haiku-4.5`

Response (200)

{
  "title": "Attention Is All You Need",
  "authors": ["Ashish Vaswani", "Noam Shazeer", "..."],
  "paper": {
    "title": "Attention Is All You Need",
    "authors": ["..."],
    "abstract": "...",
    "sections": [
      {
        "id": "section-0",
        "heading": "Abstract",
        "type": "text",
        "content": [{ "type": "text", "value": "..." }],
        "pageNumbers": [1]
      }
    ]
  },
  "cached": false
}

POST/api/papers/auto-share— Parse a PDF, return a shareable link

Same as auto-parse, but also creates a shareable link. Returns a short code and URL.

Request

curl -X POST https://www.deconstructedpapers.com/api/papers/auto-share \
  -H "Authorization: Bearer dp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://arxiv.org/abs/1706.03762"}'

Response (200)

{
  "shortCode": "aBcDeFgH",
  "url": "/s/aBcDeFgH",
  "title": "Attention Is All You Need",
  "authors": ["Ashish Vaswani", "Noam Shazeer", "..."],
  "cached": false
}

Full share URL: https://www.deconstructedpapers.com/s/{shortCode}

API Key Management

GET/api/keys— List active keys

curl https://www.deconstructedpapers.com/api/keys \
  -H "Authorization: Bearer dp_live_your_key_here"

POST/api/keys— Create a new key

curl -X POST https://www.deconstructedpapers.com/api/keys \
  -H "Authorization: Bearer dp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-bot"}'

The response includes a key field with the full plaintext key — save it immediately, it cannot be retrieved again. Max 5 active keys.

DELETE/api/keys— Revoke a key

curl -X DELETE https://www.deconstructedpapers.com/api/keys \
  -H "Authorization: Bearer dp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"keyId": "uuid-of-key-to-revoke"}'

Credits & Caching

Each fresh parse costs 1 credit.
Cached results (same URL, already in your library) are free.
If parsing fails after credit deduction, the credit is automatically refunded.
Purchase credits at /pricing.

Models

Model ID	Description
`anthropic/claude-haiku-4.5`	Default. Fast, cost-effective.
`anthropic/claude-sonnet-4.6`	Higher quality parsing.
`google/gemini-2.5-pro`	Google Gemini 2.5 Pro.
`google/gemini-2.5-flash`	Google Gemini 2.5 Flash.

Rate Limits

Tier	Parse Limit
Free	10 per day
Pro (purchased credits)	20 per hour

Error Responses

Status	Meaning
`400`	Invalid request — missing URL, invalid JSON, non-PDF content
`401`	Authentication failed — missing or invalid API key
`402`	No credits remaining
`403`	Publisher blocks automated PDF downloads
`413`	PDF too large for selected model
`429`	Rate limited — check Retry-After header
`502`	PDF fetch or LLM parsing failed

Python CLI

A ready-to-use CLI script is available on GitHub at nighthawk6389/deconstructed-papers-skill.

curl -O https://raw.githubusercontent.com/nighthawk6389/deconstructed-papers-skill/main/auto-share.py
pip install requests
export DP_API_KEY="dp_live_..."

# Parse a paper
python auto-share.py parse https://arxiv.org/abs/1706.03762
python auto-share.py parse --json URL        # raw JSON output
python auto-share.py parse --model anthropic/claude-sonnet-4.6 URL

# Parse and create a shared link
python auto-share.py share https://arxiv.org/abs/1706.03762
python auto-share.py share URL1 URL2 URL3

# Manage API keys
python auto-share.py keys list
python auto-share.py keys create --name my-bot
python auto-share.py keys revoke KEY_ID

Python Example

import requests

API_KEY = "dp_live_your_key_here"
BASE = "https://www.deconstructedpapers.com"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# Parse a paper
resp = requests.post(f"{BASE}/api/papers/auto-parse",
    headers=HEADERS,
    json={"url": "https://arxiv.org/abs/1706.03762"})
data = resp.json()
print(f"Title: {data['title']}")
print(f"Sections: {len(data['paper']['sections'])}")

# Parse and share
resp = requests.post(f"{BASE}/api/papers/auto-share",
    headers=HEADERS,
    json={"url": "https://arxiv.org/abs/1706.03762"})
data = resp.json()
print(f"Share link: {BASE}{data['url']}")

For AI Agents

Machine-readable API reference available at /llms.txt.