# Classify a document and split a bundled PDF with Unsiloed AI

Unsiloed AI's document classification API takes a PDF or image by URL and a list of your categories. Classify returns the matching category and scores its confidence for the whole document and page by page. Split cuts a bundled PDF into one PDF per category. Classify costs $0.02 per page and Split $0.02 per page of the submitted document on pay as you go. You submit a job with `POST https://agents.unsiloed.ai/zcj/sn9bwqqturqd/classify` or `POST https://agents.unsiloed.ai/zcj/sn9bwqqturqd/splitter`, pay the 402 price quote, then poll the job for the result, with the bearer credential the storefront issues on every call.

## At a glance

- **Endpoints:** `POST https://agents.unsiloed.ai/zcj/sn9bwqqturqd/classify` and `GET https://agents.unsiloed.ai/zcj/sn9bwqqturqd/classify/{job_id}`. For Split, `POST https://agents.unsiloed.ai/zcj/sn9bwqqturqd/splitter` and `GET https://agents.unsiloed.ai/zcj/sn9bwqqturqd/splitter/{job_id}`.
- **Body:** `file_url` and `categories`. `categories` is a JSON-encoded string holding an array of objects, each with a `name`.
- **Price:** Classify $0.02 per page, Split $0.02 per page, counted in pages of the submitted document. Polling a job draws nothing.
- **Payment:** a 402 price quote. Pay it over x402 or MPP (wallet rails in USDC) and retry the request. Card works for calls of $0.50 or more.
- **Credential:** an agent bearer from [auth.md](https://agents.unsiloed.ai/zcj/sn9bwqqturqd/auth.md). Send it on the submit and on the result call.
- **Response:** a `job_id` at once, then the result when `status` is `completed`.
- **Full purchase flow:** [the buyer skill](https://agents.unsiloed.ai/zcj/sn9bwqqturqd/SKILL.md)

## Classify one document

1. Submit the document and your categories with the bearer:

   ```bash
   curl -s -X POST https://agents.unsiloed.ai/zcj/sn9bwqqturqd/classify \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -d '{"file_url": "https://www.irs.gov/pub/irs-pdf/f1040.pdf", "categories": "[{\"name\":\"tax form\"},{\"name\":\"invoice\"},{\"name\":\"contract\"}]"}'
   ```

   The storefront answers `402` with the price for the document's pages in `payment.amountUsd`. Nothing is charged at this point.

2. Pay the quote with your x402 or MPP client and retry the same request with the proof attached. Keep the bearer on the retry. On MPP, `Authorization` carries the payment, so send the bearer as `ZC-Agent-Authorization: Bearer <token>` instead. The submit answers `202`:

   ```json
   {"job_id": "<job_id>", "status": "processing", "message": "..."}
   ```

   The example request above paid $0.04, two pages at the pay-per-page rate.

3. Poll the job with the same bearer until `status` is `completed` or `failed`:

   ```bash
   curl -s https://agents.unsiloed.ai/zcj/sn9bwqqturqd/classify/<job_id> \
     -H "Authorization: Bearer $ACCESS_TOKEN"
   ```

   The status runs `queued`, `processing`, then `completed` or `failed`. Jobs usually finish within seconds to a few minutes. The result call is free. A completed job returns:

   ```json
   {"job_id": "<job_id>", "status": "completed", "error": null,
    "result": {"success": true, "classification": "<category>", "confidence": <0-1>,
      "total_pages": <n>, "processed_pages": <n>,
      "categories": [{"category": "<category>", "pages": [<page>], "page_count": <n>, "confidence": <0-1>}],
      "page_results": [{"page": 1, "classification": "<category>", "confidence": <0-1>, "success": true, "raw_result": "..."}]}}
   ```

## Read the classification

| Field | Use it for |
| --- | --- |
| `classification` | The dominant category. Route the document on this value. |
| `confidence` | The score for that category, from 0 to 1 |
| `categories` | Every category that pages voted for, with the `pages` that voted for it and its own confidence |
| `page_results` | One entry per processed page: its `classification`, `confidence` and the model's `raw_result` |
| `processed_pages`, `total_pages` | How many pages were read, against the document's length |

When one PDF holds several documents, use Split instead.

## Split a bundled PDF

Send the PDF and the categories to split into. Here a `description` helps separate similar categories:

```bash
curl -s -X POST https://agents.unsiloed.ai/zcj/sn9bwqqturqd/splitter \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"file_url": "<url of the bundled PDF>", "categories": "[{\"name\":\"invoice\",\"description\":\"Itemised charges\"},{\"name\":\"contract\"}]", "enable_reordering": false}'
```

The submit takes the same 402 and payment as Classify, then returns a `job_id`. Poll `GET https://agents.unsiloed.ai/zcj/sn9bwqqturqd/splitter/{job_id}` with the bearer. When `status` is `completed`, `result.files` lists one PDF per matched category. Each file carries a `name`, a `fileId`, a `full_path` download link valid for about an hour, and a `confidence_score` from 0 to 1. Download the files before the links expire. Set `enable_reordering` to `true` to put the pages inside each file into logical order. It applies only to categories with more than one page.

## Choose Classify or Split

| The document | Call | What comes back |
| --- | --- | --- |
| One document whose type decides where it goes | Classify | One category, with per-page votes |
| One PDF that holds several documents | Split | One PDF per category, each with a download link |
| An image (JPG, PNG, GIF, WebP, BMP, TIFF) | Classify | Split takes PDFs only |

## Boundaries

- Classify reads at most the first four pages of a document, but usage is the full page count. A ten-page PDF is classified from pages 1 to 4 and costs $0.20.
- Classify accepts a category `description` but uses only the names. Split uses descriptions to separate similar categories.
- Split classifies every page. A category that matches no page produces no file.
- Each submit takes one `file_url` and creates one job.
- Send the bearer on the submit as well as on the result call. A job submitted without it cannot be read back.
- An unpaid 402 charges nothing, so it is safe to stop there. Prepaid Credits lower the rate to $0.0125 per page, with a minimum purchase of $5. Buy them at `/plans/{planId}/purchase`, with the plan id from `manifest.json`.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `402` with no `reason` | The price quote for the submit | Pay it and retry the same request, or stop |
| `401 bearer_required` | The call needs a bearer credential | Register at [auth.md](https://agents.unsiloed.ai/zcj/sn9bwqqturqd/auth.md) and resend with `Authorization: Bearer` |
| `401 invalid_token` | The token expired or did not verify | Exchange your stored assertion for a fresh token and retry |
| `settlement_failed` | The payment did not settle | Fix the wallet, then send a fresh request for a new 402 |
| `usage_exhausted` | The Credits balance ran out | Top up with `POST https://agents.unsiloed.ai/zcj/sn9bwqqturqd/extend` |
| `status: failed` | The job did not finish | Read the `error` field before submitting again |

## Frequently asked questions

### How much does it cost to classify a PDF?

Classify charges $0.02 per page of the submitted document on pay as you go, or $0.0125 per page on prepaid Credits. The 402 states the exact amount before you pay. Polling the result costs nothing.

### Does Classify read every page of a long document?

No. It classifies a document longer than four pages from its first four, and still counts every page as usage. Split classifies every page and cuts the PDF into one file per category.

### Why does the result call need the bearer?

The job is read back with the same agent credential that submitted it. Send `Authorization: Bearer` on the submit and on every poll. On MPP, send it as `ZC-Agent-Authorization`.

### How do I write the categories field?

Send a string that holds a JSON array, such as `"[{\"name\":\"invoice\"},{\"name\":\"contract\"}]"`, not a bare array. Each object needs a `name`. Split also uses an optional `description`.

### When should I split a PDF instead of classifying it?

Split when one PDF holds several documents and you need a separate file for each type. Classify when the PDF is one document and you only need its category to route it.

## Keep reading

- [Buyer skill](https://agents.unsiloed.ai/zcj/sn9bwqqturqd/SKILL.md): the full purchase flow
- [Identity](https://agents.unsiloed.ai/zcj/sn9bwqqturqd/auth.md): register and refresh the agent bearer
- [How to pay](https://agents.unsiloed.ai/zcj/sn9bwqqturqd/payment.md): the 402, each rail and Credits
- [Error reference](https://agents.unsiloed.ai/zcj/sn9bwqqturqd/errors.md): every error code
- [Classify API reference](https://agents.unsiloed.ai/zcj/sn9bwqqturqd/services/classify/openapi.json)
- [Split API reference](https://agents.unsiloed.ai/zcj/sn9bwqqturqd/services/split/openapi.json)

---

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