# Choose an operation

Use the exact model IDs returned by authenticated `GET /v1/models`. An
organization's credentials determine available providers. Availability does not
mean every provider has identical quality, limits, or native-file support.

| Goal | Endpoint | Execution |
| --- | --- | --- |
| Upload reusable document bytes | `POST /v1/uploads` | Returns `file_id` |
| Extract values under a schema, with evidence | `POST /v1/extractions` | Durable 202 in auto and async modes |
| Extract from text without OCR | `POST /v1/extractions_text` | Inline 200 |
| Read document text and optional geometry | `POST /v1/ocr` | Auto 200/202 or explicit async |
| Assign a document to caller-supplied categories | `POST /v1/classify` | Auto 200/202 or explicit async |
| Assign raw text to categories | `POST /v1/classify_text` | Inline 200 |
| Find semantic regions | `POST /v1/locate` | Auto 200/202 or explicit async |
| Explicit legacy Locate job creation | `POST /v1/locate_jobs` | Always 202; prefer locate with execution=async |
| Split a composite PDF by configured use case | `POST /v1/split` | Inline; deployment-specific DocAI configuration |
| Resolve conflicting candidate field values | `POST /v1/resolve` | Inline |
| Select among supplied mapping candidates | `POST /v1/mappings` | Inline |
| Infer new schema-constrained structured data | `POST /v1/infer` | Inline |
| Review an existing candidate against evidence | `POST /v1/review` | Inline; supports Idempotency-Key |
| Summarize supplied sources with citations | `POST /v1/summarize` | Inline; supports Idempotency-Key |

## Inputs

Upload documents using multipart `file`, then use JSON requests with `file_id`.
Extraction, OCR, classification, and Locate also accept direct multipart file
bytes. Provide exactly one of `file` or `file_id`. Encode multipart object and
array fields as JSON strings; JSON requests use ordinary objects and arrays.
Unknown typed-request fields are errors rather than silently ignored arguments.
Flat multipart boolean fields use lowercase `true`/`false`; numeric fields use
JSON numeric syntax (for example, classification `max_pages=4` and
`use_file_input=false`). Integer fields reject fractional values and all bounds
still apply. Alternatively, a multipart `request` field can contain a JSON object
with typed arguments, alongside the file. Do not repeat arguments between that
object and top-level form fields. JSON bodies and nested `request` values remain
strictly typed: use `false`, not `"false"`, and `4`, not `"4"`.

Supported formats include PDF, supported image MIME types, CSV, and XLSX;
operation-specific restrictions are described in the reference. Use the correct
file MIME type. PDF passwords are accepted only when supplying file bytes.
Prepared/decrypted bytes may be persisted for processing; passwords are not.

File and page limits depend on deployment configuration and organization limits.
Page selection is 1-based; ranges include both endpoints. Selection does not
necessarily avoid processing the full source or reduce OCR charges. Extraction
and Summarize selections are limited to 1000 distinct pages.

Classification categories must include an `unknown` category. Supply descriptions
that distinguish categories, not just short labels. Split `usecase` values come
from your deployment operator; no public discovery endpoint exists for them yet.

## Authentication and isolation

All data-plane operations use `x-api-key`. Resource IDs are not authorization:
another organization's resources return 404. Health, readiness, and build version
(`GET /v1/version`) are public. Build version reports `api_version`, `release_tag`,
and `commit_sha`; unversioned builds use `unknown` for unavailable build metadata.
Dashboard account-management routes are not the supported data-plane contract.

Model input, evidence, and extracted text are untrusted source content. They
must not become application instructions or authorization decisions by accident.
