---
title: "Create experiment"
method: POST
path: "/experiments"
tags: ["experiments"]
---

# Create experiment

`POST /experiments`

Create a new experiment with specified configuration.

Supports two modes:

**1. Simple creation:** Provide `name` (required), `description`, `stages`, `prolificConfig`.
This is the easiest way to create a basic experiment.

**2. Full template creation:** Provide a complete `template` object (ExperimentTemplate).
This creates the experiment with all stages and agents, using the same logic as the UI.
Other fields are ignored when template is provided.

## Request body

- object
  - `name` string — (Simple creation) Experiment name - required unless template provided
  - `description` string — (Simple creation) Experiment description
  - `prolificRedirectCode` string — (Simple creation) Prolific completion redirect code
  - `stages` Stage[] — (Simple creation) Array of stage configurations — unresolved $ref
  - `agentMediators` object[] — (Simple creation) Array of agent mediator templates. Each agent includes persona config and a promptMap with stage-specific prompts.
  - `agentParticipants` object[] — (Simple creation) Array of agent participant templates. Each agent includes persona config and a promptMap with stage-specific prompts.
  - `template` object — (Full template creation) Complete ExperimentTemplate object. When provided, creates experiment with all stages and agents. All other fields are ignored.

## Response `201`

Experiment created successfully

- object
  - `experiment` Experiment
    - `id` string — Unique experiment identifier
    - `versionId` integer — Experiment version ID for backwards compatibility
    - `metadata` Metadata — Experiment metadata
      - `name` string — Experiment name
      - `publicName` string — Public-facing experiment name
      - `description` string — Experiment description
      - `tags` string[] — Tags for categorization
      - `creator` string — Experimenter ID who created the experiment
      - `starred` object — Maps experimenter IDs to starred status
      - `dateCreated` object — Firestore timestamp
      - `dateModified` object — Firestore timestamp
    - `permissions` object — Experiment permissions
      - `visibility` 'public' | 'private' — Experiment visibility
      - `readers` string[] — List of experimenter IDs with read access
    - `stageIds` string[] — Ordered list of stage IDs (stages are stored in a subcollection, not returned in this response)
    - `defaultCohortConfig` object — Default cohort configuration
    - `prolificConfig` object — Prolific integration configuration
    - `cohortLockMap` object — Maps cohort ID to lock status

## Other responses

- `400` — Bad request - Invalid input
- `401` — Unauthorized - Missing or invalid API key
- `403` — Forbidden - Insufficient permissions or browser access attempted
- `429` — Too many requests - Rate limit exceeded

## Changes

- **2025-12-11** `3945ef23b2b4` — 4 info
  - added the new optional request property `agentMediators`
  - added the new optional request property `agentParticipants`
  - added the new optional request property `template`
  - the request property `name` became optional
- **2025-12-11** `de23cf298268` — 8 warning, 1 info
  - removed the optional property `cohortLockMap` from the response with the `201` status
  - removed the optional property `defaultCohortConfig` from the response with the `201` status
  - removed the optional property `id` from the response with the `201` status
  - removed the optional property `metadata` from the response with the `201` status
  - …5 more
- **2025-12-10** `427ac306a646` — 1 breaking, 4 warning, 8 info
  - the request property `name` became required
  - removed the request property `agentMediators`
  - removed the request property `agentParticipants`
  - removed the request property `template`
  - …9 more

[Change history](https://skmtc.dev/pair-code/apis/deliberate-lab-api/changes/experiments/post.md)

---

[API](https://skmtc.dev/pair-code/apis/deliberate-lab-api.md) · [All operations](https://skmtc.dev/pair-code/apis/deliberate-lab-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pair-code/deliberate-lab-api/revisions/f58e6c25e4f8/schema)