> ## 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.
# Parse a Document from a URL
> Parse one document fetched from a URL with the platform's fast lite parse
*Rate limit tier: **submission**, 60 requests/min. See [Rate limits](/api-reference-v3/introduction#rate-limits).*
The platform fetches **one document** server-side from a URL and parses it with the fast lite parse. This endpoint is the URL analogue of [`POST /v3/parse/`](/api-reference-v3/parse/parse). It runs on your organization's system parse workflow, which the platform provisions on first use.
Provide one **HTTPS** URL. The response's `Content-Disposition` names the file, and the URL's path names it otherwise. See [File names](#file-names). The response references a [run](/concepts/runs-and-results). Poll [`GET /v3/runs/{run_id}/`](/api-reference-v3/runs/get) until `status` is `processed`. The parsed markdown sits at `results.parse.markdown`. A failed, non-2xx, or timed-out fetch returns `422` with the reason in `detail`.
The results envelope carries the **first** file's parse output. To import several URLs into one packet, use [upload from URL](/api-reference-v3/workflows/upload-from-url) and [document-packets/run](/api-reference-v3/document-packets/run) directly.
## File names
The response names a from-url file, not the request. The name matters twice. It carries the extension the import requires, and a URL whose path is an opaque key carries none. It is also the name you and your users see wherever the file is listed. The precedence is:
1. The `Content-Disposition` filename on the response, per [RFC 6266](https://www.rfc-editor.org/rfc/rfc6266). `filename*=UTF-8''…` wins over `filename=`, and any path is cut to its last segment.
2. Else the URL path's last segment: `https://example.com/invoices/april.pdf` imports as `april.pdf`.
3. Else the import fails with `422`.
The name travels in the header rather than in a request field. HTTP already names a downloaded file there, and every object store signs that header into a presigned URL. The API therefore stays URL-only, with no parallel name list to match `urls` in length and order. On S3, `ResponseContentDisposition` signs it in:
```python boto3 theme={null}
import boto3
s3 = boto3.client("s3")
url = s3.generate_presigned_url(
"get_object",
Params={
"Bucket": "my-bucket",
"Key": "uploads/7c1f3e9a",
"ResponseContentDisposition": 'attachment; filename="april-invoice.pdf"',
},
ExpiresIn=900,
)
```
GCS offers the same override through `response-content-disposition` on a V4 signed URL, and Azure through `rscd` on a SAS.
Whichever name applies must end in a supported extension, such as `.pdf`, `.docx` or `.png`. A bare key such as `uploads/7c1f3e9a` names the file `7c1f3e9a`, which has no extension, so the import fails with `422`. A name that collides with a file already in the parse workflow is renamed: `april.pdf` becomes `april (1).pdf`.
```bash curl theme={null}
curl -X POST 'https://api.anyformat.ai/v3/parse/from-url/' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"url": "https://example.com/invoices/april.pdf"}'
```
```python Python (requests) theme={null}
import requests
url = "https://api.anyformat.ai/v3/parse/from-url/"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
body = {"url": "https://example.com/invoices/april.pdf"}
triggered = requests.post(url, headers=headers, json=body).json()
print(triggered["run_id"])
```
```json Response (202 Accepted) theme={null}
{
"run_id": "069dcc2c-e14c-7606-8000-2ee4fb17b4fa",
"document_packet_id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e1",
"workflow_id": "0686bb97-8c30-70f0-8000-97669e000eb8",
"status": "queued"
}
```
```json Response (422, fetch failed) theme={null}
{
"error": "Remote fetch failed",
"detail": "Remote server returned 404",
"error_code": "VALIDATION_ERROR",
"retryable": false,
"request_id": "a1b2c3d4e5f67890abcdef1234567890"
}
```
## OpenAPI
````yaml POST /v3/parse/from-url/
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-v3/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 (`/v3/`). Every response under
a versioned prefix includes `X-API-Version`.
version: 3.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: document-packets
description: >-
Document packets group uploaded documents for a workflow. Address a packet
directly to (re-)run its workflow.
- name: runs
description: >-
Extraction runs — the 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: splits
description: >-
Splits — the sub-documents a splitter node carves out of a packet.
Download any one of them as a PDF, built from the source documents on
request and never stored.
- name: parse
description: >-
Parse a single document with the platform's fast lite parse — a one-call
shortcut over the workflow upload + run primitives, backed by your
organization's system parse workflow.
- name: health
description: Health check endpoints to verify API availability.
paths:
/v3/parse/from-url/:
post:
tags:
- parse
summary: Parse a document from a URL
description: >-
Parse one document fetched from a URL with the platform's fast lite
parse (atomic).
One document per call: an HTTPS `url`, or the `object_id` (plus
`filename`) of a file staged via `POST /v3/blobs/slots/`. The upload
runs
against your organization's system parse workflow, provisioned
automatically on first use. Poll `GET /v3/runs/{run_id}/` until `status`
is `processed`; the markdown is at `results.parse.markdown`.
A URL-fetched file is named by the response's `Content-Disposition`
filename when present, else by the last segment of the URL's path.
Not idempotent: every call fetches the document, creates a packet and
starts
a new run. For a retry-safe flow use `POST
/v3/workflows/{id}/upload/from-url/`
and then `POST /v3/document-packets/{id}/run/` with an
`Idempotency-Key`.
operationId: v3_parse_from_url
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ParseFromUrlRequest'
required: true
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RunTriggeredV3'
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
'400':
description: |-
`VALIDATION_ERROR` — The request failed validation.
`INVALID_VALUE` — A value in the request is not valid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
VALIDATION_ERROR:
value:
error: The request failed validation.
detail: The request failed validation.
error_code: VALIDATION_ERROR
retryable: false
request_id: req_abc123
INVALID_VALUE:
value:
error: A value in the request is not valid.
detail: A value in the request is not valid.
error_code: INVALID_VALUE
retryable: false
request_id: req_abc123
'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
'402':
description: >-
`INSUFFICIENT_CREDIT` — The organization has no extraction credit
left.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
INSUFFICIENT_CREDIT:
value:
error: The organization has no extraction credit left.
detail: The organization has no extraction credit left.
error_code: INSUFFICIENT_CREDIT
retryable: false
request_id: req_abc123
'403':
description: >-
Access denied — the API key lacks access to this resource or the
scope this call needs (`ACCESS_DENIED`,
`INSUFFICIENT_API_KEY_SCOPE`).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
ACCESS_DENIED:
value:
error: You do not have access to this resource.
detail: You do not have access to this resource.
error_code: ACCESS_DENIED
retryable: false
request_id: req_abc123
'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
'500':
description: >-
An internal error stopped the request — `retryable=true`. Retry with
backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
INTERNAL_ERROR:
value:
error: An internal error stopped the request.
detail: An internal error stopped the request.
error_code: INTERNAL_ERROR
retryable: true
request_id: req_abc123
'504':
description: '`GATEWAY_TIMEOUT` — The upstream service did not answer in time.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
GATEWAY_TIMEOUT:
value:
error: The upstream service did not answer in time.
detail: The upstream service did not answer in time.
error_code: GATEWAY_TIMEOUT
retryable: true
request_id: req_abc123
security:
- ApiKeyAuth: []
components:
schemas:
ParseFromUrlRequest:
properties:
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: >-
HTTPS URL the backend fetches server-side. The file is named by the
response's `Content-Disposition` filename when present, else by the
last segment of the URL's path. Pass exactly one of `url` or
`object_id`.
examples:
- https://example.com/invoices/april.pdf
object_id:
anyOf:
- type: string
- type: 'null'
title: Object Id
description: >-
`object_id` of a file staged via `POST /v3/blobs/slots/`, uploaded
already. Resolved server-side to the staged bytes, so the long
presigned `read_url` never needs to be passed around. Requires
`filename`. Pass exactly one of `url` or `object_id`.
examples:
- 06a953d9792572568000f838b051ca9b
filename:
anyOf:
- type: string
maxLength: 255
- type: 'null'
title: Filename
description: >-
Name for the staged file — required with `object_id` (a staged blob
carries no name of its own) and not accepted with `url`.
examples:
- april.pdf
type: object
title: ParseFromUrlRequest
description: >-
Body for ``POST /v3/parse/from-url/``.
The document arrives one of two ways: a fetchable HTTPS ``url``, or the
``object_id`` of a file staged via ``POST /v3/blobs/slots/`` — the id is
a
few characters where the staged file's presigned ``read_url`` is
kilobytes,
so an id-carrying caller (an MCP agent spending a context window) never
has
to round-trip the long URL.
examples:
- url: https://example.com/invoices/april.pdf
- filename: april.pdf
object_id: 06a953d9792572568000f838b051ca9b
RunTriggeredV3:
properties:
run_id:
type: string
title: Run Id
description: Unique identifier of the new run (hyphenated UUID).
examples:
- 069dcc2c-e14c-7606-8000-2ee4fb17b4f9
document_packet_id:
type: string
title: Document Packet Id
description: The document packet the run executes on (hyphenated UUID).
examples:
- 069dcc2c-e14c-7606-8000-2ee4fb17b4e1
workflow_id:
type: string
title: Workflow Id
description: The workflow being run (hyphenated UUID).
examples:
- 0686bb97-8c30-70f0-8000-97669e000eb8
status:
$ref: '#/components/schemas/RunStatus'
description: Status at acceptance time — normally `queued`.
examples:
- queued
type: object
required:
- run_id
- document_packet_id
- workflow_id
- status
title: RunTriggeredV3
description: |-
202 response for both run triggers (`upload/run/` and
`document-packets/{id}/run/`).
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
- error_code
- retryable
- request_id
properties:
error:
type: string
description: Short human-readable summary.
detail:
description: >-
Machine-readable detail, any JSON value. A string for most errors, a
list of field errors for validation failures, and an object for a
structured error such as `FILENAME_CONFLICT` (`detail.conflicts`).
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.
RunStatus:
type: string
enum:
- queued
- in_progress
- processed
- error
- cancelled
title: RunStatus
description: |-
Execution lifecycle of a run. Non-terminal: ``queued``,
``in_progress``. Terminal: ``processed`` (success), ``error``,
``cancelled``.
securitySchemes:
ApiKeyAuth:
type: http
description: >-
API key issued from app.anyformat.ai/api-key. Send as `Authorization:
Bearer `.
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.