# deepread-api

Adopt this skill: https://proskills.md/skills/other/deepread-tech-skills-skills-api

Page: https://proskills.md/skills/other/deepread-tech-skills-skills-api
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/api/SKILL.md
size: 39938
sha: fdd0b337951ed3f9919cef7df7d9cb0f4af95da8
upstream: https://github.com/deepread-tech/skills/blob/main/skills/api/SKILL.md
truncated: true

````text
---
name: deepread-api
description: Full DeepRead API reference. All endpoints, auth, request/response formats, blueprints, webhooks, error handling, and code examples for OCR, structured extraction, form filling, and PII redaction.
allowed-tools: Bash, Read, Write
user-invocable: true
---

# DeepRead API Reference

You are helping a developer integrate DeepRead into their application. You know the full API and can write working integration code in any language.

**Base URL:** `https://api.deepread.tech`
**Auth:** `X-API-Key` header with key from `https://www.deepread.tech/dashboard` or via the device authorization flow (see Agent Authentication below)

---

## Agent Authentication (Device Authorization Flow)

These endpoints let an AI agent obtain an API key without the user ever copy/pasting secrets. Based on OAuth 2.0 Device Authorization Grant (RFC 8628).

### POST /v1/agent/device/code — Request a Device Code

**Auth:** None (public endpoint)
**Content-Type:** `application/json`

```json
{"agent_name": "my-agent"}
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_name` | string | No | Display name shown to the user during approval (e.g. "Claude Code", "My CI Bot"). Optional but strongly recommended — without it, the user sees "Unknown Agent". |

**Response (200 OK):**
```json
{
  "device_code": "a7f3c9d2e1b8...",
  "user_code": "HXKP-3MNV",
  "verification_uri": "https://www.deepread.tech/activate",
  "verification_uri_complete": "https://www.deepread.tech/activate?code=HXKP-3MNV",
  "expires_in": 900,
  "interval": 5
}
```

| Field | Description |
|-------|-------------|
| `device_code` | Secret code for polling — never show this to the user |
| `user_code` | Short code the user enters in their browser (format: `XXXX-XXXX`) |
| `verification_uri` | Base URL for manual code entry |
| `verification_uri_complete` | URL with code pre-filled — open this to skip manual entry (preferred) |
| `expires_in` | Seconds until the code expires (default: 900 = 15 minutes) |
| `interval` | Minimum seconds between poll requests |

---

### POST /v1/agent/device/token — Poll for API Key

**Auth:** None (public endpoint)
**Content-Type:** `application/json`

```json
{"device_code": "a7f3c9d2e1b8..."}
```

Poll this endpoint every `interval` seconds after the user has been shown the code.

**Responses:**

| Scenario | `error` field | `api_key` field | Action |
|----------|---------------|-----------------|--------|
| User hasn't acted yet | `"authorization_pending"` | `null` | Wait `interval` seconds, poll again |
| User approved | `null` | `"sk_live_..."` | Save the key, stop polling |
| User denied | `"access_denied"` | `null` | Stop polling, inform user |
| Code expired | `"expired_token"` | `null` | Start over with a new device code |

The response always includes all three fields (`error`, `api_key`, `key_prefix`). Check `api_key != null` to detect success — don't rely on key presence alone.

**Important:**
- The `api_key` is returned **exactly once**. After you retrieve it, the server clears it. Store it immediately.
- The `key_prefix` is a non-secret identifier for the key (useful for display/logging).
- Never show `device_code` or `api_key` to the user.

---

**What happens on the user's side (you don't need to call these):**
- User opens `verification_uri_complete` — the code is pre-filled, no typing needed
- User logs in (or signs up + confirms email for new users)
- User sees your agent name and clicks Approve → redirected to dashboard
- Once approved, the next poll to `/v1/agent/device/token` returns the `api_key`

---

## Processing

### POST /v1/process — Submit a Document

Uploads a document for async processing. Returns immediately with a job ID.

**Auth:** `X-API-Key: YOUR_KEY`
**Content-Type:** `multipart/form-data`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `file` | File | Yes | — | PDF, PNG or JPEG on every plan. Standard adds TIFF, WebP, BMP, GIF, DOCX, TXT; Enterprise adds more (see Rate Limits & Plans). A type your plan lacks is refused with `415` naming the plan that has it. |
| `pipeline` | string | No | plan default | Engine: `"extract"` (one OCR pass) or `"deep-extract"` (two OCR passes reconciled by an LLM judge, plus a second read that checks each extracted field value). Default: Free and Standard run `extract`, Enterprise runs `deep-extract`. The older names `fast`, `standard` and `searchable` still work as aliases (`fast` = `extract`, `standard` = `deep-extract`, `searchable` = `deep-extract` + `searchable_pdf=true`); a job's responses show the name you sent. |
| `speed` | string | No | `"standard"` | `"fast"` or `"standard"`. With `deep-extract`, `"fast"` runs **Deep Extract Fast**: about 2× faster, same accuracy, $90 per 1,000 pages. With `extract`, `"fast"` is accepted at the Extract price and mainly helps long documents. Standard and Enterprise plans (`402` on Free). Any other value is refused with `400`. |
| `schema` | string | No | — | JSON Schema for structured extraction |
| `blueprint_id` | string | No | — | Blueprint UUID (mutually exclusive with schema) |
| `preview` | string | No | `"false"` | Page images and a public preview link. Off unless you send `"true"`: anyone with the link can open the document, so it exists only on request. Works on every plan. Replaces `include_images` (deprecated but honoured). For click-to-highlight in the preview, send `include_markers` as well. |
| `include_markers` | string | No | `"false"` | Set `"true"` to return bounding boxes: layout blocks under top-level `grounding[]`, and `location.bounding_box` on each extracted field. Works on both engines and on every plan, Free included. Do not rely on `preview` alone to return boxes. |
| `per_page` | string | No | `"false"` | Per-page breakdown in `pages[]`. Replaces `include_pages` (deprecated but honoured). |
| `webhook_url` | string | No | — | Public http(s) URL to notify on completion (localhost, private and internal addresses are refused). Standard plan and up (`402` on Free). Deliveries are signed — see Webhooks. |
| `idempotency_key` | string | No | — | Up to 255 characters, unique per account. A retry with the same key returns the job the first request created (`200`, with its current status) instead of creating and charging a second job. The same key with a different file or different options is refused with `409`. |
| `searchable_pdf` | string | No | `"false"` | Set `"true"` to also produce a searchable PDF (`artifacts.searchable_pdf_url`). A Deep Extract add-on: `deep-extract` only, Enterprise plans. |
| `incognito` | string | No | `"false"` | Enterprise plans. Set `"true"` to never store the document in the clear: encrypted with a single-use key before it reaches storage and crypto-shredded when the job finishes. No preview link and no field locations; not combinable with `searchable_pdf`. Results are unaffected. |
| `retention_days` | string | No | — | Enterprise plans. Delete everything about the job — document, preview artifacts, extracted results — this many days after submission (integer 1–365). From the deadline on `GET /v1/jobs/{id}` has no content and the preview link answers 410; `data_deleted_at` confirms deletion. Combines with `incognito`. |
| `reviewer_email` | string | No | — | Have a person review the result in DeepRead: one email, or a team as comma-separated emails (up to 10). Turns the preview on; not combinable with `incognito`. See Human Review. |
| `review_due_hours` | string | No | — | With `reviewer_email`: the review is due this many hours after submission (1–8760). |
| `review_expiry_days` | string | No | `30` | With `reviewer_email`: an unfinished review closes this many days after submission (1–365). |
| `version` | string | No | — | Pipeline version for reproducibility |

**Note:** Provide `schema` OR `blueprint_id`, not both. Without either, only OCR text is returned.

Every j
````

## File: README.md
upstream: https://github.com/deepread-tech/skills/blob/main/README.md

````text
# DeepRead Skills

Teach any AI agent how to use the [DeepRead](https://www.deepread.tech) OCR API.

Install these skills and your AI coding assistant instantly knows how to integrate DeepRead — sign up, get an API key, extract text and structured data from documents, fill PDF forms, redact PII, use blueprints for optimized accuracy, handle webhooks, and manage errors.

## Skills

| Skill | What it does |
|-------|-------------|
| `/deepread-setup` | Get started — signup, API key, first request, structured extraction, blueprints |
| `/deepread-api` | Full API reference — all endpoints, auth, schemas, blueprints, webhooks, code examples |
| `/deepread-form-fill` | Fill PDF forms — submit form + JSON data, get back completed PDF with quality report |
| `/deepread-pii` | PII removal (Enterprise plans) — upload documents, detect and redact personal information, download clean files |

## Install

### Claude Code

```bash
npx skills add deepread-tech/skills
```

After installing, use the slash commands:

```
/deepread-setup      # walks you through signup, API key, and first request
/deepread-api        # full API reference — your agent can write integration code in any language
/deepread-form-fill  # fill PDF forms with AI — any PDF, no AcroForm needed
/deepread-pii        # detect and redact PII from documents
```

### Cursor

Copy the rule files into your project:

```bash
git clone https://github.com/deepread-tech/skills.git /tmp/deepread-skills
cp -r /tmp/deepread-skills/.cursor .
```

Or manually copy `.cursor/rules/deepread-setup.mdc`, `.cursor/rules/deepread-api.mdc`, `.cursor/rules/deepread-form-fill.mdc`, and `.cursor/rules/deepread-pii-removal.mdc` into your project's `.cursor/rules/` directory.

Rules use `alwaysApply: false` — Cursor will invoke them automatically when you're working with the DeepRead API.

### Windsurf

Copy the rule files into your project:

```bash
git clone https://github.com/deepread-tech/skills.git /tmp/deepread-skills
cp -r /tmp/deepread-skills/.windsurf .
```

Or manually copy `.windsurf/rules/deepread-setup.md`, `.windsurf/rules/deepread-api.md`, `.windsurf/rules/deepread-form-fill.md`, and `.windsurf/rules/deepread-pii-removal.md` into your project's `.windsurf/rules/` directory.

### Clawhub (OpenClaw Registry)

```bash
clawhub install uday390/deepread-ocr
```

The skills are published to the OpenClaw registry as `user-invocable` commands. Use `/deepread-setup`, `/deepread-api`, `/deepread-form-fill`, and `/deepread-pii` after installation.

## What is DeepRead

AI-native document processing API. Upload a PDF or image, get back extracted text and structured data. Two engines: Extract (one OCR pass) and Deep Extract (two OCR passes and an LLM judge). Both flag uncertain fields for human review; accuracy is measured on public benchmarks at deepread.tech/benchmarks.

**Key features:**
- **OCR** — Structured extraction via JSON Schema
- **Form Fill** — AI-powered PDF form filling with visual QA
- **PII Removal** — Detect and redact 14 types of personal information (Enterprise plans)
- Blueprints — optimized reusable schemas
- Per-field review flags (`needs_review` + `review_reason`) for human-in-the-loop review
- Human review in DeepRead — send `reviewer_email` and a person checks and corrects the result
- Webhook notifications
- Shareable preview links (no auth needed)

**Pricing:** Extract $15, Deep Extract $35 and Deep Extract Fast (`speed=fast`, about 2× faster) $90 per 1,000 pages; the Free plan includes 2,000 pages a month.

**Links:**
- Dashboard: `https://www.deepread.tech/dashboard`
- Docs: `https://www.deepread.tech/docs`

## License

MIT — [DeepRead Technologies](https://www.deepread.tech)
````
