Skip to main content
POST
/
v1
/
files
/
upload
from retab import Retab
from pathlib import Path

client = Retab()

# Upload from a file path
mime_data = client.files.upload(Path("invoice.pdf"))
print(f"Filename: {mime_data.filename}")
print(f"URL: {mime_data.url}")

{
  "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"
}

Documentation Index

Fetch the complete documentation index at: https://docs.retab.com/llms.txt

Use this file to discover all available pages before exploring further.

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. 
from retab import Retab
from pathlib import Path

client = Retab()

# Upload from a file path
mime_data = client.files.upload(Path("invoice.pdf"))
print(f"Filename: {mime_data.filename}")
print(f"URL: {mime_data.url}")

{
  "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"
}

​
Request Parameters

​
filename
string
required
The filename including extension (e.g., "invoice.pdf").
​
content_type
string
MIME type for the object upload. If omitted, Retab guesses from filename.
​
size_bytes
integer
required
Expected file size in bytes. The complete step verifies that storage received this exact size.
​
sha256
string
Optional SHA-256 checksum. If provided, the complete step must include the same checksum.

​
Response Fields

​
fileId
string
Unique identifier for the uploaded file, prefixed with file_.
​
uploadUrl
string
Short-lived signed URL for uploading file bytes.
​
uploadMethod
string
HTTP method to use for the signed upload. Currently "PUT".
​
uploadHeaders
object
Headers that must be sent with the signed upload.
​
mimeData
object
Durable MIMEData reference for the uploaded file. Its url is an opaque Retab storage URL and is only usable through Retab APIs.
​
expiresAt
string
Expiration timestamp for the signed upload URL.

​
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. 
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, then reuse the returned URL
mime_ref = client.files.upload("large_document.pdf")

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

​
Api-Key
string
header
required

Query Parameters

​
access_token
string | null

Body

application/json
​
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

Successful Response

​
fileId
string
required

Underlying file ID

​
uploadUrl
string
required

Short-lived signed upload URL

​
mimeData
MIMEData · object
required

Durable Retab MIMEData reference

​
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