> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userintuition.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Study lifecycle

> Pause, resume, or stop a study before editing an active panel.

Panel studies that are currently fielding must be paused or stopped before you
edit them with `PATCH /studies/{study_id}`. Only supplied fields change.

## Draft and provisioned states

Creating a study does not require every launch setting. A partial study is returned with `provisioning_status: "draft"` and a `missing_requirements` array. Study names may contain at most 40 characters.

Once the name, study plan, voice, and language are present, saving the study automatically provisions its interviewer. A successful response then returns `provisioning_status: "provisioned"`. Do not create participants or launch panel recruitment before that state.

`POST /studies/create-with-participants` requires those four settings in the study body. It validates the complete request before creating the study or invitations.

If a complete study returns `provisioning_status: "ready"`, it is configured but not yet provisioned. Retry a `PATCH` with its current complete settings. Launch endpoints return `409 Conflict` with `code: "study_not_provisioned"` until provisioning succeeds.

## Concept images

Concept images can be attached in a Customize Plan turn or uploaded separately to an accessible study. Use `POST /api/public/v1/studies/{study_id}/concept-images` with a multipart `file` and participant-facing `label`, or `POST /api/public/v1/studies/{study_id}/concept-images/from-url` with JSON `{ "url": "https://…", "label": "Concept A" }`. Supported file types are PNG, JPEG, GIF, and WebP, up to 10 MB. The URL variant rejects private-network targets and checks every redirect. Either endpoint accepts `Idempotency-Key` for safe retries.

Images are stored privately. A study read returns a first-party image URL that expires after one hour. Fetch the study again when a URL expires; do not save the URL as a permanent asset identifier. The image `id` remains stable for referring to an attachment. Uploading an image stores it on the study; send its image ID in the research brief if the planning conversation should include it in the Learning Plan.

Removing an image or deleting its study revokes existing image links. Deleting a study also removes its uploaded concept images from storage.

## Recruitment status

`fielding_status` describes recruitment separately from `provisioning_status`, which only describes interviewer readiness. Do not infer recruitment progress from provisioning or interview counts.

`recruiting_method` is `panel`, `byop`, or `synthetic_respondents`. Feasibility requests use lowercase `status`: `received` or `responded`. These values are declared in the response schemas.

Panel-country language options and panel launch responses use lowercase language codes such as `en` and `es`. The country codes remain uppercase. The `language` query filter accepts either case. The interview-language catalog also includes `auto` for automatic detection.

| Value | Meaning |
| - | - |
| `not_started` | A Panel study has not begun recruitment, or a BYOP study is not yet provisioned. |
| `collecting` | A provisioned BYOP study accepts interviews through its participant links. |
| `starting` | Panel recruitment is launching or queued. |
| `fielding` | Panel recruitment is active. |
| `paused` | Panel recruitment or BYOP collection is paused. |
| `complete` | Panel recruitment completed its target. |
| `partial` | Panel recruitment ended with a partial result. |
| `failed` | Panel recruitment failed. |
| `stopped` | Panel recruitment or BYOP collection was stopped or cancelled. |
| `not_applicable` | Synthetic respondents do not use recruitment fielding. |
| `unknown` | The backend has a newer or unrecognized Panel state. |

## Pause a study

```http theme={null}
POST /api/public/v1/studies/{study_id}/pause
```

Pausing temporarily stops new responses. For panel studies, the existing
panel, recruitment progress, target cycle, and reward authorization
hold are preserved. Resume the study to continue the same panel.

## Resume a study

```http theme={null}
POST /api/public/v1/studies/{study_id}/resume
```

Resuming returns the preserved panel survey to fielding. It does not create a
replacement panel or a second reward hold.

## Stop a study

```http theme={null}
POST /api/public/v1/studies/{study_id}/stop
```

Stopping ends active or paused panel recruitment, closes the panel's target
cycle, and settles the reward hold. Any unused authorization is released.
Stopping is the appropriate choice when you do not intend to continue the
current panel.

## Editing an active panel

An edit request for a fielding panel returns `409 Conflict`:

```json theme={null}
{
  "detail": {
    "code": "active_panel_must_be_paused_or_stopped",
    "message": "This panel study is currently fielding. Pause or stop the study before editing it. Pausing preserves the panel hold; stopping settles and releases it.",
    "actions": {
      "pause": {
        "method": "POST",
        "endpoint": "/api/public/v1/studies/study_123/pause",
        "documentation_url": "https://docs.userintuition.ai/api-reference/study-lifecycle#pause-a-study"
      },
      "stop": {
        "method": "POST",
        "endpoint": "/api/public/v1/studies/study_123/stop",
        "documentation_url": "https://docs.userintuition.ai/api-reference/study-lifecycle#stop-a-study"
      }
    }
  }
}
```

After either action succeeds, retry the original edit request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.