> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Document Extraction

> Read document sets into structured fields with source pages and confidence.

Document Extraction is a [compute goal](/api-reference/compute/create). Give it
documents and a field list. It can extract, check other tools and ask you about
unresolved fields before returning its result. The vision provider is the initial
baseline; the Reducto/Extend comparison and final provider selection are pending.

## Upload and create a goal

Upload raw bytes to `POST /v1/compute/documents` with `Content-Type: application/pdf`,
`image/png` or `image/jpeg`. Authenticate with an access token or a signed **write**
proof and `X-Agent-ID`. The response contains `document_id`, `pages`, `mime`,
`sha256` and `expires_at`. Documents are private to that agent. There are no public
document URLs. `DELETE /v1/compute/documents/{id}` removes your upload.

Create a goal through the normal quote/payment flow:

```json theme={null}
{
  "objective": "Extract invoice fields, check inconsistencies and ask me about unresolved totals.",
  "params": {
    "document_extraction": {
      "documents": ["b637058f-55b4-4f37-8665-2de209372e78"],
      "fields": [
        {"name": "invoice_number", "description": "The printed invoice number", "type": "string"},
        {"name": "total", "description": "The final invoice total", "type": "number"}
      ],
      "confidence_threshold": 0.8
    }
  },
  "budget_usdc": 2
}
```

Field types are `string`, `number` and `boolean`. For classification, include a
field describing the document type you need. Field names are unique ASCII
identifiers starting with a letter. Each document uses the same field list.
The extraction step uses the saved list and threshold; the planner cannot lower
the threshold to fill a gap.

## Results and unresolved fields

Read the goal's [outputs](/api-reference/compute/outputs). Each extraction writes
`results/document-extraction/{task_id}.json`, including `pages_processed`,
`cost_usdc`, provider and fields:

```json theme={null}
{
  "name": "total",
  "document_id": "b637058f-55b4-4f37-8665-2de209372e78",
  "status": "resolved",
  "value": 120.5,
  "page": 2,
  "quote": "Total €120.50",
  "region": null,
  "confidence": 0.95,
  "reason": null
}
```

Page numbers start at 1; an image is one page. A region uses normalized
`left`, `top`, `width`, `height` coordinates in `[0,1]`. Every resolved field has
a page and either quoted text or a region. Below the confidence threshold,
missing evidence, invalid types or unknown confidence produce `status: unresolved`
and `value: null`. A person can clarify a missing value, but their answer does not
become a document citation. Confidence is provider-reported, not a guarantee of
accuracy; vision confidence is a model self-assessment.

## Price and limits

Extraction costs **$0.05 per page in production**, **$0.001 per page in staging
and development**, drawn from the compute budget. The page count comes from the
uploaded file. Repeat extraction steps process and charge those pages again.
Orchestration and any other tools are additional. The final compute receipt's
`metadata.document_extraction` records `pages_processed`, `cost_usdc` and
`scope: goal_lifetime` (including earlier runs of a revived goal). This is a
breakdown of the goal's spend, not a second charge.

Limits: 10 MiB and 20 pages per document, 10 documents per goal, 50 scalar fields,
and 20 active uploads per agent. Encrypted or malformed PDFs are rejected.
Upload access ends after 24 hours; daily cleanup removes expired bytes. Extracted
results and receipts remain with the goal. Upload again if a long-running goal
needs an expired document.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.