v3
latestOpenAPI 3.1.02026-07-311,4541,5202.3 MBCreate Experiment
Create an experiment. Two equally-supported modes, distinguished by the payload shape:
-
Draft mode — client sends just name (plus optional description). Row lands in status=draft and stays there until the client fills in the rest via PATCH and triggers execution via POST /api/v2/experiments/{id}/runs/.
-
Create-and-run mode — client sends dataset + a non-empty workflow (plus evaluators, config, etc.). After the row is created we dispatch the Celery workflow task directly, matching the pattern in dataset/views.py::DatasetsView.post(). Dispatch failures leave the row with status=failed (via dispatch_experiment_run), so the client can re-run in place; the failure is also reflected in the HTTP response.
Body mutations inline per convention (no helper methods):
- created_by injected from request.user. Organization fields are injected automatically by SuperAdminMixin.post() via inject_target_organization.
- Alias/default transforms (experiment_id → id, dataset_id → dataset, default id + name) live in ExperimentV2CreateSerializer per serializer conventions.
Headers
Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.