# Hanji

> Hanji parses documents (PDF, PPTX, DOCX, images) into structured, AI-ready JSON: text chunks with page numbers and bounding boxes, tables as structured cells plus a markdown rendering, and figures. It can also fill an arbitrary JSON schema from a document, with a per-field citation (page, bounding box, verbatim source text) for every value. Sync, async batch, and schema extraction share one engine and one response schema.

Key facts for integrators:

- Base URL: `https://api.hanji.dev`. Auth: `X-API-KEY` header on every request. Create keys at https://hanji.dev/dashboard (Free plan includes 1,000 credits; one parsed page = 1 credit).
- Pricing is in credits ($0.003 per credit): parsing 1 credit per page ($3 per 1,000 pages); schema extraction 4 credits per page ($12 per 1,000 pages) all-in (the parse is included, not billed on top).
- Supported inputs: PDF, PPTX, DOCX, PNG, JPEG, WebP, TIFF, HEIC/HEIF, BMP. Limits: 2,000 pages and 150 MB per document (larger fails with 413). The file type is detected from the file itself; the filename doesn't matter.
- Parse: `POST /v1/parse` with a JSON body `{"url": "..."}`, or `POST /v1/parse/file` as a multipart upload. Both return `{"chunks": [...]}` in reading order; chunk types are `text`, `table` (with `cells`), and `image`, each with `page_no` and `bbox` in PDF points. Optional `table_output_format: "cell_grid"` returns a true bounding box per table cell (default `"markdown"`). Optional `include_content: true` additionally returns `content`: the entire parsed document as one text string in reading order (sync only). Compatibility aliases: `POST /v1/extract` and `POST /v1/extract/file` still work; prefer `/v1/parse` for new integrations.
- Schema extraction: `POST /v1/extract/schema` (URL) or `POST /v1/extract/schema/file` (upload) with a JSON Schema; returns `values` plus per-field `evidence` citations (`page`, `bbox` normalized 0-1000, `text`, `confidence`). `strict` mode (default) nulls any value whose quote can't be verified. `include_ocr_text: true` additionally returns `ocr_text`: the whole document as one text string in reading order (the same text `/v1/parse` returns as `content`), so fields and full text arrive from one call; the default response is unchanged.
- Bulk: `POST /v1/files` returns a presigned upload URL per file; upload bytes, then `POST /v1/batches` with the `file_id`s and poll `GET /v1/batches/{batch_id}`. Inputs and results expire after 3 days; `Idempotency-Key` on batch creation makes retries safe. Batches accept the same `extract_text` / `extract_images` options plus a `metadata` object echoed on every poll.
- Retention: sync documents are processed in memory and never stored. Batch uploads and results are deleted automatically after 3 days; URL-sourced batch inputs are never stored. Hanji never trains on customer data.
- Webhooks (production alternative to polling): pass `webhook: {"mode": "svix"}` on `POST /v1/batches` to get a signed `batch.update` event when the batch reaches a terminal status (`completed` / `partially_failed` / `failed` / `cancelled`). Signatures are Svix-wire-compatible (verify with the `svix` library). Opt-in per batch; register endpoints in the dashboard. `webhook: {"mode": "direct", "url": "..."}` sends the same event unsigned to an inline URL for prototyping. Polling `GET /v1/batches/{id}` is rate-limited to 200 req/s per org.

## Guides

- [Introduction and quickstart](https://docs.hanji.dev/introduction.md): What Hanji returns, a five-minute first parse (URL or upload), the chunk schema field by field, request options, pricing and credits (including what counts as a page), limits, auth, and the error table.
- [Schema extraction](https://docs.hanji.dev/guides/schema-extraction.md): Fill an arbitrary JSON schema from a document, with a per-field citation for every value, `strict` grounding, confidence scores, and schema-writing tips.
- [Batch processing](https://docs.hanji.dev/guides/batch.md): Async batch extraction with presigned uploads, one batch submission, cursor-based polling, status lifecycle, error codes, and limits.
- [Webhooks](https://docs.hanji.dev/guides/webhooks.md): Signed `batch.update` completion events (Svix-wire-compatible verification), opt-in per batch, the four terminal statuses incl. `partially_failed`, handler examples in Python + TypeScript, retries and idempotency, direct (unsigned) mode, and the dashboard.

## API Reference

- [Parse a document by URL](https://docs.hanji.dev/api-reference/v1/parse-a-document-by-url.md): `POST /v1/parse`
- [Parse an uploaded document](https://docs.hanji.dev/api-reference/v1/parse-an-uploaded-document.md): `POST /v1/parse/file`
- [Fill a schema from a document by URL](https://docs.hanji.dev/api-reference/v1/fill-a-schema-from-a-document-by-url.md): `POST /v1/extract/schema`
- [Fill a schema from an uploaded document](https://docs.hanji.dev/api-reference/v1/fill-a-schema-from-an-uploaded-document.md): `POST /v1/extract/schema/file`
- [Register a file for batch upload](https://docs.hanji.dev/api-reference/v1/register-a-file-for-batch-upload.md): `POST /v1/files`
- [Check upload status](https://docs.hanji.dev/api-reference/v1/check-upload-status.md): `GET /v1/files/{file_id}`
- [Create a batch](https://docs.hanji.dev/api-reference/v1/create-a-batch.md): `POST /v1/batches`
- [List your batches](https://docs.hanji.dev/api-reference/v1/list-your-batches.md): `GET /v1/batches`
- [Poll a batch](https://docs.hanji.dev/api-reference/v1/poll-a-batch.md): `GET /v1/batches/{batch_id}`
- [Download an item result](https://docs.hanji.dev/api-reference/v1/download-an-item-result.md): `GET /v1/batches/{batch_id}/items/{item_id}/result`
- [Cancel a batch](https://docs.hanji.dev/api-reference/v1/cancel-a-batch.md): `POST /v1/batches/{batch_id}/cancel`
- [batch.update webhook](https://docs.hanji.dev/api-reference/batch-update-webhook.md): The event body delivered to your endpoint when a batch reaches a terminal status.

## Optional

- [OpenAPI spec](https://docs.hanji.dev/openapi.json): Full request/response schemas for every endpoint.