Create Experiment

Create an experiment.

When source_experiment_id is set, duplicates the source experiment (block, name + “(Copy)”, n_consensus, documents) and rejects any other field. Otherwise creates a fresh experiment from the provided fields.

POST /v1/workflows/experiments

Python

from retab import Retab

client = Retab()

experiment = client.workflows.experiments.create(
    workflow_id="wf_abc123",
    block_id="extract-invoice",
    name="Q1 invoices",
    document_captures=[
        {"run_id": "wfrun_1"},
        {"run_id": "wfrun_2", "step_id": "for_each-0"},
    ],
    n_consensus=5,
)
print(experiment.id)

201

{
  "id": "exp_abc",
  "workflow_id": "wf_abc123",
  "block_id": "extract-invoice",
  "block_kind": "extract",
  "n_consensus": 5,
  "document_count": 2,
  "name": "Q1 invoices",
  "last_run_id": null,
  "status": "draft",
  "score": null,
  "is_stale": false,
  "schema_drift": "unknown",
  "schema_drift_detail": null,
  "created_at": "2026-05-01T14:30:00Z",
  "updated_at": "2026-05-01T14:30:00Z"
}

Create a consensus experiment on a supported block (extract, classifier, split, or for_each configured with map_method="split_by_key"). The experiment freezes a name, a fixed document set, and a consensus count — but does NOT run metrics. Trigger the first run with Run Experiment.

The create route is flat: send workflow_id in the request body.

Provide documents through one or both of:

• document_captures — references to past workflow runs. The handle inputs the block actually received are materialized server-side.
• documents — explicit handle inputs you assemble yourself, optionally carrying source metadata.

n_consensus must be 3, 5, or 7. See Experiments for the full conceptual model.

Python

from retab import Retab

client = Retab()

experiment = client.workflows.experiments.create(
    workflow_id="wf_abc123",
    block_id="extract-invoice",
    name="Q1 invoices",
    document_captures=[
        {"run_id": "wfrun_1"},
        {"run_id": "wfrun_2", "step_id": "for_each-0"},
    ],
    n_consensus=5,
)
print(experiment.id)

201

{
  "id": "exp_abc",
  "workflow_id": "wf_abc123",
  "block_id": "extract-invoice",
  "block_kind": "extract",
  "n_consensus": 5,
  "document_count": 2,
  "name": "Q1 invoices",
  "last_run_id": null,
  "status": "draft",
  "score": null,
  "is_stale": false,
  "schema_drift": "unknown",
  "schema_drift_detail": null,
  "created_at": "2026-05-01T14:30:00Z",
  "updated_at": "2026-05-01T14:30:00Z"
}

Authorizations

Api-Key · string · header · required

Body

application/json

Create an experiment, in one of two modes.

• Create from scratch — provide block_id, name, optional document_captures/documents/n_consensus. Leave source_experiment_id unset.
• Duplicate an existing experiment — provide only source_experiment_id. The source's block, name (with a (Copy) suffix), n_consensus, and documents are copied. All other fields must be omitted.

Combining source_experiment_id with any other field is rejected.

workflow_id · string · required

block_id · string | null

document_captures · ExperimentDocumentCaptureRequest · object[] | null

Show child attributes

documents · ExplicitExperimentDocumentRequest · object[] | null

Show child attributes

n_consensus · enum<integer> | null

Available options: 3, 5, 7

name · string | null

source_experiment_id · string | null

Response

201

application/json

Successful Response

An experiment that evaluates a workflow block against a set of documents, with its latest run status and score.

id · string · required

workflow_id · string · required

block_id · string · required

n_consensus · enum<integer> · required

Available options: 3, 5, 7

name · string · required

block_type · enum<string> · required

Available options: extract, classifier, split, for_each

document_count · integer · default: 0

last_run_id · string | null

created_at · string<date-time>

When the experiment was created

updated_at · string<date-time>

When the experiment was last updated

status · enum<string> · default: draft

Available options: draft, processing, completed, failed, cancelled

score · number | null

is_stale · boolean · default: false

freshness · ArtifactFreshness · object

Show child attributes

schema_drift · enum<string> · default: unknown

Available options: none, partial, drifted, unknown

schema_drift_detail · string | null

drift · ArtifactDrift · object

Show child attributes