---
title: "Replace a draft study"
method: PUT
path: "/v1/studies/{id}"
tags: ["Studies"]
---

# Replace a draft study

`PUT /v1/studies/{id}`

Replace the full configuration of an existing draft study. The same `launch` flag accepted by POST /v1/studies controls whether this also enqueues the background job: launch=false keeps the study as a draft, launch=true flips it to running and starts execution. Returns 409 if the study has already been launched (status != 'draft'), or if `expected_version` is provided and another save has bumped the draft's version since it was read.

## Path parameters

- `id` string, required

## Request body

- CreateStudyRequest
  - `added_captions` TextCaptionItem[], required
    - `caption` string
    - `content` string
    - `is_sequential` boolean
    - `name` string, required
  - `age_parameters` AgeParametersItem, required
    - `max_age` integer, required
    - `mean` number, nullable
    - `min_age` integer, required
    - `st_dev` number, nullable
    - `venue` string, nullable
  - `assigned_materials` AssignedMaterialsItem[], required
    - `materials_name` string, required
    - `stimuli` StimulusItem[], required
      - `caption` string
      - `materials_name` string, nullable
      - `media` union[], required — Text stimulus, a URL string, or an object with url/type/name
        - union
          - string
          - MediaItem — Media item that can be either a URL string or an object with url/type/name.
            - `name` string
            - `type` string
            - `url` string, required
      - `stimulus_name` string, required
      - `stimulus_type` 'text' | 'image' | 'video' | 'audio' | 'pdf', required
  - `expected_version` integer, nullable
  - `generate_life_stories` boolean
  - `launch` boolean
  - `number_participants` integer, required
  - `persona_context` string
  - `question_groups` QuestionItem[], required
    - `allowMultiple` boolean — Only applies when scale is 'multiple_choice'. When false (default), each persona selects exactly one option and the response is a single string. When true, each persona may select one or more options and the response is a JSON array of strings.
    - `choice_matrix_rows` string[], nullable — Row labels for question_subtype 'choice_matrix'. Each row receives exactly one choice.
    - `choices` string[], nullable — Required when scale is 'multiple_choice' or 'allocation' (party names, minimum 2 required). The list of answer options.
    - `name` string, required
    - `question_subtype` string, nullable — Optional subtype for question variants. Use 'choice_matrix' with scale 'multiple_choice' to ask one single-select choice per row.
    - `questions` string[], required
    - `scale` string, required — The response scale type. Either a point scale (2 - 100 points) in the format: '<N> point scale (1 = <low label>; <N> = <high label>)', or amount scale in the format: 'amount scale (<$ or £ or ¥><min amount> - <$ or £ or ¥><max amount>)', or one of the keywords: 'qualitative', 'multiple_choice', 'allocation'.
    - `sequenceOpenTextMode` 'per_stimulus' | 'overall', nullable — Only applies to qualitative questions in sequence studies. 'per_stimulus' asks once for each sequence item; 'overall' asks one overall open-ended question.
  - `research_goal` string
  - `segments` SegmentItem[], required
    - `name` string, required
    - `subcategories` SegmentSubCategoryItem[], required
      - `name` string, required
      - `percentage` integer, required
  - `title` string, required
  - `uploaded_audios` UploadedMediaItem[], required
    - `caption` string
    - `is_sequential` boolean
    - `name` string, required
    - `page_count` integer, nullable
    - `size_bytes` integer, nullable
    - `text_tokens` integer, nullable
    - `url` string, required
  - `uploaded_images` UploadedMediaItem[], required
    - `caption` string
    - `is_sequential` boolean
    - `name` string, required
    - `page_count` integer, nullable
    - `size_bytes` integer, nullable
    - `text_tokens` integer, nullable
    - `url` string, required
  - `uploaded_pdfs` UploadedMediaItem[], required
    - `caption` string
    - `is_sequential` boolean
    - `name` string, required
    - `page_count` integer, nullable
    - `size_bytes` integer, nullable
    - `text_tokens` integer, nullable
    - `url` string, required
  - `uploaded_videos` UploadedMediaItem[], required
    - `caption` string
    - `is_sequential` boolean
    - `name` string, required
    - `page_count` integer, nullable
    - `size_bytes` integer, nullable
    - `text_tokens` integer, nullable
    - `url` string, required

## Response `200`

OK

- CreateStudyResponse
  - `job_id` string, nullable
  - `study_id` string, required
  - `version` integer, nullable

## Other responses

- `400` — Validation error
- `401` — Authentication failed
- `402` — Entitlement limit exceeded
- `403` — Not authorized
- `404` — Study not found
- `409` — Study is not a draft

---

[API](https://skmtc.dev/viewpoints/apis/viewpoints-study-api.md) · [All operations](https://skmtc.dev/viewpoints/apis/viewpoints-study-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/viewpoints/viewpoints-study-api/revisions/0145b20e3bb0/schema)