Upload from URL

curl -X POST 'https://api.anyformat.ai/v3/workflows/0686bb97-8c30-70f0-8000-97669e000eb8/upload/from-url/' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": [
      "https://example.com/invoices/april.pdf",
      "https://example.com/invoices/april-annex.pdf"
    ],
    "metadata": {"customer_reference": "CR-2026-99001-ZTX"}
  }'

import requests

workflow_id = "0686bb97-8c30-70f0-8000-97669e000eb8"
url = f"https://api.anyformat.ai/v3/workflows/{workflow_id}/upload/from-url/"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

body = {
    "urls": [
        "https://example.com/invoices/april.pdf",
        "https://example.com/invoices/april-annex.pdf",
    ]
}

packet = requests.post(url, headers=headers, json=body).json()
print(packet["document_packet_id"])

{
  "document_packet_id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e1",
  "workflow_id": "0686bb97-8c30-70f0-8000-97669e000eb8",
  "files": [
    { "id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e2", "name": "april.pdf", "original_name": null },
    { "id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e3", "name": "april-annex.pdf", "original_name": null }
  ]
}

{
  "error": "Remote fetch failed",
  "detail": "Remote server returned 404",
  "error_code": "VALIDATION_ERROR",
  "retryable": false,
  "request_id": "a1b2c3d4e5f67890abcdef1234567890"
}

POST

workflows

{workflow_id}

upload

from-url

curl -X POST 'https://api.anyformat.ai/v3/workflows/0686bb97-8c30-70f0-8000-97669e000eb8/upload/from-url/' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": [
      "https://example.com/invoices/april.pdf",
      "https://example.com/invoices/april-annex.pdf"
    ],
    "metadata": {"customer_reference": "CR-2026-99001-ZTX"}
  }'

import requests

workflow_id = "0686bb97-8c30-70f0-8000-97669e000eb8"
url = f"https://api.anyformat.ai/v3/workflows/{workflow_id}/upload/from-url/"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

body = {
    "urls": [
        "https://example.com/invoices/april.pdf",
        "https://example.com/invoices/april-annex.pdf",
    ]
}

packet = requests.post(url, headers=headers, json=body).json()
print(packet["document_packet_id"])

{
  "document_packet_id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e1",
  "workflow_id": "0686bb97-8c30-70f0-8000-97669e000eb8",
  "files": [
    { "id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e2", "name": "april.pdf", "original_name": null },
    { "id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e3", "name": "april-annex.pdf", "original_name": null }
  ]
}

{
  "error": "Remote fetch failed",
  "detail": "Remote server returned 404",
  "error_code": "VALIDATION_ERROR",
  "retryable": false,
  "request_id": "a1b2c3d4e5f67890abcdef1234567890"
}

Rate limit tier: submission (60 req/min) — see Rate limits. Creates a document packet by having anyformat fetch the bytes server-side — no need to stream documents through your own backend when they already live in object storage you can presign (S3, GCS, R2, …) or at a public HTTPS URL. Provide 1–10 HTTPS URLs. All of them import into a single packet, atomically: the packet is registered only after every fetch succeeded, so any failure imports nothing — no partial packet, no orphan files. Each file is named by its response’s Content-Disposition, else by the URL’s path — see File names. Each fetch is bounded by a 10-second timeout and a 20 MB per-file cap. A failed, non-2xx, or timed-out fetch surfaces as 422 with the distinct failure reasons in detail. URLs resolving to non-globally-routable addresses (loopback, private ranges, link-local, cloud-metadata) are refused before any connection opens. The response is final — the packet is fully imported when you receive 201. If the server-side import takes longer than the gateway’s 6-minute polling ceiling, the request fails with a 504 (retryable: true); it is safe to retry with the same request body. Trigger extraction with POST /v3/document-packets/{document_packet_id}/run/.

Filenames are unique within a workflow, controlled by the on_conflict body field:

error (default) — if a file’s name matches a file already in the workflow, the request fails with 409 once the fetches settle, listing the conflict and its suggested rename.
rename — the file is auto-renamed server-side (april.pdf → april (1).pdf). Each returned name is then the name it was actually stored under, and original_name holds the name it was fetched under.

Attach caller context with the metadata body field. Optional; a JSON object stapled to the packet. Echoed back on GET /v3/document-packets/{document_packet_id}/; a top-level key whose name matches an extract-schema field is surfaced to the LLM and used as the extracted value. See Attaching metadata for the full contract.

File names

A from-url file is named from the response, not from the request. The name matters twice: it carries the extension the import requires (a URL whose path is an opaque key, such as a presigned object GET, has none), and it is the name you and your users see everywhere the file is listed, so a file called by its storage key is a poor experience. Precedence:

The Content-Disposition filename on the response (RFC 6266; filename*=UTF-8''… wins over filename=, and any path is cut to its last segment).
Else the URL path’s last segment: https://example.com/invoices/april.pdf imports as april.pdf.
Else the slot mint’s extension error, as today: the import fails with 422.

The header rather than a request field, because HTTP already names a downloaded file there, every object store signs it into a presigned URL, the API stays URL-only, and the name travels with its URL instead of in a parallel list that must match urls in length and order. On S3, ResponseContentDisposition signs it in:

boto3

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 (response-content-disposition on a V4 signed URL) and Azure (rscd on a SAS) offer the same override. Whichever name applies must end in a supported extension (.pdf, .docx, .png, …): a bare key such as uploads/7c1f3e9a names the file 7c1f3e9a, which has none, and the import fails with 422. The on_conflict policy applies to this name; on a rename, original_name in the response holds it.

curl -X POST 'https://api.anyformat.ai/v3/workflows/0686bb97-8c30-70f0-8000-97669e000eb8/upload/from-url/' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": [
      "https://example.com/invoices/april.pdf",
      "https://example.com/invoices/april-annex.pdf"
    ],
    "metadata": {"customer_reference": "CR-2026-99001-ZTX"}
  }'

import requests

workflow_id = "0686bb97-8c30-70f0-8000-97669e000eb8"
url = f"https://api.anyformat.ai/v3/workflows/{workflow_id}/upload/from-url/"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

body = {
    "urls": [
        "https://example.com/invoices/april.pdf",
        "https://example.com/invoices/april-annex.pdf",
    ]
}

packet = requests.post(url, headers=headers, json=body).json()
print(packet["document_packet_id"])

{
  "document_packet_id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e1",
  "workflow_id": "0686bb97-8c30-70f0-8000-97669e000eb8",
  "files": [
    { "id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e2", "name": "april.pdf", "original_name": null },
    { "id": "069dcc2c-e14c-7606-8000-2ee4fb17b4e3", "name": "april-annex.pdf", "original_name": null }
  ]
}

{
  "error": "Remote fetch failed",
  "detail": "Remote server returned 404",
  "error_code": "VALIDATION_ERROR",
  "retryable": false,
  "request_id": "a1b2c3d4e5f67890abcdef1234567890"
}

Authorizations

Authorization

string

header

required

API key issued from app.anyformat.ai/api-key. Send as Authorization: Bearer <key>.

Path Parameters

workflow_id

string

required

Body

application/json

Body for POST /v3/workflows/{workflow_id}/upload/from-url/.

Every URL imports into a single packet atomically — any fetch or validation failure means nothing is persisted.

urls

string[]

required

HTTPS URLs the backend fetches server-side (1..10). The filename is derived from each URL's path.

Required array length: 1 - 10 elements

Example:

["https://example.com/invoices/april.pdf"]

metadata

Metadata · object | null

Free-form JSON to attach to the packet. No schema is enforced; the extract operator may source datapoints from a top-level key whose name matches a schema field.

on_conflict

enum<string>

default:error

How to handle an uploaded filename that already exists in the workflow (filenames are unique within a workflow). error (the default) rejects the whole request with 409 and lists the conflicting names, so a rename is never silent — the caller must opt in. rename accepts the collision and lets the server auto-rename the file by inserting a (n) counter before the extension (invoice.pdf → invoice (1).pdf).

Available options:

error,

rename

Response

Successful Response

Response for the packet-creating uploads (multipart and from-url).

document_packet_id

string

required

Unique identifier of the newly created document packet (hyphenated UUID).

Example:

"069dcc2c-e14c-7606-8000-2ee4fb17b4e1"

workflow_id

string

required

The workflow the packet was created under (hyphenated UUID).

Example:

"0686bb97-8c30-70f0-8000-97669e000eb8"

files

DocumentPacketCreatedFileV3 · object[]

required

Files in the packet, in the order they were provided.

Show child attributes

Overview

Workflows

Upload

Document packets

Runs

Parse

Knowledge

Evals

SDKs and tools

API v2 (deprecated)

File names

Authorizations

Path Parameters

Body

Response

​File names

Authorizations

Path Parameters

Body

Response

File names