Skip to main content
Every Retab endpoint is available through a typed client library. The SDKs are open-source under retab-dev/retab.

​
Install

pip install retab

​
Authenticate

Each SDK reads RETAB_API_KEY from the environment by default. Get a key from the dashboard settings. Use RETAB_API_KEY=rt_test_... for development and CI, and RETAB_API_KEY=rt_live_... for production. The key prefix selects the customer environment — RETAB_BASE_URL is the Retab deployment URL, not the environment selector. Legacy sk_retab_... keys still work and resolve to production. 
# Development / CI
export RETAB_API_KEY=rt_test_…

# Production
export RETAB_API_KEY=rt_live_…

from retab import Retab

client = Retab() # uses RETAB_API_KEY
For a worked end-to-end extraction, see the quickstart in the introduction. Full method signatures live under API Reference.

​
Workflow Graph Resources

Blocks and edges are flat workflow resources keyed by workflow_id. SDK calls take the workflow id explicitly instead of nesting graph resources under a /workflows/{workflow_id}/... path. When creating or updating workflow blocks with a json_schema config, the public API treats the schema structurally. JSON object property order is not preserved as authored display order; the dashboard may preserve authored order through internal editor state. 
block = client.workflows.blocks.create(
    workflow_id="wf_abc123",
    id="blk_extract_1",
    type="extract",
    label="Extract invoice",
    config={
        "model": "retab-small",
        "json_schema": {
            "type": "object",
            "properties": {"invoice_number": {"type": "string"}},
            "required": ["invoice_number"],
        },
    },
)

edge = client.workflows.edges.create(
    workflow_id="wf_abc123",
    id="edge_start_extract",
    source_block="start",
    target_block=block.id,
)

​
Workflow Reviews

Reviews use immutable versions. To submit a corrected output, create a new version under client.workflows.reviews.versions and pass the reviewed parent_id/parentVersionId; SDK-created versions are always corrections of an existing version. 
review = client.workflows.reviews.get("rev_abc123")
versions = client.workflows.reviews.versions.list(review_id=review.id)

corrected = client.workflows.reviews.versions.create(
    review_id=review.id,
    parent_id=versions.data[0].id,
    snapshot={"invoice_number": "INV-1001", "total": 1200},
    note="fixed total",
)

decision = client.workflows.reviews.approve(
    review.id,
    version_id=corrected.id,
)

​
Workflow Eval and Experiment Runs

Workflow runs, workflow-eval runs, and experiment runs all use the same run-id-first pattern in the SDKs: create a run from the parent resource, poll the run by its id, then inspect child records under that run. 
eval_run = client.workflows.evals.runs.create(
    workflow_id="wf_abc123",
    eval_id="eval_abc",
)
eval_run = client.workflows.evals.runs.get(eval_run.id)
eval_results = client.workflows.evals.runs.results.list(eval_run.id)

experiment_run = client.workflows.experiments.runs.create(
workflow_id="wf_abc123",
experiment_id="exp_abc",
)
experiment_run = client.workflows.experiments.runs.get(experiment_run.id)
experiment_results = client.workflows.experiments.runs.results.list(experiment_run.id)
metrics = client.workflows.experiments.runs.metrics.get(
experiment_run.id,
view="summary",
)
These surfaces do not expose public job_id or batch_id handles. Use the returned run id for polling, cancellation, results, and experiment metrics.