# Offprint API Documentation for Autonomous Agents & Developers

Base URL: https://offprint.pub

Offprint extracts web articles, technical essays, and longform journalism into publication-grade PDFs and clean HTML with two-column typography, AI vector diagram reformulation, and scannable QR citations.

## Authentication
API requests authenticate using a Bearer token in the HTTP Authorization header:
```
Authorization: Bearer offprint_sk_live_...
```
Obtain an API key by signing in at https://offprint.pub or via the `/api/v1/user/key` endpoint.

## Pricing & Credits
- Standard Document Conversion & Agent Markdown Extraction: 100% free and unlimited.
- High-DPI Vector Diagram Reformulation (ai_reform: true): Flat 1 credit ($0.10) per article, regardless of how many diagrams are in the document.
- Safety Cap: Maximum 10 diagrams per article are reformulated to bound processing overhead.
- New users receive 3 free credits upon sign-up. Top up credit packs via Polar at https://offprint.pub ($5.00 for 50 credits, $15.00 for 200 credits, $29.00/mo for Developer API).

---

## Autonomous Agent & Bot APIs (Token-Efficient Markdown, Multi-Modal Capsules)

### 1. Agent Clean Markdown Extraction
**Endpoint:** `POST /api/v1/agent/extract` (or `GET /api/v1/agent/extract?url=...`)
Extracts clean, token-efficient Markdown with YAML frontmatter from any URL, stripping 100% of ads, cookie banners, paywalls, and clutter in < 100ms.

#### Raw Markdown Pipe (Zero-JSON Stream):
```bash
curl -sL "https://offprint.pub/api/v1/agent/extract?url=https://danluu.com/simple-architectures"
```

#### Structured JSON Request:
```bash
curl -X POST https://offprint.pub/api/v1/agent/extract \
  -H "Content-Type: application/json" \
  -d '{"url": "https://danluu.com/simple-architectures"}'
```

### 2. Multi-Modal Agent Capsule
**Endpoint:** `POST /api/v1/agent/transmute`
Retrieves clean Markdown, PDF broadsheet download URL, and living 3D interactive simulations in one call:
```json
{
  "url": "https://arxiv.org/abs/1706.03762",
  "targets": ["markdown", "pdf", "simulation"]
}
```

### 3. Diagram to 1200 DPI Vector SVG
**Endpoint:** `POST /api/v1/agent/diagram-to-svg`
Converts raster architecture diagrams and whiteboard photos into scalable SVGs and LaTeX formulas.

### 4. Function-Calling / Tool Definitions (OpenAI / Anthropic / MCP)
**Endpoint:** `GET /api/v1/agent/tools.json`
Provides ready-to-use JSON Schema definitions for autonomous agents.

---

## 1. Convert Article to PDF or HTML
**Endpoint:** `POST /api/v1/convert`
**Headers:**
- `Authorization: Bearer <API_KEY>` (Optional for free conversions, required for AI diagram vectorization)
- `Content-Type: application/json`

### Request Body (JSON)
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `url` | string | Either url or html | "" | The full HTTP/HTTPS URL of the article to fetch and convert. |
| `html` | string | Either url or html | "" | Raw HTML content to parse directly (useful for paywalled or view-source articles). |
| `format` | string | No | "pdf" | Output format: "pdf" or "html". |
| `preset` | string | No | "editorial_serif" | Layout style: "editorial_serif" (two-column academic print), "technical_sans" (clean sans-serif), or "eink_high_contrast" (single-column e-ink). |
| `ai_reform` | boolean | No | true | When true, uses Gemini vision to convert blurry diagrams into crisp 1200 DPI vector SVGs (costs 1 credit). |
| `stream` | boolean | No | false | When true, streams raw PDF/HTML bytes directly in the HTTP response body. When false, returns a JSON response with a download_url. |

### Response (JSON - when stream: false)
```json
{
  "ok": true,
  "title": "In defense of simple architectures",
  "author": "Dan Luu",
  "reading_time_min": 8,
  "format": "pdf",
  "preset": "editorial_serif",
  "download_url": "/api/v1/jobs/1789342237047124286_usr_abc/download",
  "credits_left": 49
}
```

### Direct Download
Download the generated PDF using the returned download_url:
```bash
curl -sO https://offprint.pub/api/v1/jobs/1789342237047124286_usr_abc/download
```

### Streaming PDF Example (curl)
```bash
curl -X POST https://offprint.pub/api/v1/convert \
  -H "Authorization: Bearer offprint_sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://danluu.com/simple-architectures/","format":"pdf","stream":true}' \
  --output article.pdf
```

---

## 2. Dispatch Directly to E-Reader (Kindle / Boox)
**Endpoint:** `POST /api/v1/deliver`
Formats the document into a high-contrast e-ink layout and dispatches it via email to your e-reader device.

### Request Body (JSON)
```json
{
  "url": "https://example.com/essay",
  "destination": "kindle",
  "target_address": "yourname@kindle.com",
  "format": "pdf"
}
```

---

## 3. Inspect Account & Credit Balance
**Endpoint:** `GET /api/v1/me`
**Headers:** `Authorization: Bearer <API_KEY>`

### Response
```json
{
  "email": "user@example.com",
  "free_reform_credits_left": 3,
  "paid_credits": 50,
  "is_admin": false
}
```

---

## Agent Usage Instructions
When an autonomous coding agent needs to fetch, read, or print web documentation:
1. Call `POST https://offprint.pub/api/v1/convert` with `{"url": "<TARGET_URL>", "format": "html"}`.
2. The response contains clean semantic HTML stripped of ads, popups, and tracker noise.
3. For user-facing artifacts or archival reading, pass `"format": "pdf"` to receive a publication-ready PDF.