Python SDK

Use the Python SDK when your scripts, services, notebooks, or automation jobs need typed access to Iteration Layer APIs without hand-writing HTTP requests, authorization headers, or base64 conversion for binary fields.

Key Features

• Full API Coverage — Call document extraction, document to markdown, website extraction, image transformation, image generation, document generation, and sheet generation from one client.
• Typed Request Shapes — Request parameters are typed with TypedDict definitions, so editors can surface expected fields.
• Native Binary Inputs — Pass inline file content as bytes; the SDK serializes it to the API wire format.
• Native Binary Outputs — Receive generated documents, images, and sheets as bytes plus mime_type.
• Async Variants — Every long-running API has an async method that accepts webhook_url and returns immediately after the job is accepted.
• Structured API Errors — Failed API responses raise IterationLayerError with status_code and error_message.

Installation

Install the SDK from PyPI in the Python environment that sends API requests to Iteration Layer.

pip install iterationlayer

Client Setup

Create one client with your API key. The SDK sends requests to https://api.iterationlayer.com and adds the required bearer token automatically.

from iterationlayer import IterationLayer

client = IterationLayer(api_key="YOUR_API_KEY")

First Request

The SDK request shape matches the HTTP API shape, with native Python byte types for binary fields. This example extracts the vendor name and invoice total from a remote PDF.

result = client.extract_document(
    files=[
        {
            "type": "url",
            "name": "invoice.pdf",
            "url": "https://example.com/invoice.pdf",
        }
    ],
    schema={
        "fields": [
            {
                "type": "TEXT",
                "name": "vendor",
                "description": "Vendor name",
            },
            {
                "type": "CURRENCY_AMOUNT",
                "name": "total",
                "description": "Total amount",
            },
        ],
    },
)

API Methods

Each API has a sync method and an async method. Async methods append _async, require webhook_url, and return an acceptance result instead of the final payload.

Binary Files

Inline file inputs use bytes in Python. Binary API outputs return {"buffer": bytes, "mime_type": str}, so application code can write the buffer directly to storage, an HTTP response, or another processing step.

Error Handling

API validation errors, authentication failures, rate limits, and server errors raise IterationLayerError. Network-level failures from httpx are not wrapped.

from iterationlayer import IterationLayer, IterationLayerError

client = IterationLayer(api_key="YOUR_API_KEY")

try:
    result = client.extract_document(files=[...], schema={...})
except IterationLayerError as error:
    print(error.status_code)
    print(error.error_message)

Async Webhooks

Use async methods when processing should continue after your application request has returned. Iteration Layer validates and accepts the job, then sends the final result to your webhook endpoint.

result = client.extract_document_async(
    files=[
        {
            "type": "url",
            "name": "doc.pdf",
            "url": "https://example.com/doc.pdf",
        }
    ],
    schema={
        "fields": [
            {
                "type": "TEXT",
                "name": "title",
                "description": "Document title",
            }
        ]
    },
    webhook_url="https://your-app.com/webhooks/extraction",
)

Links

• PyPI package
• GitHub repository
• SDK overview