# Parse a PDF into Markdown with Unsiloed's document parsing API

Unsiloed Parse turns a PDF, scan, image, DOCX or PPTX at a URL into ordered Markdown and HTML chunks, with a type, a page number, a bounding box and a confidence score on every segment. It costs $0.02 per page, and a 402 quotes the document's page count before anything is charged. Send `POST https://agents.unsiloed.ai/zcj/7686ywrlv2e2/parse` with the document's URL and an agent bearer, pay the quote, then poll `GET https://agents.unsiloed.ai/zcj/7686ywrlv2e2/parse/{job_id}` with the same bearer.

## At a glance

- **Submit:** `POST https://agents.unsiloed.ai/zcj/7686ywrlv2e2/parse` with `{"url": "<public or presigned URL>"}`
- **Result:** `GET https://agents.unsiloed.ai/zcj/7686ywrlv2e2/parse/{job_id}`. Polling is free.
- **Credential:** a free agent bearer, `Authorization: Bearer <access token>`, on the submit and on every result call
- **Price:** $0.02 per page pay as you go, or $0.0125 per page on prepaid Credits. A page is one PDF page, one image or one slide.
- **Payment:** a 402 price quote, paid over x402 (Base USDC) or MPP (Tempo USDC) and then retried
- **Response:** `chunks` of `segments`, each with `markdown`, `html`, `segment_type`, `page_number`, `bbox`, `confidence` and OCR detail
- **Full purchase flow:** [the buyer skill](https://agents.unsiloed.ai/zcj/7686ywrlv2e2/SKILL.md)

## Parse a PDF to Markdown

1. Get a bearer. Register a free agent credential once and exchange it for a short-lived access token, as [auth.md](https://agents.unsiloed.ai/zcj/7686ywrlv2e2/auth.md) describes. If you already hold a credential, reuse it. Every call below carries this header:

   ```
   Authorization: Bearer <access token>
   ```

   On MPP, the payment occupies `Authorization`, so send `ZC-Agent-Authorization: Bearer <access token>` instead.

2. Submit the document URL with the bearer:

   ```bash
   curl -s -X POST https://agents.unsiloed.ai/zcj/7686ywrlv2e2/parse \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer <access token>' \
     -d '{"url": "https://www.irs.gov/pub/irs-pdf/f1040.pdf"}'
   ```

   The storefront answers `402` with a quote for the document's pages at $0.02 per page. Nothing is charged unless you pay it.

3. Pay the 402 with your wallet, then send the identical request again. Attach the proof and keep the bearer on the request. On x402 the proof goes in the `x-payment` header. The blank two-page Form 1040 above was quoted and paid at $0.04, which is two pages at the pay-per-page rate. The response has this shape:

   ```json
   {"job_id": "<job_id>", "status": "Starting", "credit_used": "<pages counted>", "message": "<polling hint>"}
   ```

   Keep `job_id`. It is the only way to fetch the result.

4. Poll with the same bearer:

   ```bash
   curl -s https://agents.unsiloed.ai/zcj/7686ywrlv2e2/parse/<job_id> \
     -H 'Authorization: Bearer <access token>'
   ```

   `status` moves from `Starting` through `Processing` to one of three terminal statuses: `Succeeded`, `Failed` or `Cancelled`. Stop polling when you reach any of them. On `Failed`, `message` gives the reason. A result call draws nothing.

5. Read the result. On `Succeeded`, the response carries `page_count`, `total_chunks` and `chunks`. Each chunk holds `chunk_id`, `chunk_length`, `embed` and `segments`. Each segment looks like this:

   ```
   {
     "segment_id": "<id>",
     "segment_type": "<PageHeader | Text | Table | ...>",
     "page_number": <page>,
     "confidence": <layout score>,
     "markdown": "<segment as Markdown>",
     "html": "<segment as HTML>",
     "content": "<OCR text>",
     "ocr": [{"text": "<word>", "bbox": {...}, "confidence": <score>}],
     "bbox": {"left": <n>, "top": <n>, "width": <n>, "height": <n>},
     "page_width": <n>, "page_height": <n>
   }
   ```

   Join `markdown` across segments, in order, to get the document text. Use the other fields as follows:

   - `segment_type` lets you drop headers and footers.
   - `page_number` and `bbox` let you cite where a passage sits.
   - `confidence` lets you flag weak segments. It is the layout model's score for that segment, and each OCR word carries its own score.

   For the Form 1040, the result held four chunks over two pages, made of `PageHeader`, `Text` and `PageFooter` segments. The full response for those two pages was about 362 KB, mostly OCR detail.

## Options for OCR, page ranges and PII

Add these fields to the submit body as needed:

| Need | Field and value |
| --- | --- |
| Process only some pages | `page_range`: `"1-5"`, `"2,4,6"` or `"[1,3,5]"`. Defaults to all pages. |
| Scanned pages or a poor text layer | `ocr_strategy`: `"force_ocr"`. The default, `"auto_detection"`, runs OCR only where a page needs it. |
| Block documents that contain personal data | `detect_pii`: `true`. The job is blocked when PII at or above `pii_block_severity` is found. The default severity is `any`. |
| A smaller response | `output_fields`: `"{\"ocr\": false}"`, or `response_profile`: `"slim"`, which also drops `content` and `confidence` |
| Forms and applications | `segmentation_version`: `"v2"`, which adds `KeyValuePair`, `Signature` and `Seal` segments |

## Limits and charges

- Each request takes one document, sent by URL. Parse accepts PDF, DOCX, JPEG, PNG, WEBP and PPTX. Other formats are converted to PDF first.
- Excel workbooks use a separate route, `POST https://agents.unsiloed.ai/zcj/7686ywrlv2e2/parse/excel`, with its own options.
- The quote covers the document's page count. An unpaid 402 charges nothing, so you can safely stop there. Paying it completes the purchase.
- The result is read with the credential the job was submitted under, so send the bearer on the submit as well as on every result call. A job submitted without a bearer is still charged, but its result cannot be read: the result call for that job answers `401 bearer_required` when sent without a credential and `404 task_not_found` when sent with one.
- Card payment covers a per-call quote only at $0.50 or more. For small jobs, pay by wallet or draw from Credits. Credits have a $5 minimum and are bought at `/plans/{planId}/purchase`. The plan id is in [the catalog](https://agents.unsiloed.ai/zcj/7686ywrlv2e2/manifest.json).

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `402` | The price quote. Nothing is charged yet. | Pay it and resend the same request with the bearer, or stop |
| `401 bearer_required` | No agent bearer on the call | Add `Authorization: Bearer <access token>` |
| `401 invalid_token` | The access token expired or did not verify | Exchange the stored assertion for a fresh token |
| `404 task_not_found` | This credential does not know the job | Use the `job_id` and bearer from the submit |
| `400` | Missing `url`, an unsupported file type or an invalid parameter | Fix the body |
| `settlement_failed` | The payment did not settle | Fix the wallet, then send a fresh request for a new 402 |
| `503` | The job queue is at capacity | Retry after the `Retry-After` duration |

## Frequently asked questions

### How much does it cost to parse a PDF with Unsiloed?

Pay as you go costs $0.02 per page, counted in pages of the submitted document. Prepaid Credits cost $0.0125 per page, and the Growth plan costs $0.01 per page. Polling for the result is free.

### Does the Unsiloed OCR API handle scanned PDFs and images?

Yes. Parse accepts scans and JPEG, PNG or WEBP images, and it applies OCR where a page has no usable text layer. To run OCR on every page, set `ocr_strategy` to `"force_ocr"`.

### How long does a parse job take?

Jobs usually finish within seconds to a few minutes. For the two-page Form 1040 example, the job's `started_at` and `finished_at` were under two seconds apart, and the result call answered in 1.0 seconds.

### Why is the parse response so large?

Each segment carries word-level OCR results with their own bounding boxes and scores. To keep the Markdown and drop that detail, set `output_fields` to `"{\"ocr\": false}"`.

### Can the same credential call Extract, Classify and Split?

Yes. The same agent credential reaches Extract, Classify and Split on this storefront. Extract (`POST https://agents.unsiloed.ai/zcj/7686ywrlv2e2/v2/extract`) returns the fields a JSON Schema names, Classify (`POST https://agents.unsiloed.ai/zcj/7686ywrlv2e2/classify`) sorts a PDF or image into categories you supply, and Split (`POST https://agents.unsiloed.ai/zcj/7686ywrlv2e2/splitter`) divides a bundled PDF into a file for each category. Each is a job whose submit returns a job id that you poll for the result. They are priced at $0.02 per page, $0.02 per page and $0.02 per page.

## Keep reading

- [Buyer skill](https://agents.unsiloed.ai/zcj/7686ywrlv2e2/SKILL.md): the full purchase flow
- [Identity](https://agents.unsiloed.ai/zcj/7686ywrlv2e2/auth.md): register and exchange the agent credential
- [How to pay](https://agents.unsiloed.ai/zcj/7686ywrlv2e2/payment.md): x402, MPP, card and Credits
- [Error reference](https://agents.unsiloed.ai/zcj/7686ywrlv2e2/errors.md): every storefront error code
- [Parse API reference](https://agents.unsiloed.ai/zcj/7686ywrlv2e2/services/parse/openapi.json): every request and response field

---

Updated 2026-11-06. All Unsiloed AI guides: https://agents.unsiloed.ai/guides.md. Storefront: https://agents.unsiloed.ai/zcj/7686ywrlv2e2/llms.txt.