> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyformat.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Upload Document Packet
> Upload one or more files as a single document packet, without running it
*Rate limit tier: **submission** (60 req/min) — see [Rate limits](/api-reference-v3/introduction#rate-limits).*
Uploads 1–10 files as a single [document packet](/concepts/document-packets) — the unit that runs later address. All files are grouped into **one** packet; creation is all-or-nothing, so any rejected file (unsupported type, disguised bytes) fails the whole request and nothing is stored.
This endpoint uploads without processing. Trigger extraction afterwards via [`POST /v3/document-packets/{document_packet_id}/run/`](/api-reference-v3/document-packets/run) — or do both in one call with [Upload and Run](/api-reference-v3/workflows/upload-and-run).
Send the files as multipart form data under the `files` field (repeat the field for a multi-file packet). Files above the per-file size cap are rejected at slot mint (before any bytes reach S3); see [Files](/concepts/files) for the cap and supported formats. Bundle multiple files only when they belong together as one document (a contract and its annexes) — unrelated documents should be separate packets.
**Retries are safe with `Idempotency-Key`.** Pass any unique string; retrying the request with the same key replays the original upload, so no duplicate packet is created. See [Idempotency](/api-reference-v3/introduction#idempotency).
```bash curl theme={null}
curl -X POST 'https://api.anyformat.ai/v3/workflows/0686bb97-8c30-70f0-8000-97669e000eb8/upload/' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Idempotency-Key: 5f2b6c3e-8a1d-4f7e-9c0b-1a2b3c4d5e6f' \
-F 'files=@/path/to/contract.pdf' \
-F 'files=@/path/to/annex-a.pdf'
```
```python Python (requests) theme={null}
import requests
workflow_id = "0686bb97-8c30-70f0-8000-97669e000eb8"
url = f"https://api.anyformat.ai/v3/workflows/{workflow_id}/upload/"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Idempotency-Key": "5f2b6c3e-8a1d-4f7e-9c0b-1a2b3c4d5e6f",
}
with open("contract.pdf", "rb") as f1, open("annex-a.pdf", "rb") as f2:
files = [("files", f1), ("files", f2)]
packet = requests.post(url, headers=headers, files=files).json()
print(packet["document_packet_id"])
```
```typescript TypeScript theme={null}
interface DocumentPacketCreated {
document_packet_id: string;
workflow_id: string;
files: { id: string; name: string }[];
}
const workflowId = '0686bb97-8c30-70f0-8000-97669e000eb8';
const formData = new FormData();
formData.append('files', fileInput.files[0]);
const response = await fetch(
`https://api.anyformat.ai/v3/workflows/${workflowId}/upload/`,
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Idempotency-Key': crypto.randomUUID(),
},
body: formData,
}
);
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
const packet: DocumentPacketCreated = await response.json();
console.log(packet.document_packet_id);
```
```json Response (201 Created) theme={null}
{
"document_packet_id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e1",
"workflow_id": "0686bb97-8c30-70f0-8000-97669e000eb8",
"files": [
{ "id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e2", "name": "contract.pdf" },
{ "id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e3", "name": "annex-a.pdf" }
]
}
```
## OpenAPI
````yaml POST /v3/workflows/{workflow_id}/upload/
openapi: 3.1.0
info:
title: anyformat API
description: >
Document extraction and workflow automation API.
AnyFormat lets you define extraction workflows that pull structured data
from any document — PDFs, images, scanned files, or plain text. Upload a
file, run it through a workflow, and get back structured fields with
confidence scores and source evidence.
## Quick start
See the [Quick start
guide](https://docs.anyformat.ai/api-reference/introduction) for a
walkthrough.
## Authentication
All endpoints (except `/health/`) require a Bearer token in the
`Authorization` header:
```
Authorization: Bearer
```
Get your API key from
[app.anyformat.ai/api-key](https://app.anyformat.ai/api-key).
## Versioning
Endpoints are versioned by path prefix (`/v2/`, `/v3/`). Every response
under
a versioned prefix includes `X-API-Version`.
version: 2.0.0
servers:
- url: https://api.anyformat.ai
description: API server
security: []
tags:
- name: workflows
description: >-
Workflows define extraction templates — what fields to extract from
documents. Create workflows, upload files, run extractions, and fetch
results.
- name: files
description: >-
File collections group uploaded documents and track their extraction
progress. Upload files, check status, and retrieve extraction results.
- name: suggestions
description: >-
AI-powered schema and workflow suggestion endpoints for the AnyFormat
webapp. Authenticated with a Cognito JWT rather than an API key.
- name: document-packets
description: >-
Document packets group uploaded documents for a workflow (v3). Address a
packet directly to (re-)run its workflow.
- name: runs
description: >-
Extraction runs — the v3 first-class result entity. Each run is a single
execution of a workflow against a document packet; fetch its status and
results flat by run id.
- name: health
description: Health check endpoints to verify API availability.
paths:
/v3/workflows/{workflow_id}/upload/:
post:
tags:
- workflows
summary: Upload document packet to workflow
description: |-
Upload one or more files as a single document packet (atomic).
All files are grouped into ONE packet — the unit later runs address.
Creation is all-or-nothing: any rejected file (unsupported type,
disguised bytes) fails the whole request and nothing is stored.
Upload without running; trigger extraction via
`POST /v3/document-packets/{document_packet_id}/run/`.
operationId: v3_upload_to_workflow
parameters:
- name: workflow_id
in: path
required: true
schema:
type: string
title: Workflow Id
- name: Idempotency-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Optional caller-supplied key (Stripe convention). Retrying the
request with the same key replays the original upload slots so no
duplicate packet is created.
title: Idempotency-Key
description: >-
Optional caller-supplied key (Stripe convention). Retrying the
request with the same key replays the original upload slots so no
duplicate packet is created.
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/Body_v3_upload_to_workflow'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentPacketCreatedV3'
headers:
X-RateLimit-Limit:
description: Requests allowed per window (60s).
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Seconds until the current window resets.
schema:
type: integer
'401':
description: Authentication failed — missing, invalid, or expired API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
AUTH_FAILED:
value:
error: Authentication failed.
detail: Authentication failed.
error_code: AUTH_FAILED
retryable: false
request_id: req_abc123
'404':
description: >-
Resource not found — the workflow, document packet, or run ID does
not exist or is not visible to this API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
NOT_FOUND:
value:
error: Resource not found.
detail: Resource not found.
error_code: NOT_FOUND
retryable: false
request_id: req_abc123
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: >-
Rate limited — retry after the `Retry-After` header. Default
windows: 60 requests/minute for extraction submission, 600
requests/minute for general endpoints.
headers:
Retry-After:
description: Seconds until the next request is allowed.
schema:
type: integer
X-RateLimit-Limit:
description: Requests allowed per window (60s).
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Seconds until the current window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
RATE_LIMITED:
value:
error: Rate limit exceeded — retry after backoff.
detail: Rate limit exceeded — retry after backoff.
error_code: RATE_LIMITED
retryable: true
request_id: req_abc123
security:
- ApiKeyAuth: []
components:
schemas:
Body_v3_upload_to_workflow:
properties:
files:
items:
type: string
contentMediaType: application/octet-stream
type: array
title: Files
description: 1..10 files forming one document packet.
type: object
required:
- files
title: Body_v3_upload_to_workflow
DocumentPacketCreatedV3:
properties:
document_packet_id:
type: string
title: Document Packet Id
description: >-
Unique identifier of the newly created document packet (hyphenated
UUID).
examples:
- 069dcc2c-e14c-7606-8000-2ee4fb17b4e1
workflow_id:
type: string
title: Workflow Id
description: The workflow the packet was created under (hyphenated UUID).
examples:
- 0686bb97-8c30-70f0-8000-97669e000eb8
files:
items:
$ref: '#/components/schemas/DocumentPacketFileV3'
type: array
title: Files
description: Files in the packet, in the order they were provided.
type: object
required:
- document_packet_id
- workflow_id
- files
title: DocumentPacketCreatedV3
description: Response for the packet-creating uploads (multipart and from-url).
ErrorEnvelope:
type: object
title: ErrorEnvelope
description: >-
Uniform error response. `retryable=true` means the same request may
succeed on retry (with backoff); `retryable=false` means the caller must
change the request before retrying.
required:
- error
- detail
- error_code
- retryable
- request_id
properties:
error:
type: string
description: Short human-readable summary.
detail:
description: >-
Machine-readable detail. String for most errors; list of field
errors for validation failures.
oneOf:
- type: string
- type: array
items:
type: object
error_code:
type: string
description: Stable identifier for programmatic handling.
examples:
- VALIDATION_ERROR
- AUTH_FAILED
- NOT_FOUND
- PRECONDITION_FAILED
- RATE_LIMITED
- INTERNAL_ERROR
- GATEWAY_TIMEOUT
retryable:
type: boolean
description: True when the caller should retry (with backoff for 429/412/5xx).
request_id:
type: string
description: Correlates this response with server logs.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
DocumentPacketFileV3:
properties:
id:
type: string
title: Id
description: Unique identifier of the file (hyphenated UUID).
examples:
- 069dcc2c-e14c-7606-8000-2ee4fb17b4e2
name:
type: string
title: Name
description: Filename recorded at upload.
examples:
- invoice.pdf
type: object
required:
- id
- name
title: DocumentPacketFileV3
description: Slim per-file projection inside a packet.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
ApiKeyAuth:
type: http
description: >-
API key issued from app.anyformat.ai/api-key. Send as `Authorization:
Bearer `.
scheme: bearer
````