> ## 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.

# Upload a document

> Upload a PDF or image for a Document Extraction goal

Stores one document for [Document Extraction](https://docs.oneshotagent.com/api-reference/compute/document-extraction). Pass the returned `document_id` in `params.document_extraction.documents` when you [create a goal](https://docs.oneshotagent.com/api-reference/compute/create.md).

Documents are private to the agent that uploaded them. There are no public document URLs. Access ends at `expires_at`, 24 hours after upload.

## Authentication

A signed **write proof** or an access token: see [Authentication schemes](https://docs.oneshotagent.com/api-reference/openapi.md#authentication-schemes).

## Request body

The raw file bytes, not JSON or a form.

**Content-Type** `string` *required*

`application/pdf`, `image/png` or `image/jpeg`.

Limits: 10 MiB and 20 pages per document, 20 active uploads per agent. An image counts as one page. Page counts come from the file itself.

## Response

`201` with:

**document\_id** `string`

UUID to pass in `params.document_extraction.documents`.

**mime** `string`

The stored type.

**pages** `number`

Pages counted in the file. Extraction is charged per page (see [Pricing](https://docs.oneshotagent.com/pricing.md)).

**sha256** `string`

Hex SHA-256 of the bytes.

**expires\_at** `string`

ISO 8601. Upload again after this if a goal still needs the document.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/compute/documents \
  -H "Content-Type: application/pdf" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -H "x-agent-proof: <base64 EIP-712 proof, scope write>" \
  --data-binary @invoice.pdf
```

```json 201 theme={null}
{
  "document_id": "b637058f-55b4-4f37-8665-2de209372e78",
  "mime": "application/pdf",
  "pages": 2,
  "sha256": "9f2c4e1a7b...",
  "expires_at": "2026-10-25T12:00:00.000Z"
}
```

## Errors

| Status | `error` | Meaning |
| - | - | - |
| `400` | `invalid_document_size` | Empty body. |
| `413` | `payload_too_large` | Over 10 MiB. |
| `415` | `unsupported_document_type` | `Content-Type` is not PDF, PNG or JPEG. |
| `422` | `invalid_or_encrypted_document` | Malformed or encrypted file, or an image too large to read. |
| `422` | `document_page_limit` | More than 20 pages. |
| `429` | `document_storage_limit` | 20 active uploads. [Delete one](https://docs.oneshotagent.com/api-reference/compute/documents-delete.md) or wait for one to expire. |
| `503` | `document_validation_busy`, `document_upload_unavailable` | Retry later. |


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