Upload File

Start a file upload.

Reserves a file record for the given filename, content_type, and size_bytes, and returns a short-lived signed upload_url the client uses to PUT the file content directly. Call the complete-upload endpoint with the returned file_id once the bytes have been uploaded.

POST /v1/files/upload

Python

from retab import Retab
from pathlib import Path

client = Retab()

# Create an upload session for a local file.
invoice_path = Path("invoice.pdf")
session = client.files.create_upload(
    filename=invoice_path.name,
    size_bytes=invoice_path.stat().st_size,
    content_type="application/pdf",
)
mime_data = session.mime_data
print(f"Filename: {mime_data.filename}")
print(f"URL: {mime_data.url}")

200

{
  "fileId": "file_a1b2c3d4e5f6",
  "uploadUrl": "https://storage.googleapis.com/...",
  "uploadMethod": "PUT",
  "uploadHeaders": {
    "Content-Type": "application/pdf"
  },
  "mimeData": {
    "filename": "invoice.pdf",
    "url": "https://storage.retab.com/file_a1b2c3d4e5f6"
  },
  "expiresAt": "2026-04-24T12:00:00Z"
}

Create a direct-to-storage upload session. Upload the file bytes to the returned signed uploadUrl, then call POST /v1/files/upload/{file_id}/complete. The completed file is returned as MIMEData and can be passed directly to extractions, workflows, and other operations.

Python

from retab import Retab
from pathlib import Path

client = Retab()

# Create an upload session for a local file.
invoice_path = Path("invoice.pdf")
session = client.files.create_upload(
    filename=invoice_path.name,
    size_bytes=invoice_path.stat().st_size,
    content_type="application/pdf",
)
mime_data = session.mime_data
print(f"Filename: {mime_data.filename}")
print(f"URL: {mime_data.url}")

200

{
  "fileId": "file_a1b2c3d4e5f6",
  "uploadUrl": "https://storage.googleapis.com/...",
  "uploadMethod": "PUT",
  "uploadHeaders": {
    "Content-Type": "application/pdf"
  },
  "mimeData": {
    "filename": "invoice.pdf",
    "url": "https://storage.retab.com/file_a1b2c3d4e5f6"
  },
  "expiresAt": "2026-04-24T12:00:00Z"
}

Use the uploaded file in later requests

For large documents, prefer an object-storage URL first. Retab fetches the file server-side, avoiding inline/base64 request bodies that can trigger 413 Request Entity Too Large. Use a time-limited signed URL when the object is private.

Supported remote URL hosts include Azure Blob Storage (*.blob.core.windows.net), Google Cloud Storage (storage.googleapis.com), Amazon S3 (amazonaws.com), and Cloudflare R2 (*.r2.cloudflarestorage.com and *.r2.dev). Custom domains are not fetched by default; contact support if you need one allowlisted.

If you do not have an object-storage URL available, upload the file to Retab first. The SDK returns a durable MIMEData reference. You can pass that object directly, or pass its Retab storage URL.

Python

from retab import Retab

client = Retab(api_key="YOUR_RETAB_API_KEY")

schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "total_amount": {"type": "number"},
    },
}

# Option 1: object-storage URL
azure_blob_url = "https://<account>.blob.core.windows.net/<container>/large_document.pdf?<sas_token>"

extraction = client.extractions.create(
    document=azure_blob_url,
    model="retab-small",
    json_schema=schema,
)

# Option 2: Retab upload session, then reuse the returned URL
session = client.files.create_upload(
    filename="large_document.pdf",
    size_bytes=12345,
    content_type="application/pdf",
)
mime_ref = session.mime_data

extraction = client.extractions.create(
    document=mime_ref.url,
    model="retab-small",
    json_schema=schema,
)

# This also works:
extraction = client.extractions.create(
    document=mime_ref,
    model="retab-small",
    json_schema=schema,
)

Signed object-storage URLs are bearer URLs controlled by you; keep them time-limited and scoped to the single document being processed. https://storage.retab.com/file_... URLs are opaque Retab references, not public download links. Retab resolves them against the authenticated caller’s organization before processing.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Body to start a file upload: the filename, expected size_bytes, and optional content type and checksum.

filename · string · required

Filename to store

Minimum string length: 1

size_bytes · integer · required

Expected upload size in bytes

Required range: x >= 0

content_type · string | null

MIME type the client will upload

sha256 · string | null

Optional SHA-256 checksum

Pattern: ^[a-fA-F0-9]{64}$

Response

200

application/json

Successful Response

Instructions for uploading file content to a reserved file record.

Returned when starting a file upload. Carries the new file_id, a short-lived signed upload_url with the HTTP method and headers to use, a durable reference to the file, and the URL's expires_at time.

fileId · string · required

Underlying file ID

uploadUrl · string · required

Short-lived signed upload URL

expiresAt · string<date-time> · required

Upload URL expiration

uploadMethod · string · default: PUT

HTTP method for upload

uploadHeaders · Uploadheaders · object

Headers required by the signed upload URL

Show child attributes

mimeData · MIMEData · object

Durable Retab MIMEData reference

Show child attributes