# Deconstructed Papers API

> Deconstructed Papers is a tool that uses LLMs to parse academic PDFs into structured sections and provides AI explanations, math analysis, and artifact generation.

## Documentation

Human-readable docs: https://www.deconstructedpapers.com/docs

## Base URL

Production: https://www.deconstructedpapers.com

## Authentication

All API endpoints require an API key as a Bearer token.

Create keys in the web app at Settings → API Keys, or programmatically via the /api/keys endpoint.

```
Authorization: Bearer dp_live_your_key_here
```

### Managing API Keys

All key management endpoints accept Bearer token auth.

```
GET /api/keys
Headers:
  Authorization: Bearer dp_live_...
Response: { "keys": [{ "id": "uuid", "name": "my-bot", "keyPrefix": "dp_live_abc12345...", "lastUsedAt": "...", "createdAt": "..." }] }
```

```
POST /api/keys
Headers:
  Authorization: Bearer dp_live_...
  Content-Type: application/json
Body: { "name": "my-bot" }
Response: { "key": "dp_live_...", "id": "uuid", "name": "my-bot", "keyPrefix": "dp_live_abc12345...", "createdAt": "..." }
```

The `key` field is the full API key, shown exactly once. Store it securely — it cannot be retrieved again.

```
DELETE /api/keys
Headers:
  Authorization: Bearer dp_live_...
  Content-Type: application/json
Body: { "keyId": "uuid" }
Response: { "success": true }
```

### Limits

- Maximum 5 active API keys per user

## Auto-Parse Endpoint

Parse a PDF from a URL and get the structured paper data. Does not create a share link.

```
POST /api/papers/auto-parse
Headers:
  Content-Type: application/json
  Authorization: Bearer dp_live_...
Body:
  {
    "url": "https://arxiv.org/abs/2301.12345",
    "model": "anthropic/claude-haiku-4.5"  // optional
  }
```

### Response (success)

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

The `paper` field contains the full structured paper with sections, content blocks, and math expressions.

## Auto-Share Endpoint

Parse a PDF from a URL and get a shareable link in one step.

```
POST /api/papers/auto-share
Headers:
  Content-Type: application/json
  Authorization: Bearer dp_live_...
Body:
  {
    "url": "https://arxiv.org/abs/2301.12345",
    "model": "anthropic/claude-haiku-4.5"  // optional
  }
```

### Response (success)

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

The full shareable URL is `https://www.deconstructedpapers.com/s/{shortCode}`.

## Shared Behavior (both endpoints)

### Caching

If the same URL has been parsed before by the same user, the endpoint returns the cached result with `"cached": true` and does not deduct a credit.

### Credits

- A fresh parse (cache miss) costs 1 credit
- A cache hit costs 0 credits
- If parsing fails for any reason, the credit is automatically refunded
- If you have no credits, the endpoint returns HTTP 402

### Available Models

| Model ID | Name |
|----------|------|
| `anthropic/claude-haiku-4.5` | Claude Haiku 4.5 (default) |
| `anthropic/claude-sonnet-4.6` | Claude Sonnet 4.6 |
| `google/gemini-2.5-pro` | Gemini 2.5 Pro |
| `google/gemini-2.5-flash` | Gemini 2.5 Flash |

### Error Responses

| Status | Meaning |
|--------|---------|
| 400 | Invalid request (bad URL, HTML instead of PDF, invalid magic bytes) |
| 401 | Missing or invalid authentication |
| 402 | No credits remaining |
| 403 | Publisher blocks automated PDF downloads |
| 413 | PDF too large for selected model |
| 429 | Rate limit exceeded (check `Retry-After` header) |
| 502 | PDF fetch or LLM parsing failed |
| 500 | Internal server error |

### Rate Limits

Both endpoints share rate limits with the parse-paper endpoint:

| Tier | Limit |
|------|-------|
| Free | 10 per day |
| Pro | 20 per hour |

### URL Handling

- arXiv URLs are automatically normalized (e.g., `/abs/` → `/pdf/`, routed through `export.arxiv.org`)
- Any valid HTTPS PDF URL is accepted
- Private/internal IP addresses and non-HTTP(S) protocols are blocked

## Shared Paper Viewing

Shared papers are publicly viewable at `/s/{shortCode}` — no authentication required.

## Popular Papers Page (`/papers`)

A curated, public list of already-parsed papers is available at `/papers` — no authentication required. It's driven by a single static JSON file committed to the repo and is intended to be updated by an external process (not via the API).

### File location

```
content/popular-papers.json
```

The file is loaded at render time by `lib/curated/popular-papers.ts` and validated with Zod. If the JSON is malformed the page render will throw.

### Schema

```json
{
  "papers": [
    {
      "slug": "attention-is-all-you-need",
      "title": "Attention Is All You Need",
      "description": "The foundational Transformer paper...",
      "authors": "Vaswani et al.",
      "year": 2017,
      "tags": ["Deep Learning", "NLP"],
      "arxivUrl": "https://arxiv.org/abs/1706.03762",
      "shareCode": "abc12xyz"
    }
  ]
}
```

### Field reference

| Field | Required | Type | Notes |
|-------|----------|------|-------|
| `slug` | yes | string | Stable, URL-safe identifier. Must be unique within the file. |
| `title` | yes | string | Display title. |
| `description` | yes | string | Plain-text card body. 1-3 sentences. |
| `authors` | yes | string | Free-form display string (e.g. `"Vaswani et al."`). |
| `year` | yes | integer | Publication year. |
| `tags` | yes | string[] | 2-4 short tags. May be empty. |
| `arxivUrl` | yes | string | Absolute http(s) URL to the arxiv abstract page (`.../abs/...`). |
| `shareCode` | no | string | The 8-char `nanoid` share code for the paper. Entries without a non-empty `shareCode` are silently filtered out of the rendered list. The public share view lives at `/s/{shareCode}`. |

### Updating the file

The app does not write to this file — updates are made externally by rewriting `content/popular-papers.json` and opening a PR. Merge + deploy publishes new entries. The page is statically prerendered; there is no runtime revalidation.

## Python CLI

A Python CLI tool is available at: https://github.com/nighthawk6389/deconstructed-papers-skill

Download: https://raw.githubusercontent.com/nighthawk6389/deconstructed-papers-skill/main/auto-share.py

```bash
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

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

# 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
```