openapi: 3.1.0
info:
  title: API Reference
  version: 1.0.0
paths:
  /api/v1/users/me/:
    get:
      operationId: get-user
      summary: Retrieve a user
      description: |-
        Use this endpoint to test your token and retrieve the basic information of your account.

        Add an `Authorization` header with the value `Token <your token>`.
      tags:
        - users
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/researchers/participants/:
    post:
      operationId: create-test-participant-for-researcher
      summary: Create a test participant for a researcher
      description: |
        ### Overview
        Creates a test participant with the same details as the researcher and the supplied email. This participant will
        bypass any fraud checks and on-boarding steps.

        ### Enabling the feature
        This endpoint is only enabled for select workspaces and will need enabling before the endpoint can be used.

        ### Participant Limitations
        - The participant will be limited to take studies only in the workspaces associated to the researcher and where
        the feature is enabled.
        - The participant will not be able to cashout any balance earned from completing studies.

        ### Usage
        - The API response contains the participant ID. This can be used in a custom allowlist or participant group to
        target the participant on studies. This enables the researcher to test the study set up end-to-end.
        - A randomly generated password is assigned to the participant account. We recommend that you request to reset
        the password, and use this new password to login to the participant account.
      tags:
        - users
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTestParticipantForResearcherResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTestParticipantForResearcher'
  /api/v1/data-collection/batches:
    get:
      operationId: get-task-builder-batches
      summary: List Batches
      description: Get all AI Task Builder batches by workspace id
      tags:
        - aiTaskBuilder
      parameters:
        - name: workspace_id
          in: query
          description: The unique identifier of the workspace
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AI Task Builder_GetTaskBuilderBatches_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: create-task-builder-batch
      summary: Create a Batch
      description: >-
        Create a new AI Task Builder batch. The dataset does not need to be in READY status at creation time.


        ### Configurable task layouts via `batch_items`


        You can configure a custom task layout using `batch_items` which also stores instructions and content as part of
        batch creation. It replaces the deprecated `POST /api/v1/data-collection/batches/{batch_id}/instructions`
        endpoint, which will reject requests on batches that were created with `batch_items`.


        `batch_items` is a nested layout describing what is shown to participants:


        - `batch_items` is an ordered array of **pages**. Each page is shown to participants as a single screen.

        - Each page has an ordered array of **rows**.

        - Each row has 1 or 2 **columns** rendered side-by-side.

        - Each column has one or more **items** — a dataset field reference, a content block (`image`, `rich_text`), or
        an instruction (`free_text`, `free_text_with_unit`, `multiple_choice`, `multiple_choice_with_free_text`,
        `file_upload`).


        Items are a discriminated union on `type`. Each `dataset_field` item references a field in the attached dataset
        by name — only fields with type `text` or `image_url` are permitted, and the same field may not be referenced
        more than once on the same page.


        On a successful response, every item in `batch_items` is returned with a server-assigned `id`.


        If `batch_items` fails server-side validation (for example: a `dataset_field` item used when no v4 dataset with
        a populated schema is attached, an unknown `dataset_field`, the same `dataset_field` referenced more than once
        on a page, an `answer_limit` larger than the number of options, or a `default_unit` that does not match the
        supplied `unit_options`), the request fails with **`422 Unprocessable Entity`** and an `INVALID_BATCH_ITEMS`
        payload containing per-item `page` / `row` / `column` / `item` locations. See the `BatchItemsValidationError`
        schema for the full shape.
      tags:
        - aiTaskBuilder
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AITaskBuilderBatchCreate'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Entity — `batch_items` failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchItemsValidationError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the batch
                workspace_id:
                  type: string
                  description: The ID of the Prolific workspace
                dataset_id:
                  type: string
                  format: uuid
                  description: The ID of the dataset to attach (optional at creation time)
                task_details:
                  $ref: >-
                    #/components/schemas/ApiV1DataCollectionBatchesPostRequestBodyContentApplicationJsonSchemaTaskDetails
                  description: Task metadata displayed to participants
                batch_items:
                  type:
                    - array
                    - 'null'
                  items:
                    $ref: '#/components/schemas/BatchItemsPage'
                  description: |-
                    Inline pages of instructions and content shown to participants. Each entry is a page
                    containing rows of columns of items (dataset field references, content blocks, or
                    instructions). When supplied, this is the recommended way to author instructions —
                    the legacy `POST /batches/{batch_id}/instructions` endpoint is rejected for batches
                    created with `batch_items`.
              required:
                - name
                - workspace_id
                - task_details
  /api/v1/data-collection/batches/{batch_id}:
    get:
      operationId: get-task-builder-batch
      summary: Get a Batch
      description: Get a specific AI Task Builder batch by its unique identifier.
      tags:
        - aiTaskBuilder
      parameters:
        - name: batch_id
          in: path
          description: The unique identifier of the AI Task Builder batch
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AITaskBuilderBatch'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: update-task-builder-batch
      summary: Update a Batch
      description: >-
        Update an existing AI Task Builder batch. You can update the name, task details, associated dataset, and/or
        `batch_items`. The dataset does not need to be in READY status for updates.


        When updating `batch_items`, include the `id` of any existing pages, rows, columns, or items you want to
        preserve — items without an `id` are treated as new and assigned one server-side. Omitting an existing `id`
        removes that entry. The same validation rules as on create apply, and validation failures return **`422
        Unprocessable Entity`** with the `BatchItemsValidationError` payload.
      tags:
        - aiTaskBuilder
      parameters:
        - name: batch_id
          in: path
          description: The unique identifier of the batch
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AITaskBuilderBatch'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Entity — `batch_items` failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchItemsValidationError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                task_details:
                  $ref: >-
                    #/components/schemas/ApiV1DataCollectionBatchesBatchIdPatchRequestBodyContentApplicationJsonSchemaTaskDetails
                dataset_id:
                  type: string
                  format: uuid
                batch_items:
                  type:
                    - array
                    - 'null'
                  items:
                    $ref: '#/components/schemas/BatchItemsPage'
                  description: |-
                    Replacement layout for the batch's instructions and content. Include the `id`
                    of any existing pages, rows, columns, or items you want to preserve; omit `id`
                    to add new entries. Items absent from the payload are removed.
                auto_sync_enabled:
                  type: boolean
                  description: |-
                    When `true`, datapoints subsequently appended to the batch's attached dataset
                    (via `POST /datasets/{dataset_id}/datapoints`) automatically trigger a sync that
                    materialises tasks for them — no explicit `POST /batches/{batch_id}/sync` call is
                    needed. When `false`, appended datapoints are only picked up by an explicit
                    sync. If this field is omitted from the PATCH payload, the existing auto-sync
                    setting is left unchanged.
  /api/v1/data-collection/batches/{batch_id}/sync:
    post:
      operationId: sync-task-builder-batch
      summary: Sync a Batch
      description: |-
        Triggers an asynchronous sync job that materialises tasks for any datapoints appended to the
        batch's attached dataset since it was set up (or since the last sync). Returns immediately
        with a `sync_id`; the work is performed by a background worker.

        The batch must be in `READY` status and have an attached dataset. Syncs for the same batch are
        serialised, so a new sync picks up wherever the previous one left off.

        Poll `GET /batches/{batch_id}/syncs/{sync_id}` until the returned job reaches a terminal
        status (`complete` or `failed`).
      tags:
        - aiTaskBuilder
      parameters:
        - name: batch_id
          in: path
          description: The unique identifier of the batch to sync
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '202':
          description: |-
            Sync job accepted and queued. The returned job has status `queued`; poll the sync-status
            endpoint for progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncJob'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/data-collection/batches/{batch_id}/syncs/{sync_id}:
    get:
      operationId: get-batch-sync-status
      summary: Get Batch Sync Status
      description: >-
        Returns the current status of a batch sync job created by `POST /batches/{batch_id}/sync`.


        A sync job transitions through the following statuses:

        - `queued` — sync accepted, awaiting the background worker.

        - `processing` — the worker is materialising tasks.


        **Terminal statuses:**

        - `complete` — the sync finished. `tasks_created`, `datapoints_processed`, `groups_created`, and
        `groups_expanded` are populated.

        - `failed` — the sync failed. `reason` is populated.


        Continue polling while the status is `queued` or `processing`.
      tags:
        - aiTaskBuilder
      parameters:
        - name: batch_id
          in: path
          description: The unique identifier of the batch
          required: true
          schema:
            type: string
            format: uuid
        - name: sync_id
          in: path
          description: The sync job ID returned by `POST /batches/{batch_id}/sync`
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Sync job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncJob'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Sync job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/data-collection/batches/{batch_id}/status:
    get:
      operationId: get-task-builder-batch-status
      summary: Get Batch Status
      description: Get the current status of an AI Task Builder batch.
      tags:
        - aiTaskBuilder
      parameters:
        - name: batch_id
          in: path
          description: The unique identifier of the AI Task Builder batch
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AI Task Builder_GetTaskBuilderBatchStatus_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/data-collection/batches/{batch_id}/setup:
    post:
      operationId: setup-task-builder-batch
      summary: Setup a Batch
      description: >-
        The setup process creates all of the **tasks** within the batch according to your configuration.

        Each datapoint in the dataset is paired with all instructions to create a task. Tasks are then organized into
        task groups.


        **V3 datasets:** The dataset must be in a **READY** status before setup can be initiated.


        **V4 datasets:** The dataset must have at least one import job with status **complete**. V4 datasets do not have
        a `READY` status — readiness is determined per import job via `GET /datasets/{dataset_id}/imports/{import_id}`.


        The dataset can be attached either at batch creation time or via the `dataset_id` parameter in this request.


        Upon successful invocation, the setup process will begin asynchronously, and the batch will be set to a
        **PROCESSING** status.


        To retrieve the status of the setup, call the `GET /api/v1/data-collection/batches/{batch_id}/status` endpoint.

        The setup is complete once the batch status changes to **READY**.
      tags:
        - aiTaskBuilder
      parameters:
        - name: batch_id
          in: path
          description: The unique identifier of the AI Task Builder batch
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AI Task Builder_SetupTaskBuilderBatch_Response_202'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                dataset_id:
                  type: string
                  format: uuid
                  description: >-
                    The ID of the dataset to use for task generation. Optional if a dataset was already attached at
                    batch creation time.
                tasks_per_group:
                  type: integer
                  default: 1
                  description: >-
                    The number of tasks to randomly assign to each task group. Participants complete one task group per
                    submission.

                    If your dataset includes a META_TASK_GROUP_ID column, those groupings take precedence over this
                    parameter.
  /api/v1/data-collection/batches/{batch_id}/responses:
    get:
      operationId: get-task-builder-batch-task-responses
      summary: Get Batch Responses
      description: >-
        Get responses for an AI Task Builder batch as JSON. Returns individual response records for programmatic
        processing.
      tags:
        - aiTaskBuilder
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AI Task Builder_GetTaskBuilderBatchTaskResponses_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/data-collection/batches/{batch_id}/report/:
    get:
      operationId: get-task-builder-batch-report
      summary: Get Batch Report
      description: >-
        Get a presigned URL to download the batch responses as a CSV report. The CSV contains your original dataset with
        additional columns for participant responses.
      tags:
        - aiTaskBuilder
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AI Task Builder_GetTaskBuilderBatchReport_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/data-collection/batches/{batch_id}/duplicate:
    post:
      operationId: duplicate-task-builder-batch
      summary: Duplicate a Batch
      description: >-
        Create a duplicate of an existing AI Task Builder batch. The dataset does not need to be in READY status for
        duplication. Supports two modes:

        - Duplicate with dataset (default): Creates a copy with the same dataset (the dataset is shared between both
        batches, not duplicated)

        - Duplicate without dataset: Creates a copy that requires a new dataset upload (set upload_new_dataset to true)


        You can optionally provide a new name for the duplicated batch. If no name is provided, the duplicate will be
        named "[Original Batch Name] (Copy)".
      tags:
        - aiTaskBuilder
      parameters:
        - name: batch_id
          in: path
          description: The unique identifier of the batch to duplicate
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AITaskBuilderBatchCreate'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Optional name for the duplicated batch. If not provided, a default name will be generated.
                upload_new_dataset:
                  type: boolean
                  default: false
                  description: >-
                    If true, creates the batch without copying the dataset (user must upload a new one). If false or
                    omitted, duplicates with the existing dataset.
  /api/v1/data-collection/batches/{batch_id}/export:
    post:
      operationId: request-batch-export
      summary: Request a Batch Export
      description: >-
        Initiates an asynchronous export of all participant responses and uploaded files for a batch as a ZIP archive.


        The export is generated out-of-band to handle large batches without hitting API timeout limits. The endpoint
        returns immediately with one of two outcomes:


        - **202 Accepted** — a new export job has been enqueued. Use the returned `export_id` to poll `GET
        /batches/{batch_id}/export/{export_id}` for status.

        - **200 OK** — a recent export already exists and is ready to download immediately.


        Subsequent POST requests for the same batch are idempotent while an export is generating or complete; they
        return the existing job ID or download URL rather than re-triggering generation.


        Only researchers with workspace access to the batch can request an export.
      tags:
        - aiTaskBuilder
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Export already complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchExportComplete'
        '403':
          description: Forbidden — user does not have workspace access to this batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/data-collection/batches/{batch_id}/export/{export_id}:
    get:
      operationId: get-batch-export-status
      summary: Get Batch Export Status
      description: >-
        Polls the status of an asynchronous batch export job initiated by `POST /batches/{batch_id}/export`.


        Returns the current status of the export:


        - **generating** — the export is still being built; continue polling.

        - **complete** — the export is ready; a presigned HTTPS download URL is included. URLs are valid for 1 hour and
        are automatically refreshed if expired.

        - **failed** — generation failed (e.g. the archive was deleted from storage). Re-send `POST
        /batches/{batch_id}/export` to retry.
      tags:
        - aiTaskBuilder
      parameters:
        - name: batch_id
          in: path
          required: true
          schema:
            type: string
        - name: export_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Export status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchExportStatus'
        '404':
          description: Export job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/data-collection/datasets:
    post:
      operationId: create-task-builder-dataset
      summary: Create a Dataset
      description: >-
        Create a new AI Task Builder dataset.


        Pass an optional `schema` to create a **V4 dataset** with a structured schema. V4 datasets accept JSONL and CSV
        uploads, track each upload as an import job, and allow `dataset_field` items in `batch_items` to reference named
        schema fields. Without a `schema`, a V3 dataset is created (CSV/ZIP only, legacy flow).


        V4 dataset creation requires the feature to be enabled for the workspace.
      tags:
        - aiTaskBuilder
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AITaskBuilderDataset'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name or identifier of the AI Task Builder dataset.
                workspace_id:
                  type: string
                  description: The ID of the Prolific workspace the dataset will be created in.
                schema:
                  $ref: '#/components/schemas/DatasetSchema'
                  description: Optional schema definition. When provided, a V4 dataset is created. Omit for a V3 dataset.
              required:
                - name
                - workspace_id
  /api/v1/data-collection/datasets/{dataset_id}:
    get:
      operationId: get-task-builder-dataset
      summary: Get a Dataset
      description: >-
        Get a specific AI Task Builder dataset by its unique identifier.


        For **V4 datasets**, the response includes the dataset `schema` (if one has been set) and an `imports` array
        listing all import jobs for this dataset.


        For **V3 datasets**, the response includes `status`, `filename`, and `has_predetermined_grouping_id` instead.
      tags:
        - aiTaskBuilder
      parameters:
        - name: dataset_id
          in: path
          description: The unique identifier of the AI Task Builder dataset
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AITaskBuilderDataset'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Dataset not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: update-task-builder-dataset
      summary: Update a Dataset Schema
      description: >-
        Updates the schema of an existing **V4 dataset**. Each successful update writes a new schema

        version.


        **Schema migration.** If the dataset already had a schema, changing it starts an asynchronous

        **schema migration** that re-normalises the dataset's existing datapoints against the new

        version. In that case the response includes a `migration_job_id`; poll

        `GET /datasets/{dataset_id}/schema-migrations/{job_id}` with it until the job reaches a

        terminal status. When this is the dataset's **first** schema, no migration is needed and

        `migration_job_id` is omitted.


        **Constraints:**

        - V4 datasets only — a `400` is returned for V3 datasets.

        - The `task_group_id` column designation cannot be changed once the dataset has datapoints; attempting to do so
        returns `400`.
      tags:
        - aiTaskBuilder
      parameters:
        - name: dataset_id
          in: path
          description: The unique identifier of the V4 dataset to update
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |-
            Dataset updated. Returns the updated dataset. When the update triggered a schema
            migration, `migration_job_id` is present — poll the schema-migration endpoint with it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AI Task Builder_UpdateTaskBuilderDataset_Response_200'
        '400':
          description: |-
            Bad request — not a V4 dataset, or an attempt to change the `task_group_id` column on a
            dataset that already has datapoints.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — the user does not have access to the dataset's workspace.
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Dataset not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                schema:
                  $ref: '#/components/schemas/DatasetSchema'
                  description: The new schema definition for the dataset.
              required:
                - schema
  /api/v1/data-collection/datasets/{dataset_id}/upload-url/{filename}:
    get:
      operationId: get-dataset-upload-url
      summary: Get Dataset Upload URL
      description: >-
        Generates a presigned S3 URL for uploading a file to the dataset. Use the returned URL to PUT the file directly
        to S3.


        **V3 datasets** (CSV/ZIP): returns `upload_url` and `http_method`. After the upload completes, poll `GET
        /datasets/{dataset_id}/status` for processing status.


        **V4 datasets** (JSONL/CSV): additionally returns `import_id`. After the upload completes, poll `GET
        /datasets/{dataset_id}/imports/{import_id}` for per-upload status. Multiple upload URLs can be requested before
        any upload completes — each creates a distinct import job and S3 key.


        Supported file types:

        - V3: `.csv`, `.zip`

        - V4: `.csv`, `.jsonl`
      tags:
        - aiTaskBuilder
      parameters:
        - name: dataset_id
          in: path
          description: The ID of the dataset to upload files to
          required: true
          schema:
            type: string
        - name: filename
          in: path
          description: The name of the file to upload (e.g. `data.jsonl`)
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Presigned URL generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AI Task Builder_getDatasetUploadUrl_Response_201'
        '400':
          description: Bad request (e.g., unsupported file type for this dataset version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden (e.g., user does not have access to the workspace)
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Dataset not found
          content:
            application/json:
              schema:
                description: Any type
  /api/v1/data-collection/datasets/{dataset_id}/imports/{import_id}:
    get:
      operationId: get-dataset-import-status
      summary: Get Dataset Import Status
      description: >-
        Returns the current status of a V4 dataset import job. Each import job represents one ingestion operation and
        transitions through the following statuses:

        - `uninitialised` — Presigned url requested, but not yet used

        - `processing` — Datapoints received for ingestion, work underway

        - `queued` — Datapoints received for ingestion, awaiting a previous import job to complete before processing can
        commence


        **Terminal statuses:**

        - `complete` — all records were accepted. `accepted_count` is populated.

        - `partial` — some records were accepted and some rejected. `accepted_count`, `rejected_count`, and `errors` are
        populated. The accepted records are available for use.

        - `failed` — extraction failed entirely (e.g. file could not be parsed). `reason` is populated. No records were
        ingested.

        - `pending_schema` — the dataset has no schema set; upload is paused until a schema is defined.


        Continue polling while the status is `uninitialised`, `queued`, or `processing`.
      tags:
        - aiTaskBuilder
      parameters:
        - name: dataset_id
          in: path
          description: The unique identifier of the dataset
          required: true
          schema:
            type: string
            format: uuid
        - name: import_id
          in: path
          description: The import job ID returned by `GET /datasets/{dataset_id}/upload-url/{filename}`
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Import job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetImportJob'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Import job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/data-collection/datasets/{dataset_id}/datapoints:
    post:
      operationId: append-dataset-datapoints
      summary: Append Datapoints to a Dataset
      description: |-
        Synchronously appends one or more JSONL records to an existing **V4 dataset**. Unlike the
        file-upload flow, this endpoint processes the whole payload within the request and returns the
        accepted/rejected counts directly — there is no async import job to poll.

        **Request body:** JSONL — one JSON object per line — sent with a JSONL content type
        (e.g. `application/x-ndjson`). Blank lines are skipped. CSV is not supported on this endpoint.

        Each record is validated against the dataset's current schema. Valid records are persisted as
        datapoints and sort after every existing datapoint. Records that are malformed or violate the
        schema are rejected individually and reported in `errors` — they do not fail the whole request.
        Re-appending an identical record is idempotent (counted as accepted, not written twice).

        **Limits and preconditions:**
        - At most 1000 records per request. Larger imports should use the file-upload flow.
        - The dataset must be V4 and have a schema defined.
        - Rejected with `409 Conflict` while a dataset import or a schema migration is in progress.

        If the dataset is attached to any batches with `auto_sync_enabled`, a sync is triggered
        automatically for the newly written datapoints.
      tags:
        - aiTaskBuilder
      parameters:
        - name: dataset_id
          in: path
          description: The unique identifier of the V4 dataset to append to
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |-
            Append processed. Returns per-request accepted/rejected counts. A `200` is returned even
            when some (or all) records were rejected — inspect `rejected` and `errors`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetAppendResult'
        '400':
          description: |-
            Bad request — missing body, CSV payload, empty JSONL, too many records, a non-V4 dataset,
            or a dataset with no schema.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — the user does not have access to the dataset's workspace.
          content:
            application/json:
              schema:
                description: Any type
        '404':
          description: Dataset not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict — a dataset import or a schema migration is in progress. Retry once it completes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: string
  /api/v1/data-collection/datasets/{dataset_id}/schema-migrations/{job_id}:
    get:
      operationId: get-schema-migration-status
      summary: Get Schema Migration Status
      description: |-
        Returns the current status of a schema migration job, which reprocesses a V4 dataset's
        datapoints against a newer schema version.

        A migration job has these statuses:
        - `processing` — the migration is underway.

        **Terminal statuses:**
        - `complete` — all datapoints were reprocessed. `reprocessed_count` is populated.
        - `partial` — some datapoints were reprocessed and some fields could not be re-normalised (and
          were nulled). `reprocessed_count`, `failed_count`, and `errors` are populated.
        - `failed` — the migration failed entirely. `reason` is populated.

        Continue polling while the status is `processing`.
      tags:
        - aiTaskBuilder
      parameters:
        - name: dataset_id
          in: path
          description: The unique identifier of the dataset
          required: true
          schema:
            type: string
            format: uuid
        - name: job_id
          in: path
          description: The schema migration job ID
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Schema migration job status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaMigrationJob'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Schema migration job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/data-collection/datasets/{dataset_id}/status:
    get:
      operationId: get-task-builder-dataset-status
      summary: Get Dataset Status
      description: Get status for AI Task Builder dataset.
      tags:
        - aiTaskBuilder
      parameters:
        - name: dataset_id
          in: path
          description: The unique identifier of the AI Task Builder dataset
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AI Task Builder_GetTaskBuilderDatasetStatus_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/data-collection/batches/{batch_id}/instructions:
    get:
      operationId: get-task-builder-instructions
      summary: Get Batch Instructions
      description: >-
        Get the instructions for an AI Task Builder batch.


        <Error title="Important">


        **Deprecated.**


        All responses include the [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) headers `Deprecation: true` and
        `Sunset: Tue, 01 Sep 2026 23:59:59 GMT`. Migrate to the `batch_items` flow before the sunset date.


        </Error>
      tags:
        - aiTaskBuilder
      parameters:
        - name: batch_id
          in: path
          description: Batch ID
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AI Task Builder_GetTaskBuilderInstructions_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: create-task-builder-instructions
      summary: Create Batch Instructions
      description: >-
        Create instructions for a Task Builder batch.


        <Error title="Important">


        **Deprecated for batches that use `batch_items`.**


        All responses include the [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) headers `Deprecation: true` and
        `Sunset: Tue, 01 Sep 2026 23:59:59 GMT`.


        If the target batch was created with `batch_items` (the per-item instructions flow), this endpoint will respond
        with **`422 Unprocessable Entity`** and an error message directing you to manage instructions via the
        `batch_items` payload instead.


        Legacy batches (where `batch_items` is `null`) continue to work and return `201 Created`.


        </Error>
      tags:
        - aiTaskBuilder
      parameters:
        - name: batch_id
          in: path
          description: The unique identifier of the AI Task Builder batch
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created. Returned only for legacy batches (`batch_items` is `null`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AITaskBuilderInstruction'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            Returned when the target batch uses `batch_items`. Instructions must be managed via the `batch_items`
            payload instead of this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                instructions:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItems
                  description: The instructions to create for the AI Task Builder batch.
              required:
                - instructions
    put:
      operationId: update-task-builder-instructions
      summary: Update Batch Instructions
      description: >-
        Updates the instructions for a task builder batch. This is a full replacement - all instructions must be
        included in the request.


        Include the `id` field for existing instructions you want to preserve. Instructions without an `id` will be
        created as new.


        <Error title="Important">


        **Deprecated for batches that use `batch_items`.**


        If the target batch was created with `batch_items` (the per-item instructions flow), this endpoint will respond
        with **`422 Unprocessable Entity`** and an error message directing you to manage instructions via the
        `batch_items` payload instead.


        The response will also include the [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) headers `Deprecation:
        true` and `Sunset: Tue, 01 Sep 2026 23:59:59 GMT`. Legacy batches (where `batch_items` is `null`) are unaffected
        and continue to work as before.


        </Error>
      tags:
        - aiTaskBuilder
      parameters:
        - name: batch_id
          in: path
          description: Batch ID
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated. Returned only for legacy batches (`batch_items` is `null`).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AITaskBuilderInstruction'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            Returned when the target batch uses `batch_items`. Instructions must be managed via the `batch_items`
            payload instead of this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                instructions:
                  type: array
                  items:
                    $ref: >-
                      #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItems
                  description: The instructions for the batch.
              required:
                - instructions
  /api/v1/data-collection/collections:
    get:
      operationId: list-collections
      summary: List Collections
      description: Get all AI Task Builder Collections for a workspace.
      tags:
        - aiTaskBuilder
      parameters:
        - name: workspace_id
          in: query
          description: The unique identifier of the workspace
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AI Task Builder_ListCollections_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: create-collection
      summary: Create a Collection
      description: >-
        Create a new AI Task Builder Collection. Collections allow you to define static content and instructions without
        requiring a dataset upload.


        Unlike Batches, Collections do not require a dataset or setup step — they can be published to a study
        immediately after creation.
      tags:
        - aiTaskBuilder
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionCreateRequest'
  /api/v1/data-collection/collections/{collection_id}:
    get:
      operationId: get-collection
      summary: Get a Collection
      description: Get a specific AI Task Builder Collection by its unique identifier.
      tags:
        - aiTaskBuilder
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: update-collection
      summary: Update a Collection
      description: >-
        Update an existing AI Task Builder Collection. This is a full replacement — all fields must be provided.


        To preserve existing entities (collection items, page items) when updating, include their `id` fields in the
        request. Entities without IDs will be created as new, and existing entities not included in the request will be
        deleted.
      tags:
        - aiTaskBuilder
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionUpdateRequest'
  /api/v1/data-collection/collections/{collection_id}/responses:
    get:
      operationId: get-collection-responses
      summary: Get Collection Responses
      description: |-
        Get responses for an AI Task Builder Collection.

        **Note:** This endpoint is coming soon and is not yet available.
      tags:
        - aiTaskBuilder
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AI Task Builder_GetCollectionResponses_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/data-collection/collections/{collection_id}/export:
    post:
      operationId: request-collection-export
      summary: Request a Collection Export
      description: >-
        Initiates an asynchronous export of all participant responses and uploaded files for a collection as a ZIP
        archive.


        The export is generated out-of-band to handle large collections without hitting API timeout limits. The endpoint
        returns immediately with one of two outcomes:


        - **202 Accepted** — a new export job has been enqueued. Use the returned `export_id` to poll `GET
        /collections/{collection_id}/export/{export_id}` for status.

        - **200 OK** — a recent export already exists and is ready to download immediately.


        Subsequent POST requests for the same collection are idempotent while an export is generating or complete; they
        return the existing job ID or download URL rather than re-triggering generation.


        Only researchers with workspace access to the collection can request an export.
      tags:
        - aiTaskBuilder
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Export already complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionExportComplete'
        '403':
          description: Forbidden — user does not have workspace access to this collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/data-collection/collections/{collection_id}/export/{export_id}:
    get:
      operationId: get-collection-export-status
      summary: Get Collection Export Status
      description: >-
        Polls the status of an asynchronous collection export job initiated by `POST
        /collections/{collection_id}/export`.


        Returns the current status of the export:


        - **generating** — the export is still being built; continue polling.

        - **complete** — the export is ready; a presigned HTTPS download URL is included. URLs are valid for 1 hour and
        are automatically refreshed if expired.

        - **failed** — generation failed (e.g. the archive was deleted from storage). Re-send `POST
        /collections/{collection_id}/export` to retry.
      tags:
        - aiTaskBuilder
      parameters:
        - name: collection_id
          in: path
          required: true
          schema:
            type: string
        - name: export_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Export status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionExportStatus'
        '404':
          description: Export job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/studies/:
    get:
      operationId: get-studies
      summary: List all studies
      description: List all studies, with the option to filter by study status.
      tags:
        - studies
      parameters:
        - name: state
          in: query
          description: >-
            Filter studies by status. Accepts a string in the format "(active|published|...)", where "active" and
            "published" are example statuses.
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1StudiesGetParametersState'
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of studies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudiesListResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
    post:
      operationId: create-study
      summary: Create a draft study
      description: >-
        Create a draft study. Publishing a study is a two step process, first create a draft study then publish it.


        ## Taskflow Studies:

        Taskflow studies are created in the same manner as regular studies, however instead of providing an
        **external_study_url**, you should

        provide an access_details array with **access_detail** objects instead, containing an external_url field and a
        total_allocation field.
      tags:
        - studies
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Study'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStudy'
  /api/v1/projects/{project_id}/studies/:
    get:
      operationId: get-project-studies
      summary: List all studies in a project
      description: >-
        List all of your studies in a project.


        For projects with a large number of studies, pagination can be used to optimize the response size and
        performance. To paginate, use the `page`, `page_size` and `ordering` query parameters. For example, to retrieve
        the first 10 studies, use `/api/v1/projects/{project_id}/studies/?page=1&page_size=10&ordering=-date_created`.
      tags:
        - studies
      parameters:
        - name: project_id
          in: path
          description: Project id
          required: true
          schema:
            type: string
        - name: page
          in: query
          description: The page number to retrieve.
          required: false
          schema:
            type: integer
        - name: page_size
          in: query
          description: The number of studies to retrieve per page.
          required: false
          schema:
            type: integer
        - name: ordering
          in: query
          description: The ordering of the studies. Use `-date_created` to order by date created in descending order.
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of studies for the given project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudiesListResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
  /api/v1/projects/{project_id}/studies/{study_id}/:
    delete:
      operationId: delete-project-study
      summary: Delete a study from a project
      description: Delete a study and remove it from a project. Only draft studies can be deleted.
      tags:
        - studies
      parameters:
        - name: project_id
          in: path
          description: Project id
          required: true
          schema:
            type: string
        - name: study_id
          in: path
          description: Study id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
  /api/v1/studies/{id}/:
    get:
      operationId: get-study
      summary: Retrieve a study
      description: >-
        Retrieve a study by id. If you are polling the API for updates to a study, consider using a [Hook](#tag/Hooks).
        We will call your endpoint when certain events occur on your study, such as new completed submissions or changes
        in status.
      tags:
        - studies
      parameters:
        - name: id
          in: path
          description: Study id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Study'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: delete-study
      summary: Delete a study
      description: Published studies cannot be deleted, but you can delete draft studies.
      tags:
        - studies
      parameters:
        - name: id
          in: path
          description: Study id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Studies_DeleteStudy_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: update-study
      summary: Update a study
      description: >-
        You can update any field for a draft study.


        Once the study has been published only the following fields can be updated with some restrictions:

        - internal_name: Internal name of the study, not shown to participants

        - total_available_places: Only increasing is allowed. A completed study will become active again and resume
        recruiting of participants. For more information, check the
        [guide](https://researcher-help.prolific.com/en/articles/445201-how-do-i-increase-places-on-a-study)

        - access_details: Sending an access_detail will add a new task and increase overall study places by the number
        in the total_allocation field. Sending both access_details and total_available_places will increase places on
        existing URLs by the number specified on the access_detail.

        - data_collection_metadata.annotators_per_task: For AI Task Builder Batch studies, you can increase the number
        of annotators per task. This will automatically recalculate `total_available_places` based on the number of task
        groups multiplied by the new value. Note: This value can only be increased, not decreased, on a published study.

        - submissions_config: This allows you to update the max_submissions_per_participant, max_concurrent_submissions,
        or auto_rejection_categories. Please note decreasing max_submissions_per_participant will not affect submissions
        that have already been created.
      tags:
        - studies
      parameters:
        - name: id
          in: path
          description: Study id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Study'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseStudy'
  /api/v1/studies/{id}/transition/:
    post:
      operationId: publish-study
      summary: Transition a study's status
      description: >-
        Transition a study between statuses using one of the available actions.


        The following transitions are available:


        | Current Status | Action | Resulting Status |

        |---|---|---|

        | UNPUBLISHED | PUBLISH | ACTIVE |

        | UNPUBLISHED | SCHEDULE_PUBLISH | SCHEDULED |

        | SCHEDULED | CANCEL_PUBLISH | UNPUBLISHED |

        | ACTIVE | PAUSE | PAUSED |

        | ACTIVE | STOP | COMPLETED |

        | PAUSED | START | ACTIVE |

        | PAUSED | STOP | COMPLETED |


        **Action details:**

        - **PUBLISH**: Publish a draft study so participants can take part. The study must be fully configured.

        - **SCHEDULE_PUBLISH**: Schedule a draft study to be published at a future time. A `publish_at` field (ISO 8601
        datetime) must be set either on the study or provided in this request.

        - **CANCEL_PUBLISH**: Cancel a scheduled publication, returning the study to draft.

        - **PAUSE**: Temporarily pause an active study. Participants already taking part can still complete, but no new
        participants will be recruited.

        - **START**: Resume a paused study.

        - **STOP**: Stop a study completely. To make it active again you will need to increase the number of places.


        To learn more about it check out [help
        center](https://researcher-help.prolific.com/en/articles/445200-pausing-stopping-a-study)
      tags:
        - studies
      parameters:
        - name: id
          in: path
          description: Study id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Study'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StudyTransition'
  /api/v1/studies/{id}/test-study:
    post:
      operationId: create-test-study
      summary: Create a test study
      description: |
        ### Overview
        - Make sure atleast one test participant is created and exists against the user before hitting this endpoint.
          - To create test participant: POST /api/v1/researchers/participants/
        - Create and publish a test study from a draft study to all the test participants associated with the workspace.
        - This will allow a data collector to test the study as a participant.
        ## Prerequisites
        ✅ **Required:**
        - At least one active test participant (created via [`POST /api/v1/researchers/participants/`](#))
        - Study must be in draft status
        - Feature enabled for your workspace (contact support if unavailable)
        ### Enabling the feature
        This endpoint is only enabled for select workspaces and will need enabling before the endpoint can be used.
      tags:
        - studies
      parameters:
        - name: id
          in: path
          description: Study id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestStudySetUpResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/studies/{id}/access-details-progress/:
    get:
      operationId: get-study-access-details-progress
      summary: Get taskflow progress
      description: >-
        Returns per-URL allocation progress for a Taskflow study (studies configured with `access_details`).

        Each item in `progress` corresponds to one `external_url` from the study's access details, including how many
        participants are allocated and any screenout-driven capacity increments.


        Returns **404** if the study has no access-details collection (not a Taskflow study).
      tags:
        - studies
      parameters:
        - name: id
          in: path
          description: Study id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Taskflow progress for the study's access details collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyAccessDetailsProgress'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/studies/{id}/cost/:
    get:
      operationId: get-study-cost
      summary: Show Study cost
      description: >-
        Returns cost information about the study. Default behaviour is to return cost at the time of the request, but
        projected cost can be requested via a query parameter.
      tags:
        - studies
      parameters:
        - name: id
          in: path
          description: Study id
          required: true
          schema:
            type: string
        - name: is_projected
          in: query
          description: Return the projected cost of the study
          required: false
          schema:
            type: boolean
            default: false
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Return the total cost for the study
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyTotalCost'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
  /api/v1/studies/{id}/submissions/:
    get:
      operationId: get-study-submissions
      summary: List study submissions
      description: Returns basic information of the submissions, including the study id, participant id, status and start timestamp
      tags:
        - studies
      parameters:
        - name: id
          in: path
          description: Study id
          required: true
          schema:
            type: string
        - name: ordering
          in: query
          description: >-
            Field to sort results by. Prefix with `-` for descending order. Allowed values: `started_at`,
            `completed_at`, `status`, `ip`, `time_taken`, `participant_id`, `study_code`.
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List submissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionListResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
  /api/v1/studies/{id}/submissions/counts/:
    get:
      operationId: count-study-submissions-by-status
      summary: Count study submissions by status
      description: Returns a count of the number of submissions per submission status in the study.
      tags:
        - studies
      parameters:
        - name: id
          in: path
          description: Study id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Count of number of submissions per submission status for a study
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionsCountResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
  /api/v1/studies/{id}/credentials/report/:
    get:
      operationId: download-study-credential-report
      summary: Download credential usage report
      description: >-
        Download a CSV report of credential usage for a study. The report includes participant IDs, submission IDs,
        usernames, and credential status (USED/UNUSED). This endpoint is only available for studies that have
        credentials configured.
      tags:
        - studies
      parameters:
        - name: id
          in: path
          description: Study id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: CSV file containing credential usage report
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
  /api/v1/studies/{id}/export/:
    get:
      operationId: export-study
      summary: Download demographic data
      description: >-
        <span  style="font-size:x-large">**Deprecated - please use the new [Demographic
        Export](https://docs.prolific.com/docs/api-docs/public/#tag/Studies/operation/ExportDemographicData) endpoint
        instead.**</span>


        <span  style="font-size:x-large">**This endpoint will be sunset after the 14th of April 2026**</span>


        Download a snapshot of the participants' filter responses at the time that they took your study.


        In addition to the responses to all filters applied to the study (subject to change), you'll also have access to
        the following data:


        * Submission id

        * Participant id

        * Submission status

        * Started date-time
          * Expressed in UTC
          * ISO 8601 formatted
        * Completed date-time
          * Expressed in UTC
          * ISO 8601 formatted
        * Time taken (in seconds)

        * Age

        * Sex
          * Participants were asked the following question: What is your sex, as recorded on legal/official documents?
        * Ethnicity (simplified)

        * First language

        * Current country of residence

        * Nationality

        * Country of birth

        * Student status

        * Employment status

        * Reviewed at date-time
          * Expressed in UTC
          * ISO 8601 formatted
        * Completion code ('entered code')

        * Total approvals


        Learn more on [Exporting Prolific demographic data](https://researcher-help.prolific.com/en/article/b2943f).
      tags:
        - studies
      parameters:
        - name: id
          in: path
          description: Study id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Downloaded
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/studies/{id}/demographic-export/:
    post:
      operationId: export-demographic-data
      summary: Export demographic data
      description: >-
        Create and download a demographic export for a study. This endpoint allows you to export participant demographic
        data with optional study filter data.


        **Filter Support**: This endpoint supports applying demographic filters to export data for participants who
        match specific criteria.


        When filters are provided, the export includes both base demographic data (age, sex, country, etc.) and the
        filters.


        When no filters are provided, the export includes only base demographic data for all participants who took the
        study, excluding any study-specific filter responses.


        **Export Usage**: Please note that you may only select up to 15 filters per export. You are also limited to 2
        different filter export requests.


        You may download the same request as many times as you need. To check your current usage and see your latest
        export history, use the [Demographic Export
        History](https://docs.prolific.com/docs/api-docs/public/#tag/Studies/operation/GetDemographicExportHistory)
        endpoint.


        **Basic Data Included**: The export includes the following data fields:

        * Submission ID

        * Participant ID

        * Submission status

        * Started date-time
          * Expressed in UTC
          * ISO 8601 formatted
        * Completed date-time
          * Expressed in UTC
          * ISO 8601 formatted
        * Time taken (in seconds)

        * Age

        * Sex
          * Participants were asked the following question: What is your sex, as recorded on legal/official documents?
        * Ethnicity (simplified)

        * First language

        * Current country of residence

        * Nationality

        * Country of birth

        * Student status

        * Employment status

        * Reviewed at date-time
          * Expressed in UTC
          * ISO 8601 formatted
        * Completion code ('entered code')

        * Total approvals


        Learn more on [Exporting Prolific demographic data](https://researcher-help.prolific.com/en/article/b2943f).
      tags:
        - studies
      parameters:
        - name: id
          in: path
          description: Study ID
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Demographic data exported successfully
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DemographicExportRequest'
  /api/v1/studies/{id}/demographic-export-history/:
    get:
      operationId: get-demographic-export-history
      summary: Get demographic export history
      description: >-
        Retrieve the latest demographic export request history for a study. This endpoint returns information about your
        most recent export request, including the filters used and the total number of export combinations made.


        **Usage**: Use this endpoint to check your current export usage and see what filters were used in your latest
        request. This helps you understand your remaining export quota and track your export history.


        **Export Limits**: You are limited to 2 different filter combinations per study. This endpoint helps you track
        your usage against this limit.


        Learn more on [Exporting Prolific demographic data](https://researcher-help.prolific.com/en/article/b2943f).
      tags:
        - studies
      parameters:
        - name: id
          in: path
          description: Study ID
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Export history retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DemographicExportHistoryResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/studies/{id}/clone/:
    post:
      operationId: duplicate-study
      summary: Duplicate a study
      description: >-
        Duplicating a study can save a lot of time and effort compared to creating a new study from scratch, since all
        of the information and data from the original study will be carried over to the new study. Additionally,
        duplicating a study can help ensure that the new study is set up consistently with the original, reducing the
        risk of errors or inconsistencies.


        To prevent repeat participation, a block list containing the original study will be added to the duplicated
        study's filters unless `block_previous_participants` is set to `false` in the request body.
      tags:
        - studies
      parameters:
        - name: id
          in: path
          description: Study id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Duplicated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Study'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                block_previous_participants:
                  type: boolean
                  default: true
                  description: Controls whether the block list is added or not.
  /api/v1/studies/{study_id}/predicted-recruitment-time/:
    get:
      operationId: get-study-predicted-recruitment-time
      summary: Show Study predicted recruitment time
      description: >-
        Returns the predicted recruitment time for the study if it was published right now, based on a machine learning
        model.

        The recruitment time is the time from publish to the time when the final participant starts their submission.

        It does not account for the time to complete the submission.
      tags:
        - studies
      parameters:
        - name: study_id
          in: path
          description: Study id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Return the predicted recruitment time for the study
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyPredictedRecruitmentTimeResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
  /api/v1/studies/predicted-recruitment-time/:
    post:
      operationId: post-study-predicted-recruitment-time
      summary: Show Study predicted recruitment time
      description: >-
        Returns the predicted recruitment time for a study that has not even been saved as a draft if it was published
        right now, based on a machine learning model.

        The recruitment time is the time from publish to the time when the final participant starts their submission.

        It does not account for the time to complete the submission.
      tags:
        - studies
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Return the predicted recruitment time for the study
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyPredictedRecruitmentTimeResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StudyPredictedRecruitmentTimeRequest'
  /api/v1/study-cost-calculator/:
    post:
      operationId: calculate-study-cost
      summary: Calculate the study cost
      description: Calculate the study cost, including VAT and fees.
      tags:
        - studies
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Calculated total cost
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyCostResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StudyCostRequest'
  /api/v1/filters/:
    get:
      operationId: get-filters
      summary: List all filters
      description: List all filters that can be applied to your filter sets or studies.
      tags:
        - filters
      parameters:
        - name: detailed
          in: query
          description: >-
            Include extra information required to sort and categorise filters in the Prolific app. This is not required
            for API use. Default false.
          required: false
          schema:
            type: string
        - name: workspace_id
          in: query
          description: >-
            The workspace ID for the workspace you are creating a study or filterset in. This is used to get contextual
            data such as previous studies and participant groups.
          required: false
          schema:
            type: string
        - name: filter_tag
          in: query
          description: Can be used to return only Custom Group filters.
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of filters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterList'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/filters/{id}/distribution/:
    get:
      operationId: get-filter-distribution
      summary: Get filter distribution
      description: Get the distribution of a filter.
      tags:
        - filters
      parameters:
        - name: id
          in: path
          description: ID of the filter to get distribution for. Only filters tagged with "custom-group" are supported.
          required: true
          schema:
            type: string
        - name: workspace_id
          in: query
          description: ID of your current workspace.
          required: true
          schema:
            type: string
        - name: distribution_filters
          in: query
          description: >-
            Filters to get distributions for. This should be a comma-separated list of filter IDs. Only filters tagged
            with "allow-distribution" are supported.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Filter distribution
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterDistribution'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/eligibility-count/:
    post:
      operationId: get-eligible-count
      summary: Count participants
      description: >-
        Count how many participants meet all the given filters.

        Only participants that pass **every one** of the filters are counted.

        Zero means that there are less than 25 participants. We do not show lower numbers to protect the privacy of the
        participants.


        To see a list of filters that may be passed to this endpoint, see the documentation for filters.
      tags:
        - filters
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequirementsCount'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequirementsCountRequest'
  /api/v1/filter-sets/:
    get:
      operationId: get-filter-sets
      summary: List all filter sets
      description: List of all filter sets in the specified workspace.
      tags:
        - filterSets
      parameters:
        - name: workspace_id
          in: query
          description: ID of the workspace to get filter sets for.
          required: false
          schema:
            type: string
        - name: organisation_id
          in: query
          description: ID of the organisation to get filter sets for.
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of filter sets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterSetList'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: create-filter-set
      summary: Create filter set
      description: Create a filter set from a list of filters
      tags:
        - filterSets
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Filter set created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Filter Sets_CreateFilterSet_Response_201'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFilterSet'
  /api/v1/filter-sets/{id}/:
    get:
      operationId: get-filter-set
      summary: Get filter set
      description: Get details of a filter set.
      tags:
        - filterSets
      parameters:
        - name: id
          in: path
          description: ID of the filter set.
          required: true
          schema:
            type: string
        - name: version_number
          in: query
          description: Allows you to specify a specific version of the filter set to retrieve.
          required: false
          schema:
            type: integer
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Filter set details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Filter Sets_GetFilterSet_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: delete-filter-set
      summary: Delete filter set
      description: Delete a filter set.
      tags:
        - filterSets
      parameters:
        - name: id
          in: path
          description: ID of the filter set.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Deleted the filter set
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: update-filter-set
      summary: Update filter set
      description: Update the details of a filter set.
      tags:
        - filterSets
      parameters:
        - name: id
          in: path
          description: ID of the filter set.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Filter set updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Filter Sets_UpdateFilterSet_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFilterSet'
  /api/v1/filter-sets/{id}/clone/:
    post:
      operationId: clone-filter-set
      summary: Clone filter set
      description: Create a copy of a filter set.
      tags:
        - filterSets
      parameters:
        - name: id
          in: path
          description: ID of the filter set.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Filter set cloned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Filter Sets_CloneFilterSet_Response_201'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                new_name:
                  type: string
                  description: A new name for the cloned filter set.
  /api/v1/filter-sets/{id}/lock/:
    post:
      operationId: lock-filter-set
      summary: Lock filter set for editing
      description: Lock the filter set for editing.
      tags:
        - filterSets
      parameters:
        - name: id
          in: path
          description: ID of the filter set.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Filter set locked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Filter Sets_LockFilterSet_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/filter-sets/{id}/unlock/:
    post:
      operationId: unlock-filter-set
      summary: Unlock filter set for editing
      description: Unlock the filter set for editing.
      tags:
        - filterSets
      parameters:
        - name: id
          in: path
          description: ID of the filter set.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Filter set locked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Filter Sets_UnlockFilterSet_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/participant-groups/:
    get:
      operationId: get-participant-groups
      summary: Get a list of all participant groups within a project or workspace
      tags:
        - participantGroups
      parameters:
        - name: active
          in: query
          description: Filter by the active (not deleted) status of the participant group.
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1ParticipantGroupsGetParametersActive'
        - name: filter
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/ApiV1ParticipantGroupsGetParametersFilter'
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantGroupListResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: create-participant-group
      summary: Create a new participant group within a workspace
      tags:
        - participantGroups
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Participant group created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantGroupResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                workspace_id:
                  type: string
                  description: >-
                    The id of the workspace to create the participant group in. Either a workspace or organisation ID
                    must be specified.
                organisation_id:
                  type: string
                  description: >-
                    The id of the organisation to create the participant group in. Either a workspace or organisation ID
                    must be specified.
                name:
                  type: string
                  description: The name of the participant group
                description:
                  type: string
                  description: A description of the participant group
                participant_ids:
                  type: array
                  items:
                    type: string
                  description: The ids of participants to be initially added to the group
              required:
                - name
  /api/v1/participant-groups/{id}/:
    get:
      operationId: get-participant-group
      summary: Get a participant group
      tags:
        - participantGroups
      parameters:
        - name: id
          in: path
          description: The id of the participant group
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantGroupResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: delete-participant-group
      summary: Delete a participant group
      tags:
        - participantGroups
      parameters:
        - name: id
          in: path
          description: The id of the participant group
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: update-participant-group
      summary: Update a participant group
      tags:
        - participantGroups
      parameters:
        - name: id
          in: path
          description: The id of the participant group
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantGroupResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantGroupUpdate'
  /api/v1/participant-groups/{id}/participants/:
    get:
      operationId: get-participant-group-participants
      summary: Get a list of all participants within a participant group
      tags:
        - participantGroups
      parameters:
        - name: id
          in: path
          description: The id of the participant group to get participants for
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Request successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantGroupMembershipListResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: add-to-participant-group
      summary: Add participants to a participant group
      description: >
        Append participants to a participant group if they are not already members. If a participant is already a member
        of the group, they will be ignored.
      tags:
        - participantGroups
      parameters:
        - name: id
          in: path
          description: The id of the participant group to add the participant to
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: All participant(s) now in participant group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantGroupMembershipListResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantIDList'
    delete:
      operationId: remove-from-participant-group
      summary: Remove participants from a participant group
      description: >
        Remove specified participants from a participant group if they are members. If a participant is not a member of
        the group, they will be ignored.
      tags:
        - participantGroups
      parameters:
        - name: id
          in: path
          description: The id of the participant group to remove the participant(s) from
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: All participant(s) now in participant group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantGroupMembershipListResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParticipantIDList'
  /api/v1/submissions/:
    get:
      operationId: get-submissions
      summary: List submissions
      description: |-
        Returns basic information of submissions, including study id, participant id, status and start timestamp.

        **Filtering and Ordering:**
        - Filter by status, completion state, dates, and study
        - Order by start time, reward amount, or study name
        - Paginate by page_size and page (Default page_size is 20)
        - Boolean parameters accept multiple formats: 1/0, true/false, yes/no, t/f (case-insensitive)
        - Date parameters use DD/MM/YYYY format
        - Status parameters are case-insensitive with underscore normalization
      tags:
        - submissions
      parameters:
        - name: study
          in: query
          description: Filter by study ID (required). This is the ID we pass to the survey platform using %STUDY_ID%
          required: true
          schema:
            type: string
        - name: status
          in: query
          description: >-
            Filter by submission status (case-insensitive). Valid values include ACTIVE, AWAITING_REVIEW, APPROVED,
            REJECTED, RETURNED, SCREENED_OUT, TIMED-OUT
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1SubmissionsGetParametersStatus'
        - name: completed
          in: query
          description: >-
            Filter by completion status. Accepts 1/true/yes/t for completed, 0/false/no/f for incomplete
            (case-insensitive)
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1SubmissionsGetParametersCompleted'
        - name: returned
          in: query
          description: >-
            Filter by returned status. Accepts 1/true/yes/t for returned, 0/false/no/f for not returned
            (case-insensitive)
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1SubmissionsGetParametersReturned'
        - name: awaiting_review
          in: query
          description: >-
            Filter by awaiting review status. Accepts 1/true/yes/t for awaiting review, 0/false/no/f for not awaiting
            review (case-insensitive)
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1SubmissionsGetParametersAwaitingReview'
        - name: approved
          in: query
          description: >-
            Filter by approved status. Accepts 1/true/yes/t for approved, 0/false/no/f for not approved
            (case-insensitive)
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1SubmissionsGetParametersApproved'
        - name: active
          in: query
          description: Filter by active status. Accepts 1/true/yes/t for active, 0/false/no/f for not active (case-insensitive)
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1SubmissionsGetParametersActive'
        - name: timeout
          in: query
          description: >-
            Filter by timed out status. Accepts 1/true/yes/t for timed out, 0/false/no/f for not timed out
            (case-insensitive)
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1SubmissionsGetParametersTimeout'
        - name: rejected
          in: query
          description: >-
            Filter by rejected status. Accepts 1/true/yes/t for rejected, 0/false/no/f for not rejected
            (case-insensitive)
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1SubmissionsGetParametersRejected'
        - name: screened_out
          in: query
          description: >-
            Filter by screened out status. Accepts 1/true/yes/t for screened out, 0/false/no/f for not screened out
            (case-insensitive)
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1SubmissionsGetParametersScreenedOut'
        - name: completeoractive
          in: query
          description: >-
            Filter for submissions that are either completed or active. Accepts 1/true/yes/t to include, 0/false/no/f to
            exclude (case-insensitive)
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1SubmissionsGetParametersCompleteoractive'
        - name: submitted_from
          in: query
          description: Filter submissions completed after the given date. Format DD/MM/YYYY (e.g., 01/01/2024)
          required: false
          schema:
            type: string
        - name: submitted_before
          in: query
          description: Filter submissions completed before the given date. Format DD/MM/YYYY (e.g., 31/12/2024)
          required: false
          schema:
            type: string
        - name: ordering
          in: query
          description: >-
            Order results by field. Prefix with '-' for descending order. Supported values are started_at,
            submission_reward, study_name
          required: false
          schema:
            $ref: '#/components/schemas/ApiV1SubmissionsGetParametersOrdering'
        - name: page_size
          in: query
          description: Number of items to return per page (Default 20)
          required: false
          schema:
            type: integer
        - name: page
          in: query
          description: Page number to retrieve (Default 1)
          required: false
          schema:
            type: integer
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List submissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionListResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
  /api/v1/submissions/{id}/:
    get:
      operationId: get-submission
      summary: Retrieve a submission
      description: |-
        Returns the detailed information of a submission, including the
        study id, participant id, status and start timestamp
      tags:
        - submissions
      parameters:
        - name: id
          in: path
          description: |-
            Submission id. This is the ID we pass to the survey platform
            using %SESSION_ID%
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionDetail'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/submissions/{id}/transition/:
    post:
      operationId: transition-submission
      summary: Approve or reject a submission
      description: >-
        Transition a submission to `APPROVED`, `REJECTED`, `PARTIALLY APPROVED`, `AWAITING REVIEW` or `SCREENED OUT`.
        Once the status is changed, it can not be restored to its previous value.


        You can only transition a submission to PARTIALLY APPROVED or SCREENED OUT by:
          - setting up the study with the appropriate completion codes (only some workspaces have access to these features)
          - providing the correct completion code in the request body
          - providing the necessary data in the request body (to PARTIALLY APPROVE a submission)

        Note this endpoint is idempotent, so if you make the same request twice, the second request will be ignored.
      tags:
        - submissions
      parameters:
        - name: id
          in: path
          description: |-
            Submission id. This is the ID we pass to the survey platform
            using %SESSION_ID%
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmissionTransition'
  /api/v1/submissions/{id}/request-return/:
    post:
      operationId: request-submission-return
      summary: Request the participant who submitted the response to return their response
      description: >
        **This is an experimental feature that may be subject to change in the future.** <br/>

        It offers researchers the ability to ask a participant to return a submission. The return reason must be
        provided in the request and can be any free text string. <br/> The Prolific UI allows users to select any of the
        following options:

        * Didn't finish the study

        * Encountered technical problems

        * Withdrew consent

        * Other ( uses the free text input)


        This constructs a message around the reasons provided so there is no need to provide additional text beyond the
        reasons.

        <img alt="Example" src="/assets/img/api/message.png" />
      tags:
        - submissions
      parameters:
        - name: id
          in: path
          description: The submission id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |
            A message is sent to the participant belonging to the submission asking them to return.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnRequestedResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                request_return_reasons:
                  type: array
                  items:
                    type: string
              required:
                - request_return_reasons
  /api/v1/submissions/bulk-approve/:
    post:
      operationId: bulk-approve-submissions
      summary: Bulk approve submissions
      description: >-
        Bulk approve study submissions to pay participants after they have

        completed your survey or experiment. There are two variant payloads to

        this request.


        - You can supply a Study ID, and a list of participant IDs, or

        - You can provide a list of submission IDs


        We strongly recommend that you provide a list of submission IDs. These submissions do not need to be from the
        same study.


        We recommend a maximum of 1,000 submission or participant IDs per request.
      tags:
        - submissions
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Bulk approve in progress
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Submissions_BulkApproveSubmissions_Request'
  /api/v1/submissions/signals/upload-url/{filename}:
    get:
      operationId: get-submission-feedback-upload-url
      summary: Request a feedback upload URL
      description: |-
        Request a temporary, pre-signed URL to upload a feedback file for your completed studies.

        This is the first step of a two-step upload process:
          1. Call this endpoint to receive a pre-signed `upload_url`.
          2. Upload your file directly to that URL with an HTTP `PUT` request before it expires.

        <Note>
          Supported file formats are CSV, XLS, XLSX, JSON, TXT and PDF. The maximum file size is 5GB. Please check the [supported file formats](/api-reference/submission-feedback-upload#supported-file-formats) section for more details.
        </Note>
      tags:
        - submissionFeedbackUpload
      parameters:
        - name: filename
          in: path
          description: The name of the file you want to upload, including its extension (e.g. `participant_feedback.csv`).
          required: true
          schema:
            type: string
        - name: workspace_id
          in: query
          description: The ID of the Prolific workspace the feedback belongs to.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Pre-signed upload URL generated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission Feedback Upload_GetSubmissionFeedbackUploadUrl_Response_201'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/submissions/bonus-payments/:
    post:
      operationId: create-bonus-payments
      summary: Set up bonuses
      description: >-
        Set up bonus payments to one or more participants/submissions in a study.


        You need the study id, the participant|submission ids and the request in CSV format.


        The csv_bonuses field needs to be structured in the format of either:


        - `<participant_id>,<amount>\n`.

        - `<submission_id>,<amount>\n`.


        **Note: The amount will be in the study currency. The amount should be a decimal value, e.g. 1.50 for £1.50.**

        Warning: An amount of 30 will pay £/$30.00.


        As an example, `60ffe5c8371090c7041d43f8,4.25` would be a bonus of £4.25 for participant
        60ffe5c8371090c7041d43f8 in a study with GBP currency.


        Setting up a bonus payment does not actually pay them, to do so check
        [/api/v1/bulk-bonus-payments/{id}/pay/](#tag/Bonuses/paths/~1api~1v1~1bulk-bonus-payments~1%7Bid%7D~1pay~1/post)


        The submission and participant IDs need to have taken part in the study in order for this call to be successful.

        If not, you will get a "400" HTTP response back, which explains which IDs are incorrect.


        We recommend a maximum of 200 participant or submission IDs per request.
      tags:
        - bonuses
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Bonus created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkBonus'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                study_id:
                  type: string
                csv_bonuses:
                  type: string
  /api/v1/bulk-bonus-payments/{id}/pay/:
    post:
      operationId: pay-bonus-payments
      summary: Pay bonuses
      description: >-
        Bonus payments are made asynchronously.

        The payment will be done in the following minutes and your balance will be updated accordingly.


        <Warning>

        This endpoint is **not idempotent**. Sending multiple requests with the same bulk bonus payment ID will result
        in participants being paid multiple times. Ensure you send this request only once per bulk payment.

        </Warning>
      tags:
        - bonuses
      parameters:
        - name: id
          in: path
          description: Bulk bonus payment id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Successfully received bonus payments request. The bonuses will be paid asynchronously.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/messages/:
    get:
      operationId: get-messages
      summary: Retrieve messages
      description: Get messages between you and another user or your messages with all users.
      tags:
        - messages
      parameters:
        - name: user_id
          in: query
          description: Another user ID, must be provided if no created_after date is provided.
          required: false
          schema:
            type: string
        - name: created_after
          in: query
          description: >-
            Only fetch messages created after timestamp. Datetime in ISO8601 format. Must be provided if no user_id is
            provided. You can only fetch up to the last 30 days of messages.
          required: false
          schema:
            type: string
        - name: excluded_sender_ids
          in: query
          description: |
            A comma-separated list of sender IDs whose messages should be excluded from the response. Maximum 10 IDs.

            e.g. `excluded_sender_ids=abc,def`.
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Messages'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
    post:
      operationId: send-message
      summary: Send a message
      description: Send a message to a participant or another researcher
      tags:
        - messages
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: The message has been sent
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessage'
  /api/v1/messages/bulk/:
    post:
      operationId: bulk-message-participants
      summary: Send a message to multiple participants
      description: Send a message to multiple participants.
      tags:
        - messages
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: The message has been sent
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendBulkMessage'
  /api/v1/messages/participant-group/:
    post:
      operationId: send-message-to-participant-group
      summary: Send a message to a participant group
      description: Send a message to a participant group.
      tags:
        - messages
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: The message has been sent
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageParticipantGroup'
  /api/v1/messages/unread/:
    get:
      operationId: get-unread-messages
      summary: Retrieve unread messages
      description: |-
        Get all unread messages.
        The messages you have sent are never returned, only messages you have received and not read.
        It does not mark those messages as read.
      tags:
        - messages
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Messages'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
  /api/v1/workspaces/:
    get:
      operationId: get-workspaces
      summary: Get all a user's workspaces
      description: Gets a list of all workspaces that the user is a member of.
      tags:
        - workspaces
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspacesListResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: create-workspace
      summary: Create a workspace
      description: Creates a new workspace and adds the user as a Workspace Admin.
      tags:
        - workspaces
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkspace'
  /api/v1/workspaces/{workspace_id}/:
    get:
      operationId: get-workspace
      summary: Get workspace
      description: Gets a workspace's details
      tags:
        - workspaces
      parameters:
        - name: workspace_id
          in: path
          description: Workspace id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: update-workspace
      summary: Update a workspace
      description: Updates a workspace's details.
      tags:
        - workspaces
      parameters:
        - name: workspace_id
          in: path
          description: Workspace id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated workspace redirect link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Workspace'
  /api/v1/workspaces/{workspace_id}/balance/:
    get:
      operationId: get-workspace-balance
      summary: Get the balance of a workspace
      description: Provides details of the funds available in the workspace.
      tags:
        - workspaces
      parameters:
        - name: workspace_id
          in: path
          description: Workspace id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceBalance'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/workspaces/{workspace_id}/projects/:
    get:
      operationId: get-projects
      summary: Get all projects in a workspace
      description: Gets a list of all the projects within the workspace.
      tags:
        - projects
      parameters:
        - name: workspace_id
          in: path
          description: Workspace id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectShortListResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: create-project
      summary: Create a project
      description: |-
        Creates a new project within the workspace.
        When this project is created, it adds the user as a Project Editor.
        Set `type` to `PUBLIC` to create a public project.
      tags:
        - projects
      parameters:
        - name: workspace_id
          in: path
          description: Workspace id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Successfully created project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProject'
  /api/v1/projects/{project_id}/:
    get:
      operationId: get-project
      summary: Get project
      description: Gets a project's details
      tags:
        - projects
      parameters:
        - name: project_id
          in: path
          description: Project id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: update-project
      summary: Update a project
      description: |-
        Update a project's details.
        Public projects support partial updates to `public_details`.
        Once a public project has published studies, `public_details.title` can no longer be changed.
      tags:
        - projects
      parameters:
        - name: project_id
          in: path
          description: Project id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated project redirect link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProject'
  /api/v1/surveys/:
    get:
      operationId: get-surveys
      summary: Get all surveys
      description: Get all the surveys for a researcher.
      tags:
        - surveys
      parameters:
        - name: researcher_id
          in: query
          required: true
          schema:
            type: string
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllSurveysResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: create-survey
      summary: Create survey
      description: >-
        You can create a survey with either `sections -> questions` or just `questions`. This allows you to decide

        how much flexibility you want in your survey design. However, if you want to render the survey in the Prolific
        Application, you must use `sections`.
      tags:
        - surveys
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyOut'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SurveyIn'
  /api/v1/surveys/{survey_id}:
    get:
      operationId: get-survey
      summary: Get survey
      description: Get a single survey given an ID.
      tags:
        - surveys
      parameters:
        - name: survey_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyOut'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: delete-survey
      summary: Delete survey
      description: Delete a single Survey.
      tags:
        - surveys
      parameters:
        - name: survey_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/surveys/{survey_id}/responses/:
    get:
      operationId: get-responses
      summary: Get all responses
      description: Get all the responses for a given Survey.
      tags:
        - surveys
      parameters:
        - name: survey_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: create-response
      summary: Create response
      description: Create a Response for a survey.
      tags:
        - surveys
      parameters:
        - name: survey_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyResponseOut'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SurveyResponseIn'
    delete:
      operationId: delete-responses
      summary: Delete all responses
      description: Delete all the responses for a given Survey.
      tags:
        - surveys
      parameters:
        - name: survey_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/surveys/{survey_id}/responses/summary/:
    get:
      operationId: get-summary
      summary: Get summary of responses
      description: Get an aggregated summary of responses for a given survey.
      tags:
        - surveys
      parameters:
        - name: survey_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveySummary'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/surveys/{survey_id}/responses/{response_id}:
    get:
      operationId: get-response
      summary: Get response
      description: Get a single response for a survey.
      tags:
        - surveys
      parameters:
        - name: survey_id
          in: path
          required: true
          schema:
            type: string
        - name: response_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyResponseOut'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: delete-response
      summary: Delete a response
      description: Delete a single Response.
      tags:
        - surveys
      parameters:
        - name: survey_id
          in: path
          required: true
          schema:
            type: string
        - name: response_id
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: Any type
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/hooks/event-types/:
    get:
      operationId: get-event-types
      summary: List all subscribable event types
      description: You can subscribe to any of the event types defined in this response.
      tags:
        - webhooks
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of event types that can be subscribed to.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventTypeList'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/hooks/secrets/:
    get:
      operationId: get-secrets
      summary: List all secrets
      description: A view of all the secrets for the workspaces you belong to.
      tags:
        - webhooks
      parameters:
        - name: workspace_id
          in: query
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretList'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: create-secret
      summary: Create/replace a secret
      description: >-
        Generate a secret for verifying the request signature header of the subscription payload. If a secret already
        exists, this call will delete the old secret and create a new one.
      tags:
        - webhooks
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretDetail'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSecret'
  /api/v1/hooks/subscriptions/:
    get:
      operationId: get-subscriptions
      summary: List all subscriptions
      description: A view of all subscriptions you have created.
      tags:
        - webhooks
      parameters:
        - name: is_enabled
          in: query
          description: A filter to only pull back enabled subscriptions. Default true.
          required: false
          schema:
            type: boolean
        - name: workspace_id
          in: query
          description: >-
            The Workspace ID we want to get the subscriptions for. If not given, the subscriptions for all of your
            workspaces will be returned.
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of subscriptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionList'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: create-subscription
      summary: Create a subscription
      description: >-
        Create a subscription for an event type. When an event is triggered in the Prolific system, the hook will
        automatically notify the specified target URL.


        Before creating a subscription, you must ensure that you have created a secret for your workspace.
      tags:
        - webhooks
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionList'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionDetail'
  /api/v1/hooks/subscriptions/{subscription_id}/:
    get:
      operationId: get-subscription
      summary: Retrieve a subscription
      description: Get a single subscription
      tags:
        - webhooks
      parameters:
        - name: subscription_id
          in: path
          description: Subscription id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionDetail'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: confirm-subscription
      summary: Confirm a subscription
      description: Confirm a subscription to an event type
      tags:
        - webhooks
      parameters:
        - name: subscription_id
          in: path
          description: Subscription id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionDetail'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionConfirmation'
    delete:
      operationId: delete-subscription
      summary: Delete a subscription
      description: >-
        If you no longer require to be notified of a certain event type, you can delete a subscription. If you want to
        temporarily pause notifications, you can use the PATCH request documented.
      tags:
        - webhooks
      parameters:
        - name: subscription_id
          in: path
          description: Subscription id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: update-subscription
      summary: Update a subscription
      description: >-
        This allows you to update a subscription. For example you can temporarily disable or enable a subscription if
        you wish.
      tags:
        - webhooks
      parameters:
        - name: subscription_id
          in: path
          description: Subscription id
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionDetail'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionUpdateDetail'
  /api/v1/hooks/subscriptions/{subscription_id}/events/:
    get:
      operationId: get-events
      summary: Get subscription events
      description: Get all of the events that have triggered for the given subscription.
      tags:
        - webhooks
      parameters:
        - name: subscription_id
          in: path
          description: Subscription id
          required: true
          schema:
            type: string
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
        - name: status
          in: query
          description: Filter events by status. Accepts a single status or a JSON array of statuses as a string.
          required: false
          schema:
            type: string
        - name: resource_id
          in: query
          description: Filter events by the ID of the resource for which the event was sent.
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEventList'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/invitations/:
    post:
      operationId: create-invitation
      summary: Create a new invitation
      description: >
        Initiate a new invitation process for adding users to a Workspace.


        This operation can be performed only by authenticated users who are admins for the specified workspace.
        Invitations will be sent to the email addresses provided in the request.
      tags:
        - invitations
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Invitation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInvitationResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvitationRequest'
  /api/v1/reward-recommendations/:
    get:
      operationId: calculate-reward-recommendations
      summary: Calculate reward recommendations
      description: >-
        Calculate the recommended participant reward rates for a data collection, optionally based upon a given set of
        filters
      tags:
        - rewardRecommendations
      parameters:
        - name: workspace_id
          in: query
          description: The ID of the workspace in which you'll be creating the study
          required: true
          schema:
            type: string
        - name: currency
          in: query
          description: An ISO 4217 currency code. Note that we only support a selection of currency codes as per the enum values.
          required: true
          schema:
            $ref: '#/components/schemas/ApiV1RewardRecommendationsGetParametersCurrency'
        - name: screener_ids
          in: query
          description: >-
            A URL-encoded, comma-delimited list of filter IDs (e.g. custom group filter IDs) that you plan to apply to
            your study.


            There are various methods of converting an array of filter IDs to a URL-encoded, comma delimited array e.g:


            JavaScript:


            ```js

            const screenerIDs = ["mandarin", "spanish"];

            const encodedScreenerIDs = encodeURIComponent(screenerIDs.join(","));

            const url =
            `https://api.prolific.com/api/v1/reward-recommendations?screener_ids=${encodedScreenerIDs}&workspace_id=<workspace
            ID>&currency=GBP`

            ```


            Python:


            ```python

            import urllib.parse


            screener_ids = ["mandarin", "spanish"]

            encoded_screener_ids = urllib.parse.quote(",".join(screener_ids))

            url =
            f"https://api.prolific.com/api/v1/reward-recommendations?screener_ids={encoded_screener_ids}&workspace_id=<workspace
            ID>&currency=GBP"

            ```
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >
            A list of reward recommendations. We suggest using the first recommendation in the list as this is
            guaranteed to be the most recent set of reward rates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardRecommendationsResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
  /.well-known/study/jwks.json:
    get:
      operationId: get-study-jwks
      summary: Retrieve JSON Web Key Set (JWKS)
      description: >
        Fetches the public keys that can be used to verify JWTs signed by Prolific. Clients should cache these keys and
        update them at least daily.


        To verify the signature of a JWT you must verify the following:

        * The JWT signature is authentic by verifying it with the public key from Prolific that correlates with the KID.

        * The JWT hasn't expired, by checking the `exp` claim.

        * The `aud` claim is the correct domain for your tool.

        * The `prolific` claim matches your expected payload as set in the `external_study_url` property. It always
        includes `workspace_id`. When the workspace is linked to an organisation, it also includes `organisation_id`.
      tags:
        - wellKnownEndpoints
      responses:
        '200':
          description: Successful response with the JWKS.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWKSResponse'
  /api/v1/credentials/:
    get:
      operationId: list-credential-pools
      summary: List credential pools for a workspace
      description: >-
        Retrieve a list of credential pools belonging to a specific workspace.

        Each credential pool summary includes the pool ID, total number of credentials, number of available (unredeemed)
        credentials, and the workspace ID.
      tags:
        - credentials
      parameters:
        - name: workspace_id
          in: query
          description: The workspace ID to filter credential pools by
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Credential pools retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credentials_ListCredentialPools_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '403':
          description: Forbidden - User does not have workspace.workspace_update permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '502':
          description: Bad Gateway - Credentials service unavailable or internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
    post:
      operationId: create-credential-pool
      summary: Create credential pool
      description: >-
        Create a new workspace-level credential pool. Credential pools contain username/password pairs that can be
        assigned to participants when they start a study. This allows researchers to provide pre-provisioned credentials
        for third-party platforms.

        The credentials are provided as a CSV string where each line contains a username and password separated by a
        comma (e.g., "user1,pass1\nuser2,pass2").
      tags:
        - credentials
      parameters:
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Credential pool created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credentials_CreateCredentialPool_Response_201'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '403':
          description: Forbidden - User does not have workspace.workspace_update permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '409':
          description: Conflict - Duplicate credentials detected (username already exists in pool)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '502':
          description: Bad Gateway - Credentials service unavailable or internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                credentials:
                  type: string
                  description: CSV-formatted credentials (username,password per line)
                workspace_id:
                  type: string
                  description: The ID of the workspace this credential pool belongs to
              required:
                - credentials
                - workspace_id
  /api/v1/credentials/{credential_pool_id}/:
    patch:
      operationId: update-credential-pool
      summary: Update credential pool
      description: >-
        Add new credentials to an existing credential pool. This operation is additive - new credentials are appended to
        the existing pool rather than replacing them. The credentials service validates that no duplicate usernames
        exist.

        The credentials are provided as a CSV string where each line contains a username and password separated by a
        comma (e.g., "user4,pass4\nuser5,pass5").
      tags:
        - credentials
      parameters:
        - name: credential_pool_id
          in: path
          description: Credential pool ID
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Prolific API uses API token to authenticate requests. You can create an API token directly from your
            settings.


            Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


            If your token is leaked, delete it and create a new one directly in the app.


            In your requests add `Authorization` header with the value `Token <your token>`.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Credential pool updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credentials_UpdateCredentialPool_Response_200'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '403':
          description: Forbidden - User does not have workspace.workspace_update permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '404':
          description: Not Found - Credential pool does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '409':
          description: Conflict - Duplicate credentials detected (username already exists in pool)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
        '502':
          description: Bad Gateway - Credentials service unavailable or internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                credentials:
                  type: string
                  description: CSV-formatted credentials to add (username,password per line)
              required:
                - credentials
servers:
  - url: https://api.prolific.com
    description: Production
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
      required:
        - id
        - email
      title: User
    ErrorDetailDetail2:
      type: object
      properties:
        any_field:
          type: array
          items:
            type: string
          description: Name of the field with a validation error and as a value an array with the error descriptions
      description: All fields with validation errors
      title: ErrorDetailDetail2
    ErrorDetailDetail:
      oneOf:
        - type: string
        - type: array
          items:
            type: string
        - $ref: '#/components/schemas/ErrorDetailDetail2'
      description: Error detail
      title: ErrorDetailDetail
    ErrorDetail:
      type: object
      properties:
        status:
          type: integer
          description: Status code as in the http standards
        error_code:
          type: integer
          description: Internal error code
        title:
          type: string
          description: Error title
        detail:
          $ref: '#/components/schemas/ErrorDetailDetail'
          description: Error detail
        additional_information:
          type: string
          description: Optional extra information
        traceback:
          type: string
          description: Optional debug information
        interactive:
          type: boolean
      required:
        - status
        - error_code
        - title
        - detail
      title: ErrorDetail
    Error:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
        - error
      title: Error
    CreateTestParticipantForResearcher:
      type: object
      properties:
        email:
          type: string
          format: email
          description: |
            - The email of the test participant.
            - This cannot be an email that has been registered with Prolific already.
      required:
        - email
      title: CreateTestParticipantForResearcher
    CreateTestParticipantForResearcherResponse:
      type: object
      properties:
        participant_id:
          type: string
          format: objectId
          description: The ID of the test participant
      title: CreateTestParticipantForResearcherResponse
    AiTaskBuilderBatchDatasetsItems:
      type: object
      properties:
        id:
          type: string
          format: uuid
        total_datapoint_count:
          type: integer
        filename:
          type: string
          description: The filename of the dataset
      required:
        - id
        - total_datapoint_count
        - filename
      title: AiTaskBuilderBatchDatasetsItems
    AiTaskBuilderBatchStatus:
      type: string
      enum:
        - UNINITIALISED
        - PROCESSING
        - READY
        - ERROR
      title: AiTaskBuilderBatchStatus
    AiTaskBuilderBatchTaskDetails:
      type: object
      properties:
        task_name:
          type: string
        task_introduction:
          type: string
          description: HTML formatted task introduction
        task_steps:
          type: string
          description: HTML formatted task steps
      required:
        - task_name
        - task_introduction
        - task_steps
      title: AiTaskBuilderBatchTaskDetails
    BatchItemsDatasetFieldRefType:
      type: string
      enum:
        - dataset_field
      title: BatchItemsDatasetFieldRefType
    BatchItemsImageBlockType:
      type: string
      enum:
        - image
      title: BatchItemsImageBlockType
    BatchItemsRichTextBlockType:
      type: string
      enum:
        - rich_text
      title: BatchItemsRichTextBlockType
    BatchItemsRichTextBlockContentFormat:
      type: string
      enum:
        - html
        - markdown
      default: html
      description: Format of the `content` field. Defaults to `html`.
      title: BatchItemsRichTextBlockContentFormat
    BatchItemsFreeTextInstructionType:
      type: string
      enum:
        - free_text
      title: BatchItemsFreeTextInstructionType
    ValidationRuleType:
      type: string
      enum:
        - number
        - string
      description: >-
        The expected input type. When "number", the input must be numeric and min/max constrain the numeric value. When
        "string", the input is treated as text and min/max constrain the character count.
      title: ValidationRuleType
    ValidationRule:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ValidationRuleType'
          description: >-
            The expected input type. When "number", the input must be numeric and min/max constrain the numeric value.
            When "string", the input is treated as text and min/max constrain the character count.
        min:
          type:
            - number
            - 'null'
          format: double
          description: >-
            Minimum value (for type "number") or minimum character count (for type "string"). Null means unbounded. When
            type is "string", must be a non-negative integer. If both min and max are provided, min must be less than or
            equal to max.
        max:
          type:
            - number
            - 'null'
          format: double
          description: >-
            Maximum value (for type "number") or maximum character count (for type "string"). Null means unbounded. When
            type is "string", must be a non-negative integer. If both min and max are provided, max must be greater than
            or equal to min.
      required:
        - type
      description: Optional validation constraints for input values
      title: ValidationRule
    BatchItemsFreeTextWithUnitInstructionType:
      type: string
      enum:
        - free_text_with_unit
      title: BatchItemsFreeTextWithUnitInstructionType
    BatchItemsFreeTextWithUnitInstructionUnitOptionsItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      title: BatchItemsFreeTextWithUnitInstructionUnitOptionsItemsValue
    BatchItemsFreeTextWithUnitInstructionUnitOptionsItems:
      type: object
      properties:
        label:
          type: string
        value:
          $ref: '#/components/schemas/BatchItemsFreeTextWithUnitInstructionUnitOptionsItemsValue'
        validation:
          $ref: '#/components/schemas/ValidationRule'
      required:
        - label
        - value
      title: BatchItemsFreeTextWithUnitInstructionUnitOptionsItems
    BatchItemsFreeTextWithUnitInstructionUnitPosition:
      type: string
      enum:
        - prefix
        - suffix
      description: Position of the unit selector relative to the text input.
      title: BatchItemsFreeTextWithUnitInstructionUnitPosition
    BatchItemsMultipleChoiceInstructionType:
      type: string
      enum:
        - multiple_choice
      title: BatchItemsMultipleChoiceInstructionType
    BatchItemsMultipleChoiceInstructionOptionsItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      title: BatchItemsMultipleChoiceInstructionOptionsItemsValue
    BatchItemsMultipleChoiceInstructionOptionsItems:
      type: object
      properties:
        label:
          type: string
        value:
          $ref: '#/components/schemas/BatchItemsMultipleChoiceInstructionOptionsItemsValue'
        exclusive:
          type: boolean
          description: >-
            When true, selecting this option deselects all other options. Useful for "None of the above" style options.
            Not allowed when `answer_limit` is 1, and at least one non-exclusive option must remain if any option is
            exclusive.
      required:
        - label
        - value
      title: BatchItemsMultipleChoiceInstructionOptionsItems
    BatchItemsMultipleChoiceWithFreeTextInstructionType:
      type: string
      enum:
        - multiple_choice_with_free_text
      title: BatchItemsMultipleChoiceWithFreeTextInstructionType
    BatchItemsMultipleChoiceWithFreeTextInstructionOptionsItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      title: BatchItemsMultipleChoiceWithFreeTextInstructionOptionsItemsValue
    BatchItemsMultipleChoiceWithFreeTextInstructionOptionsItems:
      type: object
      properties:
        label:
          type: string
        value:
          $ref: '#/components/schemas/BatchItemsMultipleChoiceWithFreeTextInstructionOptionsItemsValue'
        heading:
          type: string
          description: Required. Section heading that groups this option.
        exclusive:
          type: boolean
          description: When true, selecting this option deselects all other options.
      required:
        - label
        - value
        - heading
      title: BatchItemsMultipleChoiceWithFreeTextInstructionOptionsItems
    BatchItemsFileUploadInstructionType:
      type: string
      enum:
        - file_upload
      title: BatchItemsFileUploadInstructionType
    BatchItemsItem:
      oneOf:
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/BatchItemsDatasetFieldRefType'
            field:
              type: string
              description: Name of the dataset schema field to reference.
          required:
            - type
            - field
          description: |-
            References a field in the batch's attached dataset. At task time, the dataset value
            for the current datapoint is rendered at this position. Only dataset schema fields of
            type `text` or `image_url` are permitted, and the same field may not be referenced more
            than once on the same page.
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/BatchItemsImageBlockType'
            id:
              type: string
              description: Server-assigned identifier; present on responses. Include to preserve an existing item when updating.
            url:
              type: string
              format: uri
              description: HTTPS URL of the image. Non-HTTPS URLs are rejected.
            alt_text:
              type: string
              description: Alt text shown to screen readers. Required for accessibility.
            caption:
              type: string
              description: Optional caption displayed below the image.
          required:
            - type
            - url
            - alt_text
          description: An image content block rendered inline within the batch layout.
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/BatchItemsRichTextBlockType'
            id:
              type: string
              description: Server-assigned identifier; present on responses. Include to preserve an existing item when updating.
            content:
              type: string
              description: >-
                Rich text content. Interpreted as HTML by default, or as Markdown when `content_format` is set to
                `markdown` (converted to HTML server-side before storage).
            content_format:
              $ref: '#/components/schemas/BatchItemsRichTextBlockContentFormat'
              default: html
              description: Format of the `content` field. Defaults to `html`.
          required:
            - type
            - content
          description: A rich-text content block rendered inline within the batch layout.
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/BatchItemsFreeTextInstructionType'
            id:
              type: string
              description: Server-assigned identifier; present on responses. Include to preserve an existing item when updating.
            description:
              type: string
              description: The question or prompt displayed to participants.
            helper_text:
              type: string
              description: Additional guidance text displayed below the question.
            placeholder_text_input:
              type: string
              description: Placeholder text displayed in the input field.
            validation:
              $ref: '#/components/schemas/ValidationRule'
              description: Optional validation constraints for the input value.
          required:
            - type
            - description
          description: Free-text input instruction.
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/BatchItemsFreeTextWithUnitInstructionType'
            id:
              type: string
              description: Server-assigned identifier; present on responses. Include to preserve an existing item when updating.
            description:
              type: string
              description: The question or prompt displayed to participants.
            helper_text:
              type: string
            placeholder_text_input:
              type: string
            unit_options:
              type: array
              items:
                $ref: '#/components/schemas/BatchItemsFreeTextWithUnitInstructionUnitOptionsItems'
              description: Available units the participant can select from.
            default_unit:
              type: string
              description: Default selected unit. Must match the `value` of one of the entries in `unit_options`.
            unit_position:
              $ref: '#/components/schemas/BatchItemsFreeTextWithUnitInstructionUnitPosition'
              description: Position of the unit selector relative to the text input.
          required:
            - type
            - description
            - unit_options
            - unit_position
          description: Free-text input instruction paired with a unit selector.
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/BatchItemsMultipleChoiceInstructionType'
            id:
              type: string
              description: Server-assigned identifier; present on responses. Include to preserve an existing item when updating.
            description:
              type: string
              description: The question or prompt displayed to participants.
            helper_text:
              type: string
            placeholder_text_input:
              type: string
            answer_limit:
              type: integer
              description: >-
                Number of options that can be selected. Use `1` for single-select, `-1` for unlimited, or any number up
                to the total options.
            disable_dropdown:
              type: boolean
              default: false
              description: When true, always renders checkbox/radio elements instead of a dropdown select.
            options:
              type: array
              items:
                $ref: '#/components/schemas/BatchItemsMultipleChoiceInstructionOptionsItems'
          required:
            - type
            - description
            - answer_limit
            - options
          description: Multiple-choice instruction.
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/BatchItemsMultipleChoiceWithFreeTextInstructionType'
            id:
              type: string
              description: Server-assigned identifier; present on responses. Include to preserve an existing item when updating.
            description:
              type: string
            helper_text:
              type: string
            placeholder_text_input:
              type: string
            answer_limit:
              type: integer
            disable_dropdown:
              type: boolean
              default: false
            options:
              type: array
              items:
                $ref: '#/components/schemas/BatchItemsMultipleChoiceWithFreeTextInstructionOptionsItems'
          required:
            - type
            - description
            - answer_limit
            - options
          description: Multiple-choice instruction with an additional free-text input per selected option.
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/BatchItemsFileUploadInstructionType'
            id:
              type: string
              description: Server-assigned identifier; present on responses. Include to preserve an existing item when updating.
            description:
              type: string
            helper_text:
              type: string
            accepted_file_types:
              type: array
              items:
                type: string
              description: >-
                File extensions to accept (each must start with a dot, e.g. `.jpg`). Defaults to `[".jpg", ".jpeg",
                ".png", ".heic", ".heif"]`.
            max_file_size_mb:
              type: number
              format: double
              description: Maximum size in megabytes per file. Defaults to 25.
            min_file_count:
              type: integer
              description: Minimum number of files required. Defaults to 1.
            max_file_count:
              type: integer
              description: Maximum number of files allowed. Defaults to 10. Must be greater than or equal to `min_file_count`.
          required:
            - type
            - description
          description: File upload instruction.
      discriminator:
        propertyName: type
      description: |-
        A single item within a column. One of: a dataset field reference (`dataset_field`),
        a content block (`image`, `rich_text`), or an instruction (`free_text`,
        `free_text_with_unit`, `multiple_choice`, `multiple_choice_with_free_text`, `file_upload`).
        Discriminated on `type`.
      title: BatchItemsItem
    BatchItemsColumn:
      type: object
      properties:
        id:
          type: string
          description: Server-assigned identifier; present on responses. Include to preserve an existing column when updating.
        items:
          type: array
          items:
            $ref: '#/components/schemas/BatchItemsItem'
      required:
        - items
      description: A column within a row. Contains one or more items rendered top-to-bottom.
      title: BatchItemsColumn
    BatchItemsRow:
      type: object
      properties:
        id:
          type: string
          description: Server-assigned identifier; present on responses. Include to preserve an existing row when updating.
        columns:
          type: array
          items:
            $ref: '#/components/schemas/BatchItemsColumn'
      required:
        - columns
      description: A row within a page. Renders 1 or 2 columns side-by-side.
      title: BatchItemsRow
    BatchItemsPage:
      type: object
      properties:
        id:
          type: string
          description: Server-assigned identifier; present on responses. Include to preserve an existing page when updating.
        rows:
          type: array
          items:
            $ref: '#/components/schemas/BatchItemsRow'
      required:
        - rows
      description: |-
        A single page of a batch's inline layout. Each page is rendered as one screen to participants
        and contains an ordered list of rows. On responses, includes a server-assigned `id`; omit
        `id` on create to add a new page.
      title: BatchItemsPage
    AITaskBuilderBatch:
      type: object
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
          description: An ISO-8601 formatted string representing the batch creation time, in UTC.
        created_by:
          type: string
          description: User ID of the Prolific user that created the resource.
        datasets:
          type: array
          items:
            $ref: '#/components/schemas/AiTaskBuilderBatchDatasetsItems'
        name:
          type: string
        status:
          $ref: '#/components/schemas/AiTaskBuilderBatchStatus'
        total_task_count:
          type: integer
        total_instruction_count:
          type: integer
        workspace_id:
          type: string
        schema_version:
          type: integer
        task_details:
          $ref: '#/components/schemas/AiTaskBuilderBatchTaskDetails'
        total_task_groups:
          type: integer
        batch_items:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/BatchItemsPage'
          description: |-
            The persisted `batch_items` layout, populated when the batch was created with
            `batch_items`. `null` for legacy batches authored via the standalone instructions
            endpoint. Every page, row, column, and item carries a server-assigned `id`.
        auto_sync_enabled:
          type: boolean
          description: |-
            When `true`, datapoints appended to the batch's attached dataset automatically trigger a
            sync that materialises tasks for them. Optional — absent on batches that have never
            enabled auto-sync. Absent or `false` mean auto-sync is off.
      required:
        - id
        - created_at
        - created_by
        - datasets
        - name
        - status
        - total_task_count
        - total_instruction_count
        - workspace_id
        - schema_version
        - task_details
        - total_task_groups
      title: AITaskBuilderBatch
    ApiV1DataCollectionBatchesGetResponsesContentApplicationJsonSchemaMeta:
      type: object
      properties:
        count:
          type: integer
          description: Total number of batches
      title: ApiV1DataCollectionBatchesGetResponsesContentApplicationJsonSchemaMeta
    AI Task Builder_GetTaskBuilderBatches_Response_200:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/AITaskBuilderBatch'
        meta:
          $ref: '#/components/schemas/ApiV1DataCollectionBatchesGetResponsesContentApplicationJsonSchemaMeta'
      title: AI Task Builder_GetTaskBuilderBatches_Response_200
    ApiV1DataCollectionBatchesPostRequestBodyContentApplicationJsonSchemaTaskDetails:
      type: object
      properties:
        task_name:
          type: string
          description: The title displayed to participants
        task_introduction:
          type: string
          description: HTML formatted introduction shown at the start of the task
        task_steps:
          type: string
          description: HTML formatted step-by-step instructions
      required:
        - task_name
        - task_introduction
        - task_steps
      description: Task metadata displayed to participants
      title: ApiV1DataCollectionBatchesPostRequestBodyContentApplicationJsonSchemaTaskDetails
    AiTaskBuilderBatchCreateDatasetsItems:
      type: object
      properties:
        id:
          type: string
          format: uuid
        total_datapoint_count:
          type: integer
      required:
        - id
        - total_datapoint_count
      title: AiTaskBuilderBatchCreateDatasetsItems
    AiTaskBuilderBatchCreateStatus:
      type: string
      enum:
        - UNINITIALISED
        - PROCESSING
        - READY
        - ERROR
      title: AiTaskBuilderBatchCreateStatus
    AiTaskBuilderBatchCreateTaskDetails:
      type: object
      properties:
        task_name:
          type: string
        task_introduction:
          type: string
          description: HTML formatted task introduction
        task_steps:
          type: string
          description: HTML formatted task steps
      required:
        - task_name
        - task_introduction
        - task_steps
      title: AiTaskBuilderBatchCreateTaskDetails
    AITaskBuilderBatchCreate:
      type: object
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
          description: An ISO-8601 formatted string representing the batch creation time, in UTC.
        created_by:
          type: string
          description: User ID of the Prolific user that created the resource.
        datasets:
          type: array
          items:
            $ref: '#/components/schemas/AiTaskBuilderBatchCreateDatasetsItems'
        name:
          type: string
        status:
          $ref: '#/components/schemas/AiTaskBuilderBatchCreateStatus'
        total_task_count:
          type: integer
        total_instruction_count:
          type: integer
        workspace_id:
          type: string
        task_details:
          $ref: '#/components/schemas/AiTaskBuilderBatchCreateTaskDetails'
        batch_items:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/BatchItemsPage'
          description: |-
            The persisted `batch_items` layout, returned only when `batch_items` was supplied on
            create. Every page, row, column, and item is returned with a server-assigned `id`.
      required:
        - id
        - created_at
        - created_by
        - datasets
        - name
        - status
        - total_task_count
        - total_instruction_count
        - workspace_id
        - task_details
      title: AITaskBuilderBatchCreate
    BatchItemsValidationErrorType:
      type: string
      enum:
        - INVALID_BATCH_ITEMS
      title: BatchItemsValidationErrorType
    BatchItemsValidationErrorIssuesItems:
      type: object
      properties:
        page:
          type: integer
          description: Zero-based index of the page containing the invalid item.
        row:
          type: integer
          description: Zero-based index of the row within the page.
        column:
          type: integer
          description: Zero-based index of the column within the row.
        item:
          type: integer
          description: Zero-based index of the item within the column.
        type:
          type: string
          description: The item `type` that failed validation (e.g. `dataset_field`, `multiple_choice`, `file_upload`).
        field:
          type: string
          description: Dataset field name. Present only for `dataset_field` validation issues.
        message:
          type: string
          description: Human-readable validation error message.
      required:
        - page
        - row
        - column
        - item
        - type
        - message
      title: BatchItemsValidationErrorIssuesItems
    BatchItemsValidationError:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/BatchItemsValidationErrorType'
        message:
          type: string
        issues:
          type: array
          items:
            $ref: '#/components/schemas/BatchItemsValidationErrorIssuesItems'
      required:
        - type
        - message
        - issues
      description: |-
        `422 Unprocessable Entity` payload returned when `batch_items` fails server-side
        validation on create or update. Each entry in `issues` pinpoints the offending item
        using zero-based `page` / `row` / `column` / `item` indices, and describes what was
        wrong (e.g. `dataset_field` used without a v4 dataset and populated schema attached,
        unknown dataset field, the same dataset field referenced more than once on a page,
        `answer_limit` exceeds options, `default_unit` does not match `unit_options`,
        `min_file_count` greater than `max_file_count`).
      title: BatchItemsValidationError
    ApiV1DataCollectionBatchesBatchIdPatchRequestBodyContentApplicationJsonSchemaTaskDetails:
      type: object
      properties:
        task_name:
          type: string
        task_introduction:
          type: string
          description: HTML formatted task introduction
        task_steps:
          type: string
          description: HTML formatted task steps
      required:
        - task_name
        - task_introduction
        - task_steps
      title: ApiV1DataCollectionBatchesBatchIdPatchRequestBodyContentApplicationJsonSchemaTaskDetails
    UpdateTaskBuilderBatchRequestBadRequestError:
      type: object
      properties:
        message:
          type: string
      title: UpdateTaskBuilderBatchRequestBadRequestError
    SyncJobStatus:
      type: string
      enum:
        - queued
        - processing
        - complete
        - failed
      description: Current status of the sync job.
      title: SyncJobStatus
    SyncJob:
      type: object
      properties:
        batch_id:
          type: string
          format: uuid
          description: The batch this sync job belongs to.
        dataset_id:
          type: string
          format: uuid
          description: The dataset whose appended datapoints are being synced.
        sync_id:
          type: string
          format: uuid
          description: The unique identifier of the sync job.
        created_at:
          type: string
          format: date-time
          description: When the sync job was created (ISO 8601, UTC).
        updated_at:
          type: string
          format: date-time
          description: When the sync job was last updated (ISO 8601, UTC).
        status:
          $ref: '#/components/schemas/SyncJobStatus'
          description: Current status of the sync job.
        tasks_created:
          type: integer
          description: Number of tasks created this sync. Present when status is `complete`.
        datapoints_processed:
          type: integer
          description: Number of datapoints processed this sync. Present when status is `complete`.
        groups_created:
          type: integer
          description: Number of new task groups created this sync. Present when status is `complete`.
        groups_expanded:
          type: integer
          description: |-
            Number of existing task groups grown this sync. Non-zero only for predetermined-grouping
            batches; always `0` for tasks-per-group batches. Present when status is `complete`.
        reason:
          type: string
          description: Human-readable reason for failure. Present when status is `failed`.
      required:
        - batch_id
        - dataset_id
        - sync_id
        - created_at
        - updated_at
        - status
      description: |-
        Tracks the asynchronous materialisation of tasks for datapoints appended to a batch's dataset
        since setup or the last sync. Created by `POST /batches/{batch_id}/sync`; poll
        `GET /batches/{batch_id}/syncs/{sync_id}` until a terminal status (`complete` or `failed`).

        The shape depends on `status`: the fields below marked as terminal-only are present only for
        the corresponding status.
      title: SyncJob
    SyncTaskBuilderBatchRequestBadRequestError:
      type: object
      properties:
        message:
          type: string
          description: Human-readable reason the batch cannot be synced.
        detail:
          type: string
          description: Additional context, when available.
      title: SyncTaskBuilderBatchRequestBadRequestError
    ApiV1DataCollectionBatchesBatchIdStatusGetResponsesContentApplicationJsonSchemaStatus:
      type: string
      enum:
        - UNINITIALISED
        - PROCESSING
        - READY
        - ERROR
      description: The status of the Batch - one of 'UNINITIALISED', 'PROCESSING', 'READY', 'ERROR'
      title: ApiV1DataCollectionBatchesBatchIdStatusGetResponsesContentApplicationJsonSchemaStatus
    AI Task Builder_GetTaskBuilderBatchStatus_Response_200:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ApiV1DataCollectionBatchesBatchIdStatusGetResponsesContentApplicationJsonSchemaStatus'
          description: The status of the Batch - one of 'UNINITIALISED', 'PROCESSING', 'READY', 'ERROR'
      title: AI Task Builder_GetTaskBuilderBatchStatus_Response_200
    AI Task Builder_SetupTaskBuilderBatch_Response_202:
      type: object
      properties: {}
      description: Empty response body
      title: AI Task Builder_SetupTaskBuilderBatch_Response_202
    AiTaskBuilderTaskResponseResponseType:
      type: string
      enum:
        - multiple_choice
        - free_text
        - free_text_with_unit
        - multiple_choice_with_free_text
        - file_upload
      title: AiTaskBuilderTaskResponseResponseType
    AiTaskBuilderTaskResponseResponseAnswerItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      title: AiTaskBuilderTaskResponseResponseAnswerItemsValue
    AiTaskBuilderTaskResponseResponseAnswerItems:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/AiTaskBuilderTaskResponseResponseAnswerItemsValue'
      description: The participant's answer value
      title: AiTaskBuilderTaskResponseResponseAnswerItems
    AiTaskBuilderTaskResponseResponse:
      type: object
      properties:
        instruction_id:
          type: string
        type:
          $ref: '#/components/schemas/AiTaskBuilderTaskResponseResponseType'
        answer:
          type: array
          items:
            $ref: '#/components/schemas/AiTaskBuilderTaskResponseResponseAnswerItems'
      required:
        - instruction_id
        - type
        - answer
      title: AiTaskBuilderTaskResponseResponse
    AITaskBuilderTaskResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        batch_id:
          type: string
        participant_id:
          type: string
        submission_id:
          type: string
          description: The Prolific submission ID
        correlation_id:
          type: string
          description: Correlation ID for tracking
        response:
          $ref: '#/components/schemas/AiTaskBuilderTaskResponseResponse'
        task_id:
          type: string
        metadata:
          type: object
          additionalProperties:
            description: Any type
        schema_version:
          type: integer
        no_submission:
          type: boolean
      required:
        - id
        - created_at
        - batch_id
        - participant_id
        - response
        - task_id
      title: AITaskBuilderTaskResponse
    ApiV1DataCollectionBatchesBatchIdResponsesGetResponsesContentApplicationJsonSchemaMeta:
      type: object
      properties:
        count:
          type: integer
          description: Total number of responses
      title: ApiV1DataCollectionBatchesBatchIdResponsesGetResponsesContentApplicationJsonSchemaMeta
    AI Task Builder_GetTaskBuilderBatchTaskResponses_Response_200:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/AITaskBuilderTaskResponse'
        meta:
          $ref: '#/components/schemas/ApiV1DataCollectionBatchesBatchIdResponsesGetResponsesContentApplicationJsonSchemaMeta'
      title: AI Task Builder_GetTaskBuilderBatchTaskResponses_Response_200
    ApiV1DataCollectionBatchesBatchIdReportGetResponsesContentApplicationJsonSchemaHttpMethod:
      type: string
      enum:
        - GET
      description: HTTP method to use with the presigned URL
      title: ApiV1DataCollectionBatchesBatchIdReportGetResponsesContentApplicationJsonSchemaHttpMethod
    AI Task Builder_GetTaskBuilderBatchReport_Response_200:
      type: object
      properties:
        url:
          type: string
          description: Presigned URL to download the CSV report
        expires_at:
          type: string
          format: date-time
          description: When the presigned URL expires
        http_method:
          $ref: >-
            #/components/schemas/ApiV1DataCollectionBatchesBatchIdReportGetResponsesContentApplicationJsonSchemaHttpMethod
          description: HTTP method to use with the presigned URL
      title: AI Task Builder_GetTaskBuilderBatchReport_Response_200
    BatchExportCompleteStatus:
      type: string
      enum:
        - complete
      title: BatchExportCompleteStatus
    BatchExportComplete:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/BatchExportCompleteStatus'
        url:
          type: string
          format: uri
          description: >-
            Presigned HTTPS URL for downloading the ZIP archive. Valid for 1 hour. Re-poll to get a refreshed URL if
            expired.
        expires_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp indicating when the presigned URL expires.
      required:
        - status
        - url
        - expires_at
      description: An export job that has completed successfully. The ZIP archive is ready to download.
      title: BatchExportComplete
    BatchExportStatusOneOf0Status:
      type: string
      enum:
        - generating
      title: BatchExportStatusOneOf0Status
    BatchExportStatus0:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/BatchExportStatusOneOf0Status'
        export_id:
          type: string
          format: uuid
          description: The export job ID. Use this with `GET /batches/{batch_id}/export/{export_id}` to poll for status.
      required:
        - status
        - export_id
      description: An export job that has been enqueued and is currently being generated.
      title: BatchExportStatus0
    BatchExportStatusOneOf1Status:
      type: string
      enum:
        - complete
      title: BatchExportStatusOneOf1Status
    BatchExportStatus1:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/BatchExportStatusOneOf1Status'
        url:
          type: string
          format: uri
          description: >-
            Presigned HTTPS URL for downloading the ZIP archive. Valid for 1 hour. Re-poll to get a refreshed URL if
            expired.
        expires_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp indicating when the presigned URL expires.
      required:
        - status
        - url
        - expires_at
      description: An export job that has completed successfully. The ZIP archive is ready to download.
      title: BatchExportStatus1
    BatchExportStatusOneOf2Status:
      type: string
      enum:
        - failed
      title: BatchExportStatusOneOf2Status
    BatchExportStatus2:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/BatchExportStatusOneOf2Status'
      required:
        - status
      description: >-
        An export job that failed to generate, or whose archive has since been deleted. Re-send `POST
        /batches/{batch_id}/export` to retry.
      title: BatchExportStatus2
    BatchExportStatus:
      oneOf:
        - $ref: '#/components/schemas/BatchExportStatus0'
        - $ref: '#/components/schemas/BatchExportStatus1'
        - $ref: '#/components/schemas/BatchExportStatus2'
      description: The current status of a batch export job.
      title: BatchExportStatus
    DatasetSchemaFieldType:
      type: string
      enum:
        - text
        - image_url
        - metadata
        - task_group_id
      description: >-
        Field type:

        - `text` — a text value shown to participants. Can be referenced by `dataset_field` items in `batch_items`.

        - `image_url` — a URL pointing to an image shown to participants. Can be referenced by `dataset_field` items in
        `batch_items`.

        - `metadata` — an internal value included in exports but not shown to participants (equivalent to the `META_`
        prefix in V3 CSV datasets).

        - `task_group_id` — groups datapoints into task groups. Rows with the same `task_group_id` value are assigned to
        the same participant. Equivalent to `META_TASK_GROUP_ID` in V3 CSV datasets. At most one field per schema may
        have this type.
      title: DatasetSchemaFieldType
    DatasetSchemaField:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/DatasetSchemaFieldType'
          description: >-
            Field type:

            - `text` — a text value shown to participants. Can be referenced by `dataset_field` items in `batch_items`.

            - `image_url` — a URL pointing to an image shown to participants. Can be referenced by `dataset_field` items
            in `batch_items`.

            - `metadata` — an internal value included in exports but not shown to participants (equivalent to the
            `META_` prefix in V3 CSV datasets).

            - `task_group_id` — groups datapoints into task groups. Rows with the same `task_group_id` value are
            assigned to the same participant. Equivalent to `META_TASK_GROUP_ID` in V3 CSV datasets. At most one field
            per schema may have this type.
        label:
          type: string
          description: Optional human-readable label for the field, used in the participant interface.
      required:
        - type
      description: Descriptor for a single field in a dataset schema.
      title: DatasetSchemaField
    DatasetSchema:
      type: object
      properties:
        strict:
          type: boolean
          description: >-
            When `true`, records that are missing any field defined in the schema are rejected during import. When
            `false`, missing fields are allowed and treated as absent.
        fields:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DatasetSchemaField'
          description: >-
            A map of field key to field descriptor. The key is used to reference the field in `batch_items`
            (`dataset_field` items) and in JSONL records.
      required:
        - strict
        - fields
      description: >-
        A researcher-defined schema that specifies the fields in a V4 dataset. Each field has a type that determines how
        it is rendered to participants and how it can be referenced in `batch_items`.


        Constraints:

        - Maximum 200 fields per schema.

        - Field keys: 1–128 characters.

        - Field labels: maximum 255 characters.
      title: DatasetSchema
    AiTaskBuilderDatasetSchemaVersion:
      type: string
      enum:
        - '3'
        - '4'
      description: Internal dataset version. 3 = legacy CSV/ZIP; 4 = structured schema with JSONL/CSV import tracking.
      title: AiTaskBuilderDatasetSchemaVersion
    AiTaskBuilderDatasetStatus:
      type: string
      enum:
        - ERROR
        - PROCESSING
        - READY
        - UNINITIALISED
      description: Processing status. **V3 datasets only.** V4 datasets track status per import job via `imports`.
      title: AiTaskBuilderDatasetStatus
    DatasetImportJobType:
      type: string
      enum:
        - file_upload
      description: The type of import. Currently always `file_upload`.
      title: DatasetImportJobType
    DatasetImportJobStatus:
      type: string
      enum:
        - uninitialised
        - queued
        - processing
        - complete
        - partial
        - failed
        - pending_schema
      description: Current status of the import job.
      title: DatasetImportJobStatus
    ImportJobError:
      type: object
      properties:
        record_index:
          type:
            - integer
            - 'null'
          description: Zero-based index of the rejected record in the uploaded file.
        field:
          type:
            - string
            - 'null'
          description: >-
            The schema field key that caused the rejection, or `null` if no specific field is implicated.

            The special value `_raw` indicates a whole-record parse failure (e.g. malformed JSON) rather than a
            field-level error.
        reason:
          type:
            - string
            - 'null'
          description: Human-readable description of why the record was rejected.
      description: A record-level validation error from a partial import.
      title: ImportJobError
    DatasetImportJob:
      type: object
      properties:
        dataset_id:
          type: string
          format: uuid
          description: The dataset this import job belongs to.
        import_id:
          type: string
          format: uuid
          description: The unique identifier of the import job.
        type:
          $ref: '#/components/schemas/DatasetImportJobType'
          description: The type of import. Currently always `file_upload`.
        filename:
          type:
            - string
            - 'null'
          description: The original filename supplied when the upload URL was requested.
        created_at:
          type: string
          format: date-time
          description: When the import job was created (ISO 8601, UTC).
        updated_at:
          type: string
          format: date-time
          description: When the import job was last updated (ISO 8601, UTC).
        status:
          $ref: '#/components/schemas/DatasetImportJobStatus'
          description: Current status of the import job.
        accepted_count:
          type: integer
          description: Number of records successfully ingested. Present when status is `complete` or `partial`.
        rejected_count:
          type: integer
          description: Number of records rejected. Present when status is `partial`.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ImportJobError'
          description: Record-level validation errors. Present when status is `partial`.
        reason:
          type: string
          description: Human-readable reason for failure. Present when status is `failed`.
      required:
        - dataset_id
        - import_id
        - type
        - created_at
        - updated_at
        - status
      description: >-
        Tracks the lifecycle of a single file upload to a V4 dataset.


        An import job is created when `GET /datasets/{dataset_id}/upload-url/{filename}` is called. It transitions
        through the following statuses:


        | Status | Meaning |

        |---|---|

        | `uninitialised` | Import job created; file not yet uploaded to S3 |

        | `queued` | File uploaded; queued for extraction |

        | `processing` | Extraction in progress |

        | `complete` | All records accepted |

        | `partial` | Some records accepted, some rejected — see `errors` |

        | `failed` | Extraction failed entirely — see `reason` |

        | `pending_schema` | Dataset has no schema; upload paused until schema is set |


        Poll `GET /datasets/{dataset_id}/imports/{import_id}` until a terminal status is reached (`complete`, `partial`,
        `failed`, or `pending_schema`).
      title: DatasetImportJob
    AITaskBuilderDataset:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        workspace_id:
          type: string
        total_datapoint_count:
          type: integer
        schema_version:
          $ref: '#/components/schemas/AiTaskBuilderDatasetSchemaVersion'
          description: Internal dataset version. 3 = legacy CSV/ZIP; 4 = structured schema with JSONL/CSV import tracking.
        status:
          $ref: '#/components/schemas/AiTaskBuilderDatasetStatus'
          description: Processing status. **V3 datasets only.** V4 datasets track status per import job via `imports`.
        filename:
          type:
            - string
            - 'null'
          description: Filename of the uploaded data file. **V3 datasets only.**
        has_predetermined_grouping_id:
          type:
            - boolean
            - 'null'
          description: Whether the dataset contains a `META_TASK_GROUP_ID` column. **V3 datasets only.**
        schema:
          oneOf:
            - $ref: '#/components/schemas/DatasetSchema'
            - type: 'null'
          description: |-
            The researcher-defined field schema for this dataset. **V4 datasets only.**
            `null` if no schema has been set yet.
        imports:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/DatasetImportJob'
          description: Import jobs for this dataset, most recent first. **V4 datasets only.** `null` for V3 datasets.
      required:
        - id
        - name
        - created_at
        - created_by
        - workspace_id
        - total_datapoint_count
        - schema_version
      description: >-
        An AI Task Builder dataset. The shape of the response varies by `schema_version`:


        - **V3 datasets** include `status`, `filename`, and `has_predetermined_grouping_id`.

        - **V4 datasets** include `schema` (the researcher-defined field schema, or `null` if not yet set) and `imports`
        (the list of import jobs for this dataset). V4 datasets do not include `status` or `filename`.
      title: AITaskBuilderDataset
    ApiV1DataCollectionDatasetsDatasetIdPatchResponsesContentApplicationJsonSchemaSchemaVersion:
      type: string
      enum:
        - '3'
        - '4'
      description: Internal dataset version. 3 = legacy CSV/ZIP; 4 = structured schema with JSONL/CSV import tracking.
      title: ApiV1DataCollectionDatasetsDatasetIdPatchResponsesContentApplicationJsonSchemaSchemaVersion
    ApiV1DataCollectionDatasetsDatasetIdPatchResponsesContentApplicationJsonSchemaStatus:
      type: string
      enum:
        - ERROR
        - PROCESSING
        - READY
        - UNINITIALISED
      description: Processing status. **V3 datasets only.** V4 datasets track status per import job via `imports`.
      title: ApiV1DataCollectionDatasetsDatasetIdPatchResponsesContentApplicationJsonSchemaStatus
    AI Task Builder_UpdateTaskBuilderDataset_Response_200:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        workspace_id:
          type: string
        total_datapoint_count:
          type: integer
        schema_version:
          $ref: >-
            #/components/schemas/ApiV1DataCollectionDatasetsDatasetIdPatchResponsesContentApplicationJsonSchemaSchemaVersion
          description: Internal dataset version. 3 = legacy CSV/ZIP; 4 = structured schema with JSONL/CSV import tracking.
        status:
          $ref: '#/components/schemas/ApiV1DataCollectionDatasetsDatasetIdPatchResponsesContentApplicationJsonSchemaStatus'
          description: Processing status. **V3 datasets only.** V4 datasets track status per import job via `imports`.
        filename:
          type:
            - string
            - 'null'
          description: Filename of the uploaded data file. **V3 datasets only.**
        has_predetermined_grouping_id:
          type:
            - boolean
            - 'null'
          description: Whether the dataset contains a `META_TASK_GROUP_ID` column. **V3 datasets only.**
        schema:
          oneOf:
            - $ref: '#/components/schemas/DatasetSchema'
            - type: 'null'
          description: |-
            The researcher-defined field schema for this dataset. **V4 datasets only.**
            `null` if no schema has been set yet.
        imports:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/DatasetImportJob'
          description: Import jobs for this dataset, most recent first. **V4 datasets only.** `null` for V3 datasets.
        migration_job_id:
          type: string
          format: uuid
          description: |-
            The schema migration job started by this update. Present only when the
            dataset already had a schema (i.e. the schema was changed, not set for the
            first time). Use with `GET /datasets/{dataset_id}/schema-migrations/{job_id}`.
      required:
        - id
        - name
        - created_at
        - created_by
        - workspace_id
        - total_datapoint_count
        - schema_version
      description: >-
        An AI Task Builder dataset. The shape of the response varies by `schema_version`:


        - **V3 datasets** include `status`, `filename`, and `has_predetermined_grouping_id`.

        - **V4 datasets** include `schema` (the researcher-defined field schema, or `null` if not yet set) and `imports`
        (the list of import jobs for this dataset). V4 datasets do not include `status` or `filename`.
      title: AI Task Builder_UpdateTaskBuilderDataset_Response_200
    ApiV1DataCollectionDatasetsDatasetIdUploadUrlFilenameGetResponsesContentApplicationJsonSchemaHttpMethod:
      type: string
      enum:
        - PUT
      description: HTTP method to use with the presigned URL.
      title: ApiV1DataCollectionDatasetsDatasetIdUploadUrlFilenameGetResponsesContentApplicationJsonSchemaHttpMethod
    AI Task Builder_getDatasetUploadUrl_Response_201:
      type: object
      properties:
        dataset_id:
          type: string
          format: uuid
          description: The ID of the dataset the upload URL was requested for.
        upload_url:
          type: string
          description: Presigned S3 URL. Make a PUT request to this URL with your file as the body.
        http_method:
          $ref: >-
            #/components/schemas/ApiV1DataCollectionDatasetsDatasetIdUploadUrlFilenameGetResponsesContentApplicationJsonSchemaHttpMethod
          description: HTTP method to use with the presigned URL.
        content_type:
          type: string
          description: |-
            The `Content-Type` header value to use when making the S3 PUT request.
            Use this value exactly — e.g. `application/x-ndjson` for JSONL files.
        expires_at:
          type: string
          format: date-time
          description: When the presigned URL expires (ISO 8601, UTC). The URL cannot be used after this time.
        file_key:
          type: string
          description: The S3 object key for the uploaded file. Provided for reference only.
        import_id:
          type: string
          format: uuid
          description: >-
            Import job ID. **V4 datasets only.** Use with `GET /datasets/{dataset_id}/imports/{import_id}` to poll for
            upload and processing status.
      required:
        - dataset_id
        - upload_url
        - http_method
        - content_type
        - expires_at
      title: AI Task Builder_getDatasetUploadUrl_Response_201
    DatasetAppendError:
      type: object
      properties:
        record_index:
          type: integer
          description: One-based index of the rejected non-blank JSONL record in the append request body.
        field:
          type: string
          description: |-
            The schema field key that caused the rejection. The special value `_raw` indicates a
            whole-record parse failure (for example malformed JSON) rather than a field-level error.
        reason:
          type: string
          description: Human-readable description of why the record was rejected.
      required:
        - record_index
        - field
        - reason
      description: A record-level validation error from a synchronous JSONL append request.
      title: DatasetAppendError
    DatasetAppendResult:
      type: object
      properties:
        accepted:
          type: integer
          description: Number of records that passed validation (newly written or idempotent duplicates).
        rejected:
          type: integer
          description: Number of records rejected. Equal to the length of `errors`.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/DatasetAppendError'
          description: Record-level rejections. Empty when every record was accepted.
      required:
        - accepted
        - rejected
        - errors
      description: |-
        Result of a synchronous append to a V4 dataset (`POST /datasets/{dataset_id}/datapoints`).
        `accepted` counts records that passed validation (newly written plus idempotent duplicates);
        `rejected` counts records that failed parsing or schema validation, each detailed in `errors`.
      title: DatasetAppendResult
    SchemaMigrationJobStatus:
      type: string
      enum:
        - processing
        - complete
        - partial
        - failed
      description: Current status of the migration job.
      title: SchemaMigrationJobStatus
    SchemaMigrationError:
      type: object
      properties:
        datapoint_id:
          type: string
          format: uuid
          description: The datapoint whose field could not be re-normalised.
        field:
          type: string
          description: The schema field key that was nulled.
        reason:
          type: string
          description: Human-readable description of why the field was nulled.
      required:
        - datapoint_id
        - field
        - reason
      description: A single record-level failure — a field that was invalid under the new schema and so was nulled.
      title: SchemaMigrationError
    SchemaMigrationJob:
      type: object
      properties:
        dataset_id:
          type: string
          format: uuid
          description: The dataset being migrated.
        job_id:
          type: string
          format: uuid
          description: The unique identifier of the schema migration job.
        schema_version:
          type: integer
          description: The schema version this job reprocesses datapoints up to.
        created_at:
          type: string
          format: date-time
          description: When the migration job was created (ISO 8601, UTC).
        updated_at:
          type: string
          format: date-time
          description: When the migration job was last updated (ISO 8601, UTC).
        status:
          $ref: '#/components/schemas/SchemaMigrationJobStatus'
          description: Current status of the migration job.
        reprocessed_count:
          type: integer
          description: Number of datapoints reprocessed. Present when status is `complete` or `partial`.
        failed_count:
          type: integer
          description: >-
            Number of datapoints with at least one field that could not be re-normalised. Present when status is
            `partial`.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/SchemaMigrationError'
          description: >-
            Record-level failures — fields nulled because they were invalid under the new schema. Present when status is
            `partial`.
        reason:
          type: string
          description: Human-readable reason for failure. Present when status is `failed`.
      required:
        - dataset_id
        - job_id
        - schema_version
        - created_at
        - updated_at
        - status
      description: |-
        Tracks the asynchronous re-normalisation of a V4 dataset's datapoints against a newer schema
        version. Poll `GET /datasets/{dataset_id}/schema-migrations/{job_id}` until a terminal
        status (`complete`, `partial`, or `failed`).

        The shape depends on `status`: the fields below marked as terminal-only are present only for
        the corresponding status.
      title: SchemaMigrationJob
    ApiV1DataCollectionDatasetsDatasetIdStatusGetResponsesContentApplicationJsonSchemaStatus:
      type: string
      enum:
        - UNINITIALISED
        - PROCESSING
        - READY
        - ERROR
      description: The status of the Dataset - one of 'UNINITIALISED', 'PROCESSING', 'READY', 'ERROR'
      title: ApiV1DataCollectionDatasetsDatasetIdStatusGetResponsesContentApplicationJsonSchemaStatus
    AI Task Builder_GetTaskBuilderDatasetStatus_Response_200:
      type: object
      properties:
        status:
          $ref: >-
            #/components/schemas/ApiV1DataCollectionDatasetsDatasetIdStatusGetResponsesContentApplicationJsonSchemaStatus
          description: The status of the Dataset - one of 'UNINITIALISED', 'PROCESSING', 'READY', 'ERROR'
      title: AI Task Builder_GetTaskBuilderDatasetStatus_Response_200
    AiTaskBuilderMultipleChoiceInstructionType:
      type: string
      enum:
        - multiple_choice
      title: AiTaskBuilderMultipleChoiceInstructionType
    AiTaskBuilderMultipleChoiceInstructionParentType:
      type: string
      enum:
        - batch
        - collection
      title: AiTaskBuilderMultipleChoiceInstructionParentType
    AiTaskBuilderMultipleChoiceInstructionOptionsItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      description: Value returned in responses
      title: AiTaskBuilderMultipleChoiceInstructionOptionsItemsValue
    AiTaskBuilderMultipleChoiceInstructionOptionsItems:
      type: object
      properties:
        label:
          type: string
          description: Display text shown to participants
        value:
          $ref: '#/components/schemas/AiTaskBuilderMultipleChoiceInstructionOptionsItemsValue'
          description: Value returned in responses
        exclusive:
          type: boolean
          description: When true, selecting this option deselects all other options. Useful for "None of the above" style options.
      required:
        - label
        - value
      title: AiTaskBuilderMultipleChoiceInstructionOptionsItems
    AiTaskBuilderFreeTextInputInstructionType:
      type: string
      enum:
        - free_text
      title: AiTaskBuilderFreeTextInputInstructionType
    AiTaskBuilderFreeTextInputInstructionParentType:
      type: string
      enum:
        - batch
        - collection
      title: AiTaskBuilderFreeTextInputInstructionParentType
    AiTaskBuilderFreeTextWithUnitInstructionType:
      type: string
      enum:
        - free_text_with_unit
      title: AiTaskBuilderFreeTextWithUnitInstructionType
    AiTaskBuilderFreeTextWithUnitInstructionParentType:
      type: string
      enum:
        - batch
        - collection
      title: AiTaskBuilderFreeTextWithUnitInstructionParentType
    AiTaskBuilderFreeTextWithUnitInstructionUnitOptionsItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      description: Value returned in responses
      title: AiTaskBuilderFreeTextWithUnitInstructionUnitOptionsItemsValue
    AiTaskBuilderFreeTextWithUnitInstructionUnitOptionsItems:
      type: object
      properties:
        label:
          type: string
          description: Display text shown to participants
        value:
          $ref: '#/components/schemas/AiTaskBuilderFreeTextWithUnitInstructionUnitOptionsItemsValue'
          description: Value returned in responses
        validation:
          $ref: '#/components/schemas/ValidationRule'
          description: Optional validation constraints for this unit option
      required:
        - label
        - value
      title: AiTaskBuilderFreeTextWithUnitInstructionUnitOptionsItems
    AiTaskBuilderFreeTextWithUnitInstructionUnitPosition:
      type: string
      enum:
        - prefix
        - suffix
      description: >-
        Position of the unit selector relative to the text input. Use 'prefix' for units before the input (e.g.,
        currency symbols) or 'suffix' for units after the input (e.g., measurements).
      title: AiTaskBuilderFreeTextWithUnitInstructionUnitPosition
    AiTaskBuilderMultipleChoiceWithFreeTextInstructionType:
      type: string
      enum:
        - multiple_choice_with_free_text
      title: AiTaskBuilderMultipleChoiceWithFreeTextInstructionType
    AiTaskBuilderMultipleChoiceWithFreeTextInstructionParentType:
      type: string
      enum:
        - batch
        - collection
      title: AiTaskBuilderMultipleChoiceWithFreeTextInstructionParentType
    AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      description: Value returned in responses
      title: AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItemsValue
    AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItems:
      type: object
      properties:
        label:
          type: string
          description: Display text shown to participants
        value:
          $ref: '#/components/schemas/AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItemsValue'
          description: Value returned in responses
        heading:
          type: string
          description: Section heading that groups this option
        exclusive:
          type: boolean
          description: When true, selecting this option deselects all other options. Useful for "None of the above" style options.
      required:
        - label
        - value
        - heading
      title: AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItems
    AiTaskBuilderFileUploadInstructionType:
      type: string
      enum:
        - file_upload
      title: AiTaskBuilderFileUploadInstructionType
    AiTaskBuilderFileUploadInstructionParentType:
      type: string
      enum:
        - batch
        - collection
      title: AiTaskBuilderFileUploadInstructionParentType
    AITaskBuilderInstruction:
      oneOf:
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/AiTaskBuilderMultipleChoiceInstructionType'
            id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
            parent_id:
              type: string
              format: uuid
              description: ID of the parent batch or collection
            parent_type:
              $ref: '#/components/schemas/AiTaskBuilderMultipleChoiceInstructionParentType'
            created_by:
              type: string
            description:
              type: string
              description: The question or prompt displayed to participants
            helper_text:
              type: string
              description: Additional guidance text displayed below the question
            placeholder_text_input:
              type: string
              description: Placeholder text displayed in the input field
            answer_limit:
              type: integer
              description: >-
                Number of options that can be selected. Use 1 for single-select, -1 for unlimited, or any number up to
                the total options.
            disable_dropdown:
              type: boolean
              default: false
              description: >-
                When true, always renders checkbox/radio elements instead of a dropdown select, regardless of option
                count. By default, a dropdown is used when there are 5 or more options.
            options:
              type: array
              items:
                $ref: '#/components/schemas/AiTaskBuilderMultipleChoiceInstructionOptionsItems'
          required:
            - type
            - id
            - created_at
            - parent_id
            - parent_type
            - created_by
            - description
            - answer_limit
            - options
          description: multiple_choice variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/AiTaskBuilderFreeTextInputInstructionType'
            id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
            parent_id:
              type: string
              format: uuid
              description: ID of the parent batch or collection
            parent_type:
              $ref: '#/components/schemas/AiTaskBuilderFreeTextInputInstructionParentType'
            created_by:
              type: string
            description:
              type: string
              description: The question or prompt displayed to participants
            helper_text:
              type: string
              description: Additional guidance text displayed below the question
            placeholder_text_input:
              type: string
              description: Placeholder text displayed in the input field
            validation:
              $ref: '#/components/schemas/ValidationRule'
              description: Optional validation constraints for the input value
          required:
            - type
            - id
            - created_at
            - parent_id
            - parent_type
            - created_by
            - description
          description: free_text variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/AiTaskBuilderFreeTextWithUnitInstructionType'
            id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
            parent_id:
              type: string
              format: uuid
              description: ID of the parent batch or collection
            parent_type:
              $ref: '#/components/schemas/AiTaskBuilderFreeTextWithUnitInstructionParentType'
            created_by:
              type: string
            description:
              type: string
              description: The question or prompt displayed to participants
            helper_text:
              type: string
              description: Additional guidance text displayed below the question
            placeholder_text_input:
              type: string
              description: Placeholder text displayed in the input field
            unit_options:
              type: array
              items:
                $ref: '#/components/schemas/AiTaskBuilderFreeTextWithUnitInstructionUnitOptionsItems'
              description: List of available units that participants can select from
            default_unit:
              type: string
              description: Default selected unit (must match a value from unit_options)
            unit_position:
              $ref: '#/components/schemas/AiTaskBuilderFreeTextWithUnitInstructionUnitPosition'
              description: >-
                Position of the unit selector relative to the text input. Use 'prefix' for units before the input (e.g.,
                currency symbols) or 'suffix' for units after the input (e.g., measurements).
          required:
            - type
            - id
            - created_at
            - parent_id
            - parent_type
            - created_by
            - description
            - unit_options
            - unit_position
          description: free_text_with_unit variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/AiTaskBuilderMultipleChoiceWithFreeTextInstructionType'
            id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
            parent_id:
              type: string
              format: uuid
              description: ID of the parent batch or collection
            parent_type:
              $ref: '#/components/schemas/AiTaskBuilderMultipleChoiceWithFreeTextInstructionParentType'
            created_by:
              type: string
            description:
              type: string
              description: The question or prompt displayed to participants
            helper_text:
              type: string
              description: Additional guidance text displayed below the question
            placeholder_text_input:
              type: string
              description: Placeholder text displayed in the input field
            answer_limit:
              type: integer
              description: >-
                Number of options that can be selected. Use 1 for single-select, -1 for unlimited, or any number up to
                the total options.
            disable_dropdown:
              type: boolean
              default: false
              description: >-
                When true, always renders checkbox/radio elements instead of a dropdown select, regardless of option
                count. By default, a dropdown is used when there are 5 or more options.
            options:
              type: array
              items:
                $ref: '#/components/schemas/AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItems'
          required:
            - type
            - id
            - created_at
            - parent_id
            - parent_type
            - created_by
            - description
            - answer_limit
            - options
          description: multiple_choice_with_free_text variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/AiTaskBuilderFileUploadInstructionType'
            id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
            parent_id:
              type: string
              format: uuid
              description: ID of the parent batch or collection
            parent_type:
              $ref: '#/components/schemas/AiTaskBuilderFileUploadInstructionParentType'
            created_by:
              type: string
            description:
              type: string
              description: The prompt describing what to upload
            helper_text:
              type: string
              description: Additional guidance text displayed below the question
            placeholder_text_input:
              type: string
              description: Placeholder text displayed in the input field
            accepted_file_types:
              type: array
              items:
                type: string
              description: >-
                File extensions to accept (e.g., [".jpg", ".png", ".pdf"]). Each extension must start with a dot.
                Defaults to [".jpg", ".jpeg", ".png", ".heic", ".heif"] if not specified.
            max_file_size_mb:
              type: number
              format: double
              description: Maximum file size in megabytes per file. Must be a positive number. Defaults to 25.
            min_file_count:
              type: integer
              description: Minimum number of files required. Must be at least 1. Defaults to 1.
            max_file_count:
              type: integer
              description: >-
                Maximum number of files allowed. Must be at least 1 and greater than or equal to min_file_count.
                Defaults to 10.
          required:
            - type
            - id
            - created_at
            - parent_id
            - parent_type
            - created_by
            - description
          description: file_upload variant
      discriminator:
        propertyName: type
      title: AITaskBuilderInstruction
    ApiV1DataCollectionBatchesBatchIdInstructionsGetResponsesContentApplicationJsonSchemaMeta:
      type: object
      properties:
        count:
          type: integer
          description: Total number of instructions
      title: ApiV1DataCollectionBatchesBatchIdInstructionsGetResponsesContentApplicationJsonSchemaMeta
    AI Task Builder_GetTaskBuilderInstructions_Response_200:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/AITaskBuilderInstruction'
        meta:
          $ref: >-
            #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsGetResponsesContentApplicationJsonSchemaMeta
      title: AI Task Builder_GetTaskBuilderInstructions_Response_200
    ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsType:
      type: string
      enum:
        - multiple_choice
        - free_text
        - free_text_with_unit
        - multiple_choice_with_free_text
        - file_upload
      description: The type of instruction.
      title: ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsType
    ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems:
      type: object
      properties:
        label:
          type: string
          description: The display label for the option.
        value:
          type: string
          description: The value associated with the option.
        heading:
          type: string
          description: The heading for the option (required for multiple_choice_with_free_text).
      required:
        - label
        - value
      title: >-
        ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems
    ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      description: The value associated with the unit.
      title: >-
        ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItemsValue
    ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItems:
      type: object
      properties:
        label:
          type: string
          description: The display label for the unit.
        value:
          $ref: >-
            #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItemsValue
          description: The value associated with the unit.
        validation:
          $ref: '#/components/schemas/ValidationRule'
          description: Optional validation constraints for this unit option.
      required:
        - label
        - value
      title: >-
        ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItems
    ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitPosition:
      type: string
      enum:
        - prefix
        - suffix
      description: >-
        Required for free_text_with_unit. Position of the unit selector relative to the text input. Use 'prefix' for
        units before the input (e.g., currency symbols) or 'suffix' for units after the input (e.g., measurements).
      title: >-
        ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitPosition
    ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItems:
      type: object
      properties:
        type:
          $ref: >-
            #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsType
          description: The type of instruction.
        description:
          type: string
          description: The question or prompt displayed to participants.
        helper_text:
          type: string
          description: Additional guidance text displayed below the question.
        placeholder_text_input:
          type: string
          description: Placeholder text displayed in the input field.
        answer_limit:
          type: integer
          description: >-
            Number of options that can be selected (required for multiple_choice and multiple_choice_with_free_text).
            Use 1 for single-select, -1 for unlimited.
        disable_dropdown:
          type: boolean
          default: false
          description: >-
            When true, always renders checkbox/radio elements instead of a dropdown select. By default, a dropdown is
            used when there are 5 or more options.
        options:
          type: array
          items:
            $ref: >-
              #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems
          description: The options (required for multiple_choice and multiple_choice_with_free_text).
        unit_options:
          type: array
          items:
            $ref: >-
              #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItems
          description: >-
            The unit options (required for free_text_with_unit). List of available units that participants can select
            from.
        default_unit:
          type: string
          description: For free_text_with_unit. Default selected unit (must match a value from unit_options).
        unit_position:
          $ref: >-
            #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitPosition
          description: >-
            Required for free_text_with_unit. Position of the unit selector relative to the text input. Use 'prefix' for
            units before the input (e.g., currency symbols) or 'suffix' for units after the input (e.g., measurements).
        validation:
          $ref: '#/components/schemas/ValidationRule'
          description: Optional validation constraints for the input value (for free_text).
      required:
        - type
        - description
      title: ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItems
    ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsType:
      type: string
      enum:
        - multiple_choice
        - free_text
        - free_text_with_unit
        - multiple_choice_with_free_text
        - file_upload
      description: The type of instruction.
      title: ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsType
    ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems:
      type: object
      properties:
        label:
          type: string
          description: The display text for the option.
        value:
          type: string
          description: The value associated with the option.
        heading:
          type: string
          description: The heading for the option (required for multiple_choice_with_free_text).
      required:
        - label
        - value
      title: >-
        ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems
    ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      description: The value associated with the unit.
      title: >-
        ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItemsValue
    ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItems:
      type: object
      properties:
        label:
          type: string
          description: The display label for the unit.
        value:
          $ref: >-
            #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItemsValue
          description: The value associated with the unit.
        validation:
          $ref: '#/components/schemas/ValidationRule'
          description: Optional validation constraints for this unit option.
      required:
        - label
        - value
      title: >-
        ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItems
    ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitPosition:
      type: string
      enum:
        - prefix
        - suffix
      description: >-
        Required for free_text_with_unit. Position of the unit selector relative to the text input. Use 'prefix' for
        units before the input (e.g., currency symbols) or 'suffix' for units after the input (e.g., measurements).
      title: >-
        ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitPosition
    ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItems:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Include to preserve an existing instruction.
        type:
          $ref: >-
            #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsType
          description: The type of instruction.
        description:
          type: string
          description: The question or prompt displayed to participants.
        helper_text:
          type: string
          description: Additional guidance text displayed below the question.
        placeholder_text_input:
          type: string
          description: Placeholder text displayed in the input field.
        answer_limit:
          type: integer
          description: >-
            Number of options that can be selected (required for multiple_choice and multiple_choice_with_free_text).
            Use 1 for single-select, -1 for unlimited.
        disable_dropdown:
          type: boolean
          default: false
          description: When true, always renders checkbox/radio elements instead of a dropdown select.
        options:
          type: array
          items:
            $ref: >-
              #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems
          description: The options (required for multiple_choice and multiple_choice_with_free_text).
        unit_options:
          type: array
          items:
            $ref: >-
              #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItems
          description: >-
            The unit options (required for free_text_with_unit). List of available units that participants can select
            from.
        default_unit:
          type: string
          description: For free_text_with_unit. Default selected unit (must match a value from unit_options).
        unit_position:
          $ref: >-
            #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitPosition
          description: >-
            Required for free_text_with_unit. Position of the unit selector relative to the text input. Use 'prefix' for
            units before the input (e.g., currency symbols) or 'suffix' for units after the input (e.g., measurements).
        validation:
          $ref: '#/components/schemas/ValidationRule'
          description: Optional validation constraints for the input value (for free_text).
      required:
        - type
        - description
      title: ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItems
    CollectionSchemaVersion:
      type: string
      enum:
        - '1'
      title: CollectionSchemaVersion
    TaskDetails:
      type: object
      properties:
        task_name:
          type: string
          description: The title displayed to participants
        task_introduction:
          type: string
          description: HTML formatted introduction shown at the start of the task
        task_steps:
          type: string
          description: HTML formatted step-by-step instructions
      required:
        - task_name
        - task_introduction
        - task_steps
      description: Task metadata displayed to participants
      title: TaskDetails
    CollectionItemSchemaVersion:
      type: string
      enum:
        - '1'
      title: CollectionItemSchemaVersion
    CollectionMultipleChoiceInstructionType:
      type: string
      enum:
        - multiple_choice
      title: CollectionMultipleChoiceInstructionType
    CollectionMultipleChoiceInstructionParentType:
      type: string
      enum:
        - batch
        - collection
      title: CollectionMultipleChoiceInstructionParentType
    CollectionMultipleChoiceInstructionOptionsItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      title: CollectionMultipleChoiceInstructionOptionsItemsValue
    CollectionMultipleChoiceInstructionOptionsItems:
      type: object
      properties:
        label:
          type: string
        value:
          $ref: '#/components/schemas/CollectionMultipleChoiceInstructionOptionsItemsValue'
        exclusive:
          type: boolean
          description: When true, selecting this option deselects all other options. Useful for "None of the above" style options.
      required:
        - label
        - value
      title: CollectionMultipleChoiceInstructionOptionsItems
    CollectionFreeTextInstructionType:
      type: string
      enum:
        - free_text
      title: CollectionFreeTextInstructionType
    CollectionFreeTextInstructionParentType:
      type: string
      enum:
        - batch
        - collection
      title: CollectionFreeTextInstructionParentType
    CollectionFreeTextWithUnitInstructionType:
      type: string
      enum:
        - free_text_with_unit
      title: CollectionFreeTextWithUnitInstructionType
    CollectionFreeTextWithUnitInstructionParentType:
      type: string
      enum:
        - batch
        - collection
      title: CollectionFreeTextWithUnitInstructionParentType
    CollectionFreeTextWithUnitInstructionUnitOptionsItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      description: Value returned in responses
      title: CollectionFreeTextWithUnitInstructionUnitOptionsItemsValue
    CollectionFreeTextWithUnitInstructionUnitOptionsItems:
      type: object
      properties:
        label:
          type: string
          description: Display text shown to participants
        value:
          $ref: '#/components/schemas/CollectionFreeTextWithUnitInstructionUnitOptionsItemsValue'
          description: Value returned in responses
        validation:
          $ref: '#/components/schemas/ValidationRule'
          description: Optional validation constraints for this unit option
      required:
        - label
        - value
      title: CollectionFreeTextWithUnitInstructionUnitOptionsItems
    CollectionFreeTextWithUnitInstructionUnitPosition:
      type: string
      enum:
        - prefix
        - suffix
      description: >-
        Position of the unit selector relative to the text input. Use 'prefix' for units before the input (e.g.,
        currency symbols) or 'suffix' for units after the input (e.g., measurements).
      title: CollectionFreeTextWithUnitInstructionUnitPosition
    CollectionMultipleChoiceWithFreeTextInstructionType:
      type: string
      enum:
        - multiple_choice_with_free_text
      title: CollectionMultipleChoiceWithFreeTextInstructionType
    CollectionMultipleChoiceWithFreeTextInstructionParentType:
      type: string
      enum:
        - batch
        - collection
      title: CollectionMultipleChoiceWithFreeTextInstructionParentType
    CollectionMultipleChoiceWithFreeTextInstructionOptionsItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      title: CollectionMultipleChoiceWithFreeTextInstructionOptionsItemsValue
    CollectionMultipleChoiceWithFreeTextInstructionOptionsItems:
      type: object
      properties:
        label:
          type: string
        value:
          $ref: '#/components/schemas/CollectionMultipleChoiceWithFreeTextInstructionOptionsItemsValue'
        heading:
          type: string
        exclusive:
          type: boolean
          description: When true, selecting this option deselects all other options. Useful for "None of the above" style options.
      required:
        - label
        - value
        - heading
      title: CollectionMultipleChoiceWithFreeTextInstructionOptionsItems
    CollectionFileUploadInstructionType:
      type: string
      enum:
        - file_upload
      title: CollectionFileUploadInstructionType
    CollectionFileUploadInstructionParentType:
      type: string
      enum:
        - batch
        - collection
      title: CollectionFileUploadInstructionParentType
    ImageContentBlockType:
      type: string
      enum:
        - image
      title: ImageContentBlockType
    ImageContentBlockParentType:
      type: string
      enum:
        - collection
        - batch
      title: ImageContentBlockParentType
    ImageContentBlockSchemaVersion:
      type: string
      enum:
        - '1'
      title: ImageContentBlockSchemaVersion
    RichTextContentBlockType:
      type: string
      enum:
        - rich_text
      title: RichTextContentBlockType
    RichTextContentBlockParentType:
      type: string
      enum:
        - collection
        - batch
      title: RichTextContentBlockParentType
    RichTextContentBlockSchemaVersion:
      type: string
      enum:
        - '1'
      title: RichTextContentBlockSchemaVersion
    PageItem:
      oneOf:
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/CollectionMultipleChoiceInstructionType'
            id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
            parent_id:
              type: string
              format: uuid
              description: ID of the parent batch or collection
            parent_type:
              $ref: '#/components/schemas/CollectionMultipleChoiceInstructionParentType'
            created_by:
              type: string
            description:
              type: string
            order:
              type: integer
            helper_text:
              type: string
              description: Additional guidance text displayed below the question
            placeholder_text_input:
              type: string
              description: Placeholder text displayed in the input field
            answer_limit:
              type: integer
            disable_dropdown:
              type: boolean
              default: false
            options:
              type: array
              items:
                $ref: '#/components/schemas/CollectionMultipleChoiceInstructionOptionsItems'
          required:
            - type
            - id
            - created_at
            - parent_id
            - parent_type
            - created_by
            - description
            - order
            - answer_limit
            - options
          description: multiple_choice variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/CollectionFreeTextInstructionType'
            id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
            parent_id:
              type: string
              format: uuid
              description: ID of the parent batch or collection
            parent_type:
              $ref: '#/components/schemas/CollectionFreeTextInstructionParentType'
            created_by:
              type: string
            description:
              type: string
            order:
              type: integer
            helper_text:
              type: string
              description: Additional guidance text displayed below the question
            placeholder_text_input:
              type: string
              description: Placeholder text displayed in the input field
            validation:
              $ref: '#/components/schemas/ValidationRule'
              description: Optional validation constraints for the input value
          required:
            - type
            - id
            - created_at
            - parent_id
            - parent_type
            - created_by
            - description
            - order
          description: free_text variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/CollectionFreeTextWithUnitInstructionType'
            id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
            parent_id:
              type: string
              format: uuid
              description: ID of the parent batch or collection
            parent_type:
              $ref: '#/components/schemas/CollectionFreeTextWithUnitInstructionParentType'
            created_by:
              type: string
            description:
              type: string
            order:
              type: integer
            helper_text:
              type: string
              description: Additional guidance text displayed below the question
            placeholder_text_input:
              type: string
              description: Placeholder text displayed in the input field
            unit_options:
              type: array
              items:
                $ref: '#/components/schemas/CollectionFreeTextWithUnitInstructionUnitOptionsItems'
              description: List of available units that participants can select from
            default_unit:
              type: string
              description: Default selected unit (must match a value from unit_options)
            unit_position:
              $ref: '#/components/schemas/CollectionFreeTextWithUnitInstructionUnitPosition'
              description: >-
                Position of the unit selector relative to the text input. Use 'prefix' for units before the input (e.g.,
                currency symbols) or 'suffix' for units after the input (e.g., measurements).
          required:
            - type
            - id
            - created_at
            - parent_id
            - parent_type
            - created_by
            - description
            - order
            - unit_options
            - unit_position
          description: free_text_with_unit variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/CollectionMultipleChoiceWithFreeTextInstructionType'
            id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
            parent_id:
              type: string
              format: uuid
              description: ID of the parent batch or collection
            parent_type:
              $ref: '#/components/schemas/CollectionMultipleChoiceWithFreeTextInstructionParentType'
            created_by:
              type: string
            description:
              type: string
            order:
              type: integer
            helper_text:
              type: string
              description: Additional guidance text displayed below the question
            placeholder_text_input:
              type: string
              description: Placeholder text displayed in the input field
            answer_limit:
              type: integer
            disable_dropdown:
              type: boolean
              default: false
            options:
              type: array
              items:
                $ref: '#/components/schemas/CollectionMultipleChoiceWithFreeTextInstructionOptionsItems'
          required:
            - type
            - id
            - created_at
            - parent_id
            - parent_type
            - created_by
            - description
            - order
            - answer_limit
            - options
          description: multiple_choice_with_free_text variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/CollectionFileUploadInstructionType'
            id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
            parent_id:
              type: string
              format: uuid
              description: ID of the parent batch or collection
            parent_type:
              $ref: '#/components/schemas/CollectionFileUploadInstructionParentType'
            created_by:
              type: string
            description:
              type: string
            order:
              type: integer
            helper_text:
              type: string
              description: Additional guidance text displayed below the question
            placeholder_text_input:
              type: string
              description: Placeholder text displayed in the input field
            accepted_file_types:
              type: array
              items:
                type: string
              description: >-
                File extensions to accept (e.g., [".jpg", ".png", ".pdf"]). Each extension must start with a dot.
                Defaults to [".jpg", ".jpeg", ".png", ".heic", ".heif"] if not specified.
            max_file_size_mb:
              type: number
              format: double
              description: Maximum file size in megabytes per file. Must be a positive number. Defaults to 25.
            min_file_count:
              type: integer
              description: Minimum number of files required. Must be at least 1. Defaults to 1.
            max_file_count:
              type: integer
              description: >-
                Maximum number of files allowed. Must be at least 1 and greater than or equal to min_file_count.
                Defaults to 10.
          required:
            - type
            - id
            - created_at
            - parent_id
            - parent_type
            - created_by
            - description
            - order
          description: file_upload variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/ImageContentBlockType'
            id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
            parent_id:
              type: string
              format: uuid
              description: ID of the parent collection item (page)
            parent_type:
              $ref: '#/components/schemas/ImageContentBlockParentType'
            created_by:
              type: string
            schema_version:
              $ref: '#/components/schemas/ImageContentBlockSchemaVersion'
            url:
              type: string
              format: uri
              description: HTTPS URL of the image
            alt_text:
              type: string
              description: Alt text for accessibility
            caption:
              type: string
              description: Optional caption displayed below the image
          required:
            - type
            - id
            - created_at
            - parent_id
            - parent_type
            - created_by
            - schema_version
            - url
            - alt_text
          description: image variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/RichTextContentBlockType'
            id:
              type: string
              format: uuid
            created_at:
              type: string
              format: date-time
            parent_id:
              type: string
              format: uuid
              description: ID of the parent collection item (page)
            parent_type:
              $ref: '#/components/schemas/RichTextContentBlockParentType'
            created_by:
              type: string
            schema_version:
              $ref: '#/components/schemas/RichTextContentBlockSchemaVersion'
            content:
              type: string
              description: HTML content. If the original input used Markdown, it has been converted to HTML.
          required:
            - type
            - id
            - created_at
            - parent_id
            - parent_type
            - created_by
            - schema_version
            - content
          description: rich_text variant
      discriminator:
        propertyName: type
      description: An instruction or content block within a page
      title: PageItem
    CollectionItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        schema_version:
          $ref: '#/components/schemas/CollectionItemSchemaVersion'
        page_items:
          type: array
          items:
            $ref: '#/components/schemas/PageItem'
          description: Instructions and content blocks on this page
      required:
        - id
        - created_at
        - created_by
        - schema_version
        - page_items
      description: A page within a collection containing instructions and content blocks
      title: CollectionItem
    Collection:
      type: object
      properties:
        id:
          type: string
          format: uuid
        schema_version:
          $ref: '#/components/schemas/CollectionSchemaVersion'
        created_at:
          type: string
          format: date-time
          description: ISO-8601 formatted creation timestamp in UTC
        created_by:
          type: string
          description: User ID of the Prolific user that created the collection
        workspace_id:
          type: string
          description: The ID of the Prolific workspace
        name:
          type: string
          description: The name of the collection
        task_details:
          $ref: '#/components/schemas/TaskDetails'
        collection_items:
          type: array
          items:
            $ref: '#/components/schemas/CollectionItem'
          description: Pages within the collection. Each collection item represents a page.
        last_modified_at:
          type: string
          format: date-time
          description: ISO-8601 formatted last modification timestamp in UTC
        last_modified_by:
          type: string
          description: User ID of the Prolific user that last modified the collection
      required:
        - id
        - schema_version
        - created_at
        - created_by
        - workspace_id
        - name
        - task_details
        - collection_items
      title: Collection
    ApiV1DataCollectionCollectionsGetResponsesContentApplicationJsonSchemaMeta:
      type: object
      properties:
        count:
          type: integer
          description: Total number of collections
      title: ApiV1DataCollectionCollectionsGetResponsesContentApplicationJsonSchemaMeta
    AI Task Builder_ListCollections_Response_200:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Collection'
        meta:
          $ref: '#/components/schemas/ApiV1DataCollectionCollectionsGetResponsesContentApplicationJsonSchemaMeta'
      title: AI Task Builder_ListCollections_Response_200
    CollectionInstructionInputType:
      type: string
      enum:
        - multiple_choice
        - free_text
        - free_text_with_unit
        - multiple_choice_with_free_text
        - file_upload
      title: CollectionInstructionInputType
    CollectionInstructionInputOptionsItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      title: CollectionInstructionInputOptionsItemsValue
    CollectionInstructionInputOptionsItems:
      type: object
      properties:
        label:
          type: string
        value:
          $ref: '#/components/schemas/CollectionInstructionInputOptionsItemsValue'
        heading:
          type: string
          description: Required for multiple_choice_with_free_text
        exclusive:
          type: boolean
          description: When true, selecting this option deselects all other options. Useful for "None of the above" style options.
      required:
        - label
        - value
      title: CollectionInstructionInputOptionsItems
    CollectionInstructionInputUnitOptionsItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      title: CollectionInstructionInputUnitOptionsItemsValue
    CollectionInstructionInputUnitOptionsItems:
      type: object
      properties:
        label:
          type: string
        value:
          $ref: '#/components/schemas/CollectionInstructionInputUnitOptionsItemsValue'
        validation:
          $ref: '#/components/schemas/ValidationRule'
          description: Optional validation constraints for this unit option.
      required:
        - label
        - value
      title: CollectionInstructionInputUnitOptionsItems
    CollectionInstructionInputUnitPosition:
      type: string
      enum:
        - prefix
        - suffix
      description: Required for free_text_with_unit. Position of the unit selector relative to the text input.
      title: CollectionInstructionInputUnitPosition
    CollectionInstructionInput:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Include to preserve an existing instruction when updating
        type:
          $ref: '#/components/schemas/CollectionInstructionInputType'
        description:
          type: string
          description: The question or prompt displayed to participants
        order:
          type: integer
          description: Position of this instruction relative to others
        helper_text:
          type: string
          description: Additional guidance text displayed below the question
        placeholder_text_input:
          type: string
          description: Placeholder text displayed in the input field
        answer_limit:
          type: integer
          description: Number of options that can be selected. Use 1 for single-select, -1 for unlimited.
        disable_dropdown:
          type: boolean
          default: false
          description: When true, always renders checkbox/radio elements instead of a dropdown select.
        options:
          type: array
          items:
            $ref: '#/components/schemas/CollectionInstructionInputOptionsItems'
        unit_options:
          type: array
          items:
            $ref: '#/components/schemas/CollectionInstructionInputUnitOptionsItems'
          description: Required for free_text_with_unit. List of available units that participants can select from.
        default_unit:
          type: string
          description: For free_text_with_unit. Default selected unit (must match a value from unit_options).
        unit_position:
          $ref: '#/components/schemas/CollectionInstructionInputUnitPosition'
          description: Required for free_text_with_unit. Position of the unit selector relative to the text input.
        validation:
          $ref: '#/components/schemas/ValidationRule'
          description: Optional validation constraints for the input value (for free_text).
      required:
        - type
        - description
        - order
      description: Instruction input for a collection page
      title: CollectionInstructionInput
    ContentBlockInputType:
      type: string
      enum:
        - image
        - rich_text
      title: ContentBlockInputType
    ContentBlockInputContentFormat:
      type: string
      enum:
        - html
        - markdown
      default: html
      description: >-
        Format of the content field. When set to "markdown", content is converted to HTML server-side before storage.
        Defaults to "html".
      title: ContentBlockInputContentFormat
    ContentBlockInput:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Include to preserve an existing content block when updating
        type:
          $ref: '#/components/schemas/ContentBlockInputType'
        url:
          type: string
          format: uri
          description: HTTPS URL for image content blocks
        alt_text:
          type: string
          description: Alt text for image content blocks (required for accessibility)
        caption:
          type: string
          description: Optional caption for image content blocks
        content:
          type: string
          description: >-
            Content for rich_text content blocks. Interpreted as HTML by default, or Markdown if content_format is set
            to "markdown".
        content_format:
          $ref: '#/components/schemas/ContentBlockInputContentFormat'
          default: html
          description: >-
            Format of the content field. When set to "markdown", content is converted to HTML server-side before
            storage. Defaults to "html".
      required:
        - type
      description: Content block input for a collection page
      title: ContentBlockInput
    PageItemInput:
      oneOf:
        - $ref: '#/components/schemas/CollectionInstructionInput'
        - $ref: '#/components/schemas/ContentBlockInput'
      description: An instruction or content block input. Include `id` to preserve an existing item when updating.
      title: PageItemInput
    CollectionItemInput:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Include to preserve an existing page when updating
        page_items:
          type: array
          items:
            $ref: '#/components/schemas/PageItemInput'
          description: Instructions and content blocks on this page
      required:
        - page_items
      description: A page within a collection. Include `id` to preserve an existing page when updating.
      title: CollectionItemInput
    CollectionCreateRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the collection
        workspace_id:
          type: string
          description: The ID of the Prolific workspace
        task_details:
          $ref: '#/components/schemas/TaskDetails'
        collection_items:
          type: array
          items:
            $ref: '#/components/schemas/CollectionItemInput'
          description: Pages within the collection
      required:
        - name
        - workspace_id
        - task_details
        - collection_items
      title: CollectionCreateRequest
    CollectionUpdateRequest:
      type: object
      properties:
        name:
          type: string
          description: The name of the collection
        task_details:
          $ref: '#/components/schemas/TaskDetails'
        collection_items:
          type: array
          items:
            $ref: '#/components/schemas/CollectionItemInput'
          description: Pages within the collection. Include `id` to preserve existing items.
      required:
        - name
        - task_details
        - collection_items
      title: CollectionUpdateRequest
    CollectionResponseResponseType:
      type: string
      enum:
        - multiple_choice
        - free_text
        - free_text_with_unit
        - multiple_choice_with_free_text
        - file_upload
      title: CollectionResponseResponseType
    CollectionResponseResponseAnswerItemsValue:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
      title: CollectionResponseResponseAnswerItemsValue
    CollectionResponseResponseAnswerItems:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/CollectionResponseResponseAnswerItemsValue'
      title: CollectionResponseResponseAnswerItems
    CollectionResponseResponse:
      type: object
      properties:
        instruction_id:
          type: string
        type:
          $ref: '#/components/schemas/CollectionResponseResponseType'
        answer:
          type: array
          items:
            $ref: '#/components/schemas/CollectionResponseResponseAnswerItems'
      required:
        - instruction_id
        - type
        - answer
      title: CollectionResponseResponse
    CollectionResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        collection_id:
          type: string
          format: uuid
        participant_id:
          type: string
        submission_id:
          type: string
        response:
          $ref: '#/components/schemas/CollectionResponseResponse'
      required:
        - id
        - created_at
        - collection_id
        - participant_id
        - response
      description: A participant's response to a collection
      title: CollectionResponse
    ApiV1DataCollectionCollectionsCollectionIdResponsesGetResponsesContentApplicationJsonSchemaMeta:
      type: object
      properties:
        count:
          type: integer
          description: Total number of responses
      title: ApiV1DataCollectionCollectionsCollectionIdResponsesGetResponsesContentApplicationJsonSchemaMeta
    AI Task Builder_GetCollectionResponses_Response_200:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/CollectionResponse'
        meta:
          $ref: >-
            #/components/schemas/ApiV1DataCollectionCollectionsCollectionIdResponsesGetResponsesContentApplicationJsonSchemaMeta
      title: AI Task Builder_GetCollectionResponses_Response_200
    CollectionExportCompleteStatus:
      type: string
      enum:
        - complete
      title: CollectionExportCompleteStatus
    CollectionExportComplete:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/CollectionExportCompleteStatus'
        url:
          type: string
          format: uri
          description: >-
            Presigned HTTPS URL for downloading the ZIP archive. Valid for 1 hour. Re-poll to get a refreshed URL if
            expired.
        expires_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp indicating when the presigned URL expires.
      required:
        - status
        - url
        - expires_at
      description: An export job that has completed successfully. The ZIP archive is ready to download.
      title: CollectionExportComplete
    CollectionExportStatusOneOf0Status:
      type: string
      enum:
        - generating
      title: CollectionExportStatusOneOf0Status
    CollectionExportStatus0:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/CollectionExportStatusOneOf0Status'
        export_id:
          type: string
          format: uuid
          description: The export job ID. Use this with `GET /collections/{collection_id}/export/{export_id}` to poll for status.
      required:
        - status
        - export_id
      description: An export job that has been enqueued and is currently being generated.
      title: CollectionExportStatus0
    CollectionExportStatusOneOf1Status:
      type: string
      enum:
        - complete
      title: CollectionExportStatusOneOf1Status
    CollectionExportStatus1:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/CollectionExportStatusOneOf1Status'
        url:
          type: string
          format: uri
          description: >-
            Presigned HTTPS URL for downloading the ZIP archive. Valid for 1 hour. Re-poll to get a refreshed URL if
            expired.
        expires_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp indicating when the presigned URL expires.
      required:
        - status
        - url
        - expires_at
      description: An export job that has completed successfully. The ZIP archive is ready to download.
      title: CollectionExportStatus1
    CollectionExportStatusOneOf2Status:
      type: string
      enum:
        - failed
      title: CollectionExportStatusOneOf2Status
    CollectionExportStatus2:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/CollectionExportStatusOneOf2Status'
      required:
        - status
      description: >-
        An export job that failed to generate, or whose archive has since been deleted. Re-send `POST
        /collections/{collection_id}/export` to retry.
      title: CollectionExportStatus2
    CollectionExportStatus:
      oneOf:
        - $ref: '#/components/schemas/CollectionExportStatus0'
        - $ref: '#/components/schemas/CollectionExportStatus1'
        - $ref: '#/components/schemas/CollectionExportStatus2'
      description: The current status of a collection export job.
      title: CollectionExportStatus
    ApiV1StudiesGetParametersState:
      type: string
      enum:
        - ACTIVE
        - PAUSED
        - UNPUBLISHED
        - PUBLISHING
        - COMPLETED
        - AWAITING REVIEW
        - UNKNOWN
        - SCHEDULED
      title: ApiV1StudiesGetParametersState
    StudyShortStatus:
      type: string
      enum:
        - UNPUBLISHED
        - SCHEDULED
        - PUBLISHING
        - ACTIVE
        - AWAITING REVIEW
        - PAUSED
        - COMPLETED
      description: Status of the study.
      title: StudyShortStatus
    StudyShortStudyType:
      type: string
      enum:
        - SINGLE
        - UK_REP_SAMPLE
        - US_REP_SAMPLE
      description: Deprecated. Type of study.
      title: StudyShortStudyType
    StudyShort:
      type: object
      properties:
        id:
          type: string
          description: Study id. It is created by Prolific.
        name:
          type: string
          description: Public name or title of the study
        internal_name:
          type:
            - string
            - 'null'
          description: Internal name of the study, not shown to participants
        status:
          $ref: '#/components/schemas/StudyShortStatus'
          description: Status of the study.
        study_type:
          $ref: '#/components/schemas/StudyShortStudyType'
          description: Deprecated. Type of study.
        estimated_completion_time:
          type: number
          format: double
          description: Estimated duration in minutes of the experiment or survey
        total_available_places:
          type: number
          format: double
          description: How many participants are you looking to recruit
        places_taken:
          type: number
          format: double
          description: Places already taken, number of submission started excluding timed out and returned submissions
        number_of_submissions:
          type: number
          format: double
        reward:
          type: number
          format: double
          description: How much are you going to pay the participants in cents. We use the currency of your account
        total_cost:
          type: number
          format: double
          description: Total cost of the study including fees
        published_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Date time when the study was published.
        publish_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Date time when the study was scheduled to be published.
        date_created:
          type: string
          format: date-time
          description: Date time when the study was created
        credential_pool_id:
          type:
            - string
            - 'null'
          description: The ID of the credential pool associated with this study, if any
        is_ready_to_publish:
          type: boolean
          description: >-
            Whether the study has all required fields completed for publishing. Does not check wallet balance or funding
            — only study-level field completeness.
      required:
        - id
        - name
      title: StudyShort
    StudiesListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/StudyShort'
          description: List of all studies matching the criteria.
      required:
        - results
      title: StudiesListResponse
    CreateStudyProlificIdOption:
      type: string
      enum:
        - question
        - url_parameters
        - not_required
      description: >-
        Use 'question' if you will add a question in your survey or experiment asking the participant ID


        **Recommended** Use 'url_parameters' if your survey or experiment can retrieve and store those parameters for
        your analysis.


        Use 'not_required' if you don't need to record them.
      title: CreateStudyProlificIdOption
    CreateStudyCompletionCodesItemsCodeType:
      type: string
      enum:
        - COMPLETED
        - FAILED_ATTENTION_CHECK
        - FOLLOW_UP_STUDY
        - GIVE_BONUS
        - INCOMPATIBLE_DEVICE
        - NO_CONSENT
        - OTHER
        - FIXED_SCREENOUT
        - SCREENED_IN
        - SCREENED_OUT
      description: >
        A name for your code to make it easier to understand its intention. Either use one of the predefined options or
        any other free text.
      title: CreateStudyCompletionCodesItemsCodeType
    AutomaticallyApproveAction:
      type: string
      enum:
        - AUTOMATICALLY_APPROVE
      description: Automatically approves submission with payment being processed immediately
      title: AutomaticallyApproveAction
    AutomaticallyApprove:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/AutomaticallyApproveAction'
          description: Automatically approves submission with payment being processed immediately
      required:
        - action
      title: AutomaticallyApprove
    AddToParticipantGroupAction:
      type: string
      enum:
        - ADD_TO_PARTICIPANT_GROUP
      description: Adds participants to a specific group
      title: AddToParticipantGroupAction
    AddToParticipantGroup:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/AddToParticipantGroupAction'
          description: Adds participants to a specific group
        participant_group:
          type: string
          description: The participant group to add the participant to.
      required:
        - action
        - participant_group
      title: AddToParticipantGroup
    RemoveFromParticipantGroupAction:
      type: string
      enum:
        - REMOVE_FROM_PARTICIPANT_GROUP
      description: Removes participants from specific groups
      title: RemoveFromParticipantGroupAction
    RemoveFromParticipantGroup:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/RemoveFromParticipantGroupAction'
          description: Removes participants from specific groups
        participant_group:
          type: string
          description: The participant group to remove the participant from.
      required:
        - action
        - participant_group
      title: RemoveFromParticipantGroup
    ManuallyReviewAction:
      type: string
      enum:
        - MANUALLY_REVIEW
      description: Moves submission for the data collector to be manually reviewed.
      title: ManuallyReviewAction
    ManuallyReview:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/ManuallyReviewAction'
          description: Moves submission for the data collector to be manually reviewed.
      required:
        - action
      title: ManuallyReview
    RequestReturnAction:
      type: string
      enum:
        - REQUEST_RETURN
      description: Requests the participant to return their study
      title: RequestReturnAction
    RequestReturn:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/RequestReturnAction'
          description: Requests the participant to return their study
        return_reason:
          type: string
          description: The reason you would like to request a return
      required:
        - action
        - return_reason
      title: RequestReturn
    DynamicPaymentAction:
      type: string
      enum:
        - DYNAMIC_PAYMENT
      description: >-
        Use this action to set up a dynamic payment study. Only certain workspaces have access to this feature. When
        using this action, the actor must be "researcher".
      title: DynamicPaymentAction
    DynamicPayment:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/DynamicPaymentAction'
          description: >-
            Use this action to set up a dynamic payment study. Only certain workspaces have access to this feature. When
            using this action, the actor must be "researcher".
      required:
        - action
      title: DynamicPayment
    FixedScreenOutAction:
      type: string
      enum:
        - FIXED_SCREEN_OUT_PAYMENT
      description: >-
        Use this action to set up a fixed screen out reward study. This feature is currently available to select
        workspaces only.

        - A fixed screen out reward study compensates participants with a predetermined amount when they do not qualify
        for the study.

        - This feature enables researchers to implement more precise participant screening while ensuring fair
        compensation for participants' time.
      title: FixedScreenOutAction
    FixedScreenOut:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/FixedScreenOutAction'
          description: >-
            Use this action to set up a fixed screen out reward study. This feature is currently available to select
            workspaces only.

            - A fixed screen out reward study compensates participants with a predetermined amount when they do not
            qualify for the study.

            - This feature enables researchers to implement more precise participant screening while ensuring fair
            compensation for participants' time.
        fixed_screen_out_reward:
          type: integer
          description: >-
            The amount that you would like to pay for a screen-out submission (in subcurrency). This must be less that
            the study reward.
        slots:
          type: integer
          description: >-
            The slots field controls how many participants can be screened out of your study before it automatically
            pauses.


            #### What are slots?
              - Slots set a limit on screen-outs to help you budget upfront, by setting the limit to the maximum number of screen-outs you're comfortable paying for in your study.
              - When participants don't qualify for your study, they will receive a screen-out payment.
              - The slots limit prevents unexpected high costs created from too many screen-outs.
              - **Example**: If you set `slots: 50`, your study will pause after 50 participants are screened out, even if you still need more qualified participants.

            #### How slots work
              1. **Participants are screened out** - When they enter the completion code linked to this action. They will automatically receive the fixed screen out reward.
              2. **Study pauses automatically** - When the number of participants screened out reaches the slots limit, and there are still unfilled places in the study, the study will automatically pause.
              3. **You get notified** - Via email and webhook, notifying you that you’ve reached your slot limit, and that your study has been paused.  (Webhook notifications only if they’re enabled for `study.status.change` events)

            #### Resuming your study
              *To continue recruiting after hitting the slot limit:*

              1. **Increase the slot limit** using the [update study](#tag/Studies/operation/UpdateStudy) endpoint.
                 - Update the initial property to your new slot limit.
                 - Refer `update_slots` in the example of the [UpdateStudy](#tag/Studies/operation/UpdateStudy) endpoint.
                 - For example, if you started with 50 slots and want to add another 50 slots, set the `slots` property to 100.
              ```json
                {
                  "completion_codes": [
                    {
                      "code": "ABC123",
                      "actions": [
                        {
                          "action": "FIXED_SCREEN_OUT_PAYMENT",
                          "slots": 100
                        }
                      ]
                    }
                  ]
                }
              ```
              2. **Resume the study** by transitioning it back to `START` state using the [transition study](#tag/Studies/operation/PublishStudy) endpoint.

              ```json
              {
                "action": "START"
              }
              ```
      required:
        - action
        - fixed_screen_out_reward
        - slots
      description: Use this action to set up a fixed screen out reward study.
      title: FixedScreenOut
    CreateStudyCompletionCodesItemsActionsItems:
      oneOf:
        - $ref: '#/components/schemas/AutomaticallyApprove'
        - $ref: '#/components/schemas/AddToParticipantGroup'
        - $ref: '#/components/schemas/RemoveFromParticipantGroup'
        - $ref: '#/components/schemas/ManuallyReview'
        - $ref: '#/components/schemas/RequestReturn'
        - $ref: '#/components/schemas/DynamicPayment'
        - $ref: '#/components/schemas/FixedScreenOut'
      title: CreateStudyCompletionCodesItemsActionsItems
    CreateStudyCompletionCodesItemsActor:
      type: string
      enum:
        - participant
        - researcher
      default: participant
      description: The actor that can provide this completion code.
      title: CreateStudyCompletionCodesItemsActor
    CreateStudyCompletionCodesItems:
      type: object
      properties:
        code:
          type:
            - string
            - 'null'
          description: >
            The code the participant will either enter manually at the end of your study or be redirected as part of the
            return URL.


            If the code is null, then the participant will not be asked to submit a completion code when they return to
            Prolific.

            Null codes can only be provided when:
              - The actor is "participant"
              - There are no other completion codes with the "participant" actor
              - The actions array is empty

            The code must be unique within the study.
        code_type:
          $ref: '#/components/schemas/CreateStudyCompletionCodesItemsCodeType'
          description: >
            A name for your code to make it easier to understand its intention. Either use one of the predefined options
            or any other free text.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/CreateStudyCompletionCodesItemsActionsItems'
          description: >-
            The actions that will be completed automatically when the submission is completed with this code by the
            participant.


            You have the ability to use one or multiple `actions` together - it's up to you and your desired automated
            journey.


            If you’re looking to keep things simple, we recommend setting the `{"action": "MANUALLY_REVIEW"}` option
            only, so all submissions wait for your manual approval.
        actor:
          $ref: '#/components/schemas/CreateStudyCompletionCodesItemsActor'
          default: participant
          description: The actor that can provide this completion code.
      required:
        - code
        - code_type
        - actions
      title: CreateStudyCompletionCodesItems
    CreateStudyDeviceCompatibilityItems:
      type: string
      enum:
        - desktop
        - tablet
        - mobile
      title: CreateStudyDeviceCompatibilityItems
    CreateStudyPeripheralRequirementsItems:
      type: string
      enum:
        - audio
        - camera
        - download
        - microphone
      title: CreateStudyPeripheralRequirementsItems
    SelectFilter:
      type: object
      properties:
        filter_id:
          type: string
          description: ID of the "select" type filter.
        selected_values:
          type: array
          items:
            type: string
          description: >-
            This schema applies for filters of the `select` type, as defined in the [filter list
            response](\#tag/Filters/paths/~1api~1v1~1filters~1/get).


            Array of IDs matching the response IDs, from the `select` filter's `choices` (see response linked above).


            String format should match the `data_type` of the `select` filter's `choices` (see response linked above).
        weightings:
          type: object
          additionalProperties:
            type: number
            format: double
          description: |-
            Ratios to control the distribution of participants across the selected values.

            Integer percentages, floats, and exact quantities are valid inputs.
      required:
        - filter_id
        - selected_values
      title: SelectFilter
    RangeFilterSelectedRangeLower:
      oneOf:
        - type: integer
        - type: string
        - type: number
          format: double
      description: Your selected lower bound for the range.
      title: RangeFilterSelectedRangeLower
    RangeFilterSelectedRangeUpper:
      oneOf:
        - type: integer
        - type: string
        - type: number
          format: double
      description: Your selected upper bound for the range.
      title: RangeFilterSelectedRangeUpper
    RangeFilterSelectedRange:
      type: object
      properties:
        lower:
          $ref: '#/components/schemas/RangeFilterSelectedRangeLower'
          description: Your selected lower bound for the range.
        upper:
          $ref: '#/components/schemas/RangeFilterSelectedRangeUpper'
          description: Your selected upper bound for the range.
      description: >-
        This schema applies for filters of the `range` type, as defined in the [filter list
        response](\#tag/Filters/paths/~1api~1v1~1filters~1/get).


        A dictionary with two possible objects, 'lower' and 'upper'. At least one must be present and a non-null value.


        The expected data type for these values is defined by the `range` filter's `data_type` (see response linked
        above).


        If the data_type is a date, string format should be a parseable ISO8601 date string. Date values should be
        provided as a string in ISO 8601 format.


        Leaving a value as null will result in that bound being set to the lowest or highest possible value, depending
        on whether it is the upper or lower bound.
      title: RangeFilterSelectedRange
    RangeFilterWeightingsSelectedRangeLower:
      oneOf:
        - type: integer
        - type: string
        - type: number
          format: double
      title: RangeFilterWeightingsSelectedRangeLower
    RangeFilterWeightingsSelectedRangeUpper:
      oneOf:
        - type: integer
        - type: string
        - type: number
          format: double
      title: RangeFilterWeightingsSelectedRangeUpper
    RangeFilterWeightingsSelectedRange:
      type: object
      properties:
        lower:
          $ref: '#/components/schemas/RangeFilterWeightingsSelectedRangeLower'
        upper:
          $ref: '#/components/schemas/RangeFilterWeightingsSelectedRangeUpper'
      title: RangeFilterWeightingsSelectedRange
    RangeFilterWeightings:
      type: object
      properties:
        selected_range:
          $ref: '#/components/schemas/RangeFilterWeightingsSelectedRange'
        weighting:
          type: number
          format: double
      required:
        - selected_range
        - weighting
      title: RangeFilterWeightings
    RangeFilter:
      type: object
      properties:
        filter_id:
          type: string
          description: ID of the "range" type filter.
        selected_range:
          $ref: '#/components/schemas/RangeFilterSelectedRange'
          description: >-
            This schema applies for filters of the `range` type, as defined in the [filter list
            response](\#tag/Filters/paths/~1api~1v1~1filters~1/get).


            A dictionary with two possible objects, 'lower' and 'upper'. At least one must be present and a non-null
            value.


            The expected data type for these values is defined by the `range` filter's `data_type` (see response linked
            above).


            If the data_type is a date, string format should be a parseable ISO8601 date string. Date values should be
            provided as a string in ISO 8601 format.


            Leaving a value as null will result in that bound being set to the lowest or highest possible value,
            depending on whether it is the upper or lower bound.
        weightings:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RangeFilterWeightings'
          description: |-
            Ratios to control the distribution of participants across the selected values.

            Integers and exact quantities are valid inputs.
      required:
        - filter_id
        - selected_range
      title: RangeFilter
    CompositeFilterFilterId:
      type: string
      enum:
        - and
        - or
      description: >-
        Composite filter group operator. Use `and` when every child filter must match, or `or` when at least one child
        filter must match.
      title: CompositeFilterFilterId
    CompositeFilterSelectedFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: CompositeFilterSelectedFiltersItems
    CompositeFilter:
      type: object
      properties:
        filter_id:
          $ref: '#/components/schemas/CompositeFilterFilterId'
          description: >-
            Composite filter group operator. Use `and` when every child filter must match, or `or` when at least one
            child filter must match.
        selected_filters:
          type: array
          items:
            $ref: '#/components/schemas/CompositeFilterSelectedFiltersItems'
          description: >-
            Child filters in this group. Children can be select filters, range filters, or supported nested composite
            groups.
      required:
        - filter_id
        - selected_filters
      title: CompositeFilter
    CreateStudyFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: CreateStudyFiltersItems
    CreateStudySubmissionsConfigAutoRejectionCategoriesItems:
      type: string
      enum:
        - EXCEPTIONALLY_FAST
      title: CreateStudySubmissionsConfigAutoRejectionCategoriesItems
    CreateStudySubmissionsConfig:
      type: object
      properties:
        max_submissions_per_participant:
          type:
            - integer
            - 'null'
          default: 1
          description: >-
            - **1** is the default Prolific experience. This means one submission, per participant, per study. If you do
              not specify this field, the **default is 1**.
            - **1+** turns your study into a multi-submission study, meaning a participant can create many submissions
            per study.
              As noted above, your survey system will need to handle providing a
            unique experience each time the participant takes the study.

            - **-1** will allow an indefinite number of submissions from a single participant, up to
            `total_available_places`.
        max_concurrent_submissions:
          type:
            - integer
            - 'null'
          default: -1
          description: |-
            - **-1** is the default value, meaning unlimited concurrent active/reserved submissions per study.
            - **1+** limits the number of concurrent active/reserved submissions a study can have at one time.
        auto_rejection_categories:
          type: array
          items:
            $ref: '#/components/schemas/CreateStudySubmissionsConfigAutoRejectionCategoriesItems'
          default: []
          description: >-
            List of rejection categories that trigger automatic submission rejections.


            **Available Categories:**

            - **EXCEPTIONALLY_FAST**: Automatically reject submissions completed in an exceptionally short time


            **Important Notes:**

            - **This feature is currently in an evaluation period and can be activated for your workspace upon
            request.**

            - Auto-rejections only apply to submissions in "AWAITING REVIEW" status

            - Submissions with return requests will not be auto-rejected

            - Auto-rejected submissions do not count towards your rejection limit

            - Set to an empty array `[]` or omit this field to disable auto-rejection
      description: >-
        **Advanced**: This helps with faster data collection. Your survey system will need to handle providing a

        unique experience each time the participant takes the study.


        Configuration related to study submissions. The purpose of this field is to capture any configuration options
        that impact the submissions made by participants in a study.
      title: CreateStudySubmissionsConfig
    CreateStudyStudyLabelsItems:
      type: string
      enum:
        - survey
        - writing_task
        - annotation
        - decision_making_task
        - interview
        - other
        - ai_annotation
        - ai_evaluation
        - ai_reasoning
        - ai_fact_checking
        - ai_safety
        - ai_data_creation_text
        - ai_data_creation_audio
        - ai_data_creation_video
        - ai_data_creation_images
        - ai_other
      title: CreateStudyStudyLabelsItems
    CreateStudyContentWarningsItems:
      type: string
      enum:
        - sensitive
        - explicit
      title: CreateStudyContentWarningsItems
    CreateStudyDataCollectionMethod:
      type: string
      enum:
        - AI_TASK_BUILDER_BATCH
        - AI_TASK_BUILDER_COLLECTION
      description: >-
        **Optional.** Specifies the data collection method for the study.


        - `AI_TASK_BUILDER_BATCH`: Use AI Task Builder for data annotation tasks.

        - `AI_TASK_BUILDER_COLLECTION`: Use AI Task Builder for data collection tasks.


        **Note:** This field is mutually exclusive with `external_study_url` and `access_details`. If not provided, you
        must specify one of those fields instead.
      title: CreateStudyDataCollectionMethod
    CreateStudyDataCollectionMetadata:
      type: object
      properties:
        annotators_per_task:
          type: integer
          description: >-
            Number of annotators required per task. Required for AI Task Builder Batch studies to set multiple
            annotators.
      description: >-
        **Optional.** Additional metadata for configuring AI Task Builder data annotation behavior. Only used when
        `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`.


        **Properties:**


        - `annotators_per_task` (integer): Number of annotators per task. **This field must be provided if you want
        multiple annotators per task.** Without this field, the default value of 1 will be used.
          - Minimum: 1
          - Default: 1 (if not provided)

        **Example:**

        ```json

        {
          "annotators_per_task": 5
        }

        ```


        **Important:** You must include `annotators_per_task` to control how many participants annotate each task. After
        the study is published, this value can only be increased (not decreased), which will increase the total
        available places on the study.
      title: CreateStudyDataCollectionMetadata
    AccessDetail:
      type: object
      properties:
        external_url:
          type: string
          description: >-
            URL of the task you want to send the participant to. You can pass URL search parameters as in
            `external_study_url`.
        total_allocation:
          type: number
          format: double
          description: >-
            The base number of places you want allocated to this URL. This value is set by you and is used to determine
            the study's total available places.


            Note: for studies with custom screening (fixed screen-out reward), participants who are screened out
            generate additional capacity on top of this base value. The `allocated` count in progress responses may
            therefore exceed `total_allocation` — this is expected behaviour. See `capacity_increments` in the progress
            response for details.
      required:
        - external_url
        - total_allocation
      title: AccessDetail
    CreateStudyAccessDetailsItems:
      oneOf:
        - $ref: '#/components/schemas/AccessDetail'
      title: CreateStudyAccessDetailsItems
    CreateStudy:
      type: object
      properties:
        name:
          type: string
          description: Public name or title of the study
        internal_name:
          type:
            - string
            - 'null'
          description: Internal name of the study, not shown to participants
        description:
          type: string
          description: >-
            Description of the study for the participants to read before

            starting the study


            **Supported HTML in `description`**


            The `description` field supports the following HTML tags for formatting participant instructions:


            * `<b>` - bold

            * `<i>` - italic

            * `<em>` - emphasized text

            * `<strong>` - strong importance

            * `<s>` - strikethrough

            * `<u>` - underline

            * `<h1>` - heading level 1

            * `<h2>` - heading level 2

            * `<ol>` - ordered list

            * `<ul>` - unordered list

            * `<li>` - list item

            * `<p>` - paragraph


            Other HTML tags will be stripped or escaped. Please ensure that you only use supported tags for formatting
            to avoid rendering issues.
        external_study_url:
          type: string
          description: >-
            URL of the survey or experiment you want participant to access. You can pass URL search parameters to your
            survey or experiment


            * Participant id {{%PROLIFIC_PID%}}

            * Study id {{%STUDY_ID%}}

            * Session id {{%SESSION_ID%}}


            For example `https://eggs-experriment.com?participant={{%PROLIFIC_PID%}}`
        prolific_id_option:
          $ref: '#/components/schemas/CreateStudyProlificIdOption'
          description: >-
            Use 'question' if you will add a question in your survey or experiment asking the participant ID


            **Recommended** Use 'url_parameters' if your survey or experiment can retrieve and store those parameters
            for your analysis.


            Use 'not_required' if you don't need to record them.
        completion_codes:
          type: array
          items:
            $ref: '#/components/schemas/CreateStudyCompletionCodesItems'
          description: >-
            Specify at least one completion code for your study. A participant will enter one of these codes when they
            complete your study.


            Each code must be unique within a study.


            You can specify as many actions as you like per code. However, some actions can't be used together (e.g.
            AutomaticallyApprove and ManuallyReview).


            **Note:** This field is optional when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH` or
            `AI_TASK_BUILDER_COLLECTION`. When omitted, a default COMPLETED code with a `MANUALLY_REVIEW` action is
            auto-generated. When provided, AITB studies must include exactly one code with `code_type` of `COMPLETED`
            and an action of `MANUALLY_REVIEW` or `AUTOMATICALLY_APPROVE`.
        total_available_places:
          type: number
          format: double
          description: >-
            How many participants are you looking to recruit.


            **Note:** This field is optional when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`, as the
            total available places are automatically calculated from the batch configuration.
        estimated_completion_time:
          type: number
          format: double
          description: Estimated duration in minutes of the experiment or survey
        maximum_allowed_time:
          type: number
          format: double
          description: >-
            Max time in minutes for a participant to finish the submission. Submissions are timed out if it takes
            longer.


            If it is not provided the default value is set to the max value.


            The min value is calculated as two minutes plus two times the estimated time plus two times the square root
            of the estimated time
        reward:
          type: number
          format: double
          description: |-
            How much are you going to pay the participants in cents. We
            use the currency of your account.
        device_compatibility:
          type: array
          items:
            $ref: '#/components/schemas/CreateStudyDeviceCompatibilityItems'
          description: |-
            Add all devices that participants can use.
            You can include one or more options.

            An empty array indicates that all options are available.
        peripheral_requirements:
          type: array
          items:
            $ref: '#/components/schemas/CreateStudyPeripheralRequirementsItems'
          description: |-
            Add all requirements that participants have to meet.

            An empty array indicates that there are no extra peripheral requirements.
        filters:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CreateStudyFiltersItems'
          description: >-
            Array of filters.


            For advanced participant targeting with `and` / `or` groups, see [Advanced
            filtering](/api-reference/filters/advanced-filtering).


            Use empty array for "Everyone"
        filter_set_id:
          type:
            - string
            - 'null'
          description: |-
            The ID of a filter set, from which filters for the study will be taken.

            For more information, see [Filter Sets](/api-reference/filter-sets).

            Note, this cannot be used in combination with additional filters via the `filters` field.
        filter_set_version:
          type:
            - integer
            - 'null'
          description: |-
            The version of the filter set to be used.

            If not provided, this will default to the latest available version at the time of applying the filter set.
        naivety_distribution_rate:
          type:
            - number
            - 'null'
          format: double
          description: |-
            Control the balance between speed of your studies and the naivety of the participants.

            If not defined, by default Prolific calculates the best rate for most studies
            taking into account the `filters` and the `total_available_places` needed for this study.

            Use 0 if your priority is speed. When this property is set to 0 all eligible participants will have access
            to your study at the same time, without any prioritization.

            You can also set this at a workspace and project level.
        project:
          type: string
          description: >-
            Project ID. When you don't specify a project in your request, Prolific automatically uses your first created
            project as the default. For clarity, we recommend explicitly including the project ID in your requests.
        submissions_config:
          $ref: '#/components/schemas/CreateStudySubmissionsConfig'
          description: >-
            **Advanced**: This helps with faster data collection. Your survey system will need to handle providing a

            unique experience each time the participant takes the study.


            Configuration related to study submissions. The purpose of this field is to capture any configuration
            options that impact the submissions made by participants in a study.
        study_labels:
          type: array
          items:
            $ref: '#/components/schemas/CreateStudyStudyLabelsItems'
          description: >-
            This field allows you to tag studies with information about the type/topic of the study and the kind of work
            involved in completing it.


            We plan to make this information available to participants for easier self-selection. At present these
            options are mutually exclusive and only a single option can be selected, however in the future available
            categories will expand.
        content_warnings:
          type: array
          items:
            $ref: '#/components/schemas/CreateStudyContentWarningsItems'
          description: >-
            Allow researchers to define content warnings for their study.


            At present these options are mutually exclusive and only a single option can be selected, however in the
            future available warnings will expand.
        content_warning_details:
          type: string
          description: Allow researchers to add further details about their content warning.
        metadata:
          type:
            - string
            - 'null'
          description: |-
            This field can be used to store extra information required for a system integration.
            For example, it could be some JSON, XML, an integer, or a string.

            Examples could include:

              - `123345` - An ID from your system, that helps with linkage when returning the study.
              - `{ \"id\": \"45\", \"type\": \"finance\"}` - Some JSON that you want to store.
        credential_pool_id:
          type:
            - string
            - 'null'
          description: |-
            The ID of the credential pool to associate with this study. Credential pools contain
            username/password pairs that are distributed to participants when they start the study.

            When provided, participants will be assigned unique credentials from the pool. Each
            credential can only be used once and is tracked throughout the study lifecycle.

            **Note:** The credential pool must:
            - Exist and belong to the study's workspace
            - Have available (unredeemed) credentials

            See the [Credentials endpoints](#tag/Credentials) for managing credential pools.
        has_credentials:
          type: boolean
          description: |-
            Indicates whether this study requires participants to use credentials. This field is
            automatically set to `true` when a `credential_pool_id` is provided, and `false` when
            the credential pool is removed.

            **Note:** This field is automatically managed based on the `credential_pool_id` field
            and does not need to be set manually.
        data_collection_method:
          oneOf:
            - $ref: '#/components/schemas/CreateStudyDataCollectionMethod'
            - type: 'null'
          description: >-
            **Optional.** Specifies the data collection method for the study.


            - `AI_TASK_BUILDER_BATCH`: Use AI Task Builder for data annotation tasks.

            - `AI_TASK_BUILDER_COLLECTION`: Use AI Task Builder for data collection tasks.


            **Note:** This field is mutually exclusive with `external_study_url` and `access_details`. If not provided,
            you must specify one of those fields instead.
        data_collection_id:
          type:
            - string
            - 'null'
          description: >-
            The ID of the data collection batch or project from the Task Builder API.


            **Required when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH` or
            `AI_TASK_BUILDER_COLLECTION`.**
        data_collection_metadata:
          oneOf:
            - $ref: '#/components/schemas/CreateStudyDataCollectionMetadata'
            - type: 'null'
          description: >-
            **Optional.** Additional metadata for configuring AI Task Builder data annotation behavior. Only used when
            `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`.


            **Properties:**


            - `annotators_per_task` (integer): Number of annotators per task. **This field must be provided if you want
            multiple annotators per task.** Without this field, the default value of 1 will be used.
              - Minimum: 1
              - Default: 1 (if not provided)

            **Example:**

            ```json

            {
              "annotators_per_task": 5
            }

            ```


            **Important:** You must include `annotators_per_task` to control how many participants annotate each task.
            After the study is published, this value can only be increased (not decreased), which will increase the
            total available places on the study.
        access_details:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CreateStudyAccessDetailsItems'
          description: >-
            Array of access_details, which integrates with taskflow.


            While this field is nullable, you must provide one of `access_details` or `external_study_url`.


            The sum of all access_details must add to the `total_available_places` field, however the values can be
            different for an individual access_detail.
        is_external_study_url_secure:
          type: boolean
          description: >-
            When set to true, any query parameters in the external study url will be signed with a JSON Web Token. The
            token will be added to the URL as a query parameter named `prolific_token`.


            This feature is only available to certain workspaces.


            **The JWT payload**


            Header:


            ```json

            {
              "alg": "RS256",
              "kid": "<KEY_ID>",
              "typ": "JWT"
            }

            ```


            Where

            - alg is always RS256.

            - kid indicates the key ID that was used to secure the JWT.

            - typ is always JWT.


            Payload:


            ```json

            {
              "iss": "https://www.prolific.com",
              "iat": <CURRENT_TIME>,
              "exp": <CURRENT_TIME + 2 minutes>,
              "aud": "<EXTERNAL_STUDY_URL>",
              "sub": "<SESSION_ID>",
              "prolific":{
                "<QUERY_1>": "<VALUE_1>",
                "<QUERY_2>": "<VALUE_2>",
                ...
                "workspace_id": "<WORKSPACE_ID>",
                "organisation_id": "<ORGANISATION_ID>"
              }
            }

            ```


            `<ORGANISATION_ID>` appears only when the workspace is linked to an

            organisation; otherwise omit that key from `prolific`.


            The `prolific` object maps each URL parameter from your

            external study URL template to the resolved value for that

            placeholder (for example participant, study, and session

            identifiers). Prolific always adds `workspace_id` (string). When the

            workspace is linked to an organisation, `organisation_id` (string)

            is also present.


            For example (the sample below includes `organisation_id`; that key

            is omitted when the workspace has no linked organisation):


            ```json

            {
              "iss": "https://www.prolific.com",
              "iat": 1740496135,
              "exp": 1740496255,
              "aud": "https://x.com?STUDY_ID=1&...",
              "sub": "1234",
              "prolific":{
                "STUDY_ID": "abcd",
                "SESSION_ID": "1234",
                "PROLIFIC_PID": "xyz",
                "workspace_id": "507f1f77bcf86cd799439011",
                "organisation_id": "507f191e810c19729de860ea"
              }
            }

            ```


            **Verify the payload**


            When you receive the JWT, you must verify the following:

            - The JWT signature is authentic by verifying it with the public key from Prolific that correlates with the
            KID. The public keys can be retrieved from
            [/.well-known/study/jwks.json](#tag/Well-Known-Endpoints/paths/~1.well-known~1study~1jwks.json/get).

            - The JWT hasn't expired, by checking the `exp` claim.

            - The `aud` claim is the correct domain for your tool.

            - The `prolific` claim matches your expected payload as set in the `external_study_url` property. It always
            includes `workspace_id`. When the workspace is linked to an organisation, it also includes `organisation_id`
            (validate both against what your integration expects).
      required:
        - name
        - description
        - external_study_url
        - prolific_id_option
        - total_available_places
        - estimated_completion_time
        - reward
      title: CreateStudy
    StudyStatus:
      type: string
      enum:
        - UNPUBLISHED
        - SCHEDULED
        - PUBLISHING
        - ACTIVE
        - AWAITING REVIEW
        - PAUSED
        - COMPLETED
      description: |-
        Status of the study. **Read only**.

        To change the status you can use `/api/v1/studies/{id}/transition/`
      title: StudyStatus
    Study:
      type: object
      properties:
        name:
          type: string
          description: Public name or title of the study
        internal_name:
          type:
            - string
            - 'null'
          description: Internal name of the study, not shown to participants
        description:
          type: string
          description: >-
            Description of the study for the participants to read before

            starting the study


            **Supported HTML in `description`**


            The `description` field supports the following HTML tags for formatting participant instructions:


            * `<b>` - bold

            * `<i>` - italic

            * `<em>` - emphasized text

            * `<strong>` - strong importance

            * `<s>` - strikethrough

            * `<u>` - underline

            * `<h1>` - heading level 1

            * `<h2>` - heading level 2

            * `<ol>` - ordered list

            * `<ul>` - unordered list

            * `<li>` - list item

            * `<p>` - paragraph


            Other HTML tags will be stripped or escaped. Please ensure that you only use supported tags for formatting
            to avoid rendering issues.
        external_study_url:
          type: string
          description: >-
            URL of the survey or experiment you want participant to access. You can pass URL search parameters to your
            survey or experiment


            * Participant id {{%PROLIFIC_PID%}}

            * Study id {{%STUDY_ID%}}

            * Session id {{%SESSION_ID%}}


            For example `https://eggs-experriment.com?participant={{%PROLIFIC_PID%}}`
        prolific_id_option:
          $ref: '#/components/schemas/CreateStudyProlificIdOption'
          description: >-
            Use 'question' if you will add a question in your survey or experiment asking the participant ID


            **Recommended** Use 'url_parameters' if your survey or experiment can retrieve and store those parameters
            for your analysis.


            Use 'not_required' if you don't need to record them.
        completion_codes:
          type: array
          items:
            $ref: '#/components/schemas/CreateStudyCompletionCodesItems'
          description: >-
            Specify at least one completion code for your study. A participant will enter one of these codes when they
            complete your study.


            Each code must be unique within a study.


            You can specify as many actions as you like per code. However, some actions can't be used together (e.g.
            AutomaticallyApprove and ManuallyReview).


            **Note:** This field is optional when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH` or
            `AI_TASK_BUILDER_COLLECTION`. When omitted, a default COMPLETED code with a `MANUALLY_REVIEW` action is
            auto-generated. When provided, AITB studies must include exactly one code with `code_type` of `COMPLETED`
            and an action of `MANUALLY_REVIEW` or `AUTOMATICALLY_APPROVE`.
        total_available_places:
          type: number
          format: double
          description: >-
            How many participants are you looking to recruit.


            **Note:** This field is optional when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`, as the
            total available places are automatically calculated from the batch configuration.
        estimated_completion_time:
          type: number
          format: double
          description: Estimated duration in minutes of the experiment or survey
        maximum_allowed_time:
          type: number
          format: double
          description: >-
            Max time in minutes for a participant to finish the submission. Submissions are timed out if it takes
            longer.


            If it is not provided the default value is set to the max value.


            The min value is calculated as two minutes plus two times the estimated time plus two times the square root
            of the estimated time
        reward:
          type: number
          format: double
          description: |-
            How much are you going to pay the participants in cents. We
            use the currency of your account.
        device_compatibility:
          type: array
          items:
            $ref: '#/components/schemas/CreateStudyDeviceCompatibilityItems'
          description: |-
            Add all devices that participants can use.
            You can include one or more options.

            An empty array indicates that all options are available.
        peripheral_requirements:
          type: array
          items:
            $ref: '#/components/schemas/CreateStudyPeripheralRequirementsItems'
          description: |-
            Add all requirements that participants have to meet.

            An empty array indicates that there are no extra peripheral requirements.
        filters:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CreateStudyFiltersItems'
          description: >-
            Array of filters.


            For advanced participant targeting with `and` / `or` groups, see [Advanced
            filtering](/api-reference/filters/advanced-filtering).


            Use empty array for "Everyone"
        filter_set_id:
          type:
            - string
            - 'null'
          description: |-
            The ID of a filter set, from which filters for the study will be taken.

            For more information, see [Filter Sets](/api-reference/filter-sets).

            Note, this cannot be used in combination with additional filters via the `filters` field.
        filter_set_version:
          type:
            - integer
            - 'null'
          description: |-
            The version of the filter set to be used.

            If not provided, this will default to the latest available version at the time of applying the filter set.
        naivety_distribution_rate:
          type:
            - number
            - 'null'
          format: double
          description: |-
            Control the balance between speed of your studies and the naivety of the participants.

            If not defined, by default Prolific calculates the best rate for most studies
            taking into account the `filters` and the `total_available_places` needed for this study.

            Use 0 if your priority is speed. When this property is set to 0 all eligible participants will have access
            to your study at the same time, without any prioritization.

            You can also set this at a workspace and project level.
        project:
          type: string
          description: >-
            Project ID. When you don't specify a project in your request, Prolific automatically uses your first created
            project as the default. For clarity, we recommend explicitly including the project ID in your requests.
        submissions_config:
          $ref: '#/components/schemas/CreateStudySubmissionsConfig'
          description: >-
            **Advanced**: This helps with faster data collection. Your survey system will need to handle providing a

            unique experience each time the participant takes the study.


            Configuration related to study submissions. The purpose of this field is to capture any configuration
            options that impact the submissions made by participants in a study.
        study_labels:
          type: array
          items:
            $ref: '#/components/schemas/CreateStudyStudyLabelsItems'
          description: >-
            This field allows you to tag studies with information about the type/topic of the study and the kind of work
            involved in completing it.


            We plan to make this information available to participants for easier self-selection. At present these
            options are mutually exclusive and only a single option can be selected, however in the future available
            categories will expand.
        content_warnings:
          type: array
          items:
            $ref: '#/components/schemas/CreateStudyContentWarningsItems'
          description: >-
            Allow researchers to define content warnings for their study.


            At present these options are mutually exclusive and only a single option can be selected, however in the
            future available warnings will expand.
        content_warning_details:
          type: string
          description: Allow researchers to add further details about their content warning.
        metadata:
          type:
            - string
            - 'null'
          description: |-
            This field can be used to store extra information required for a system integration.
            For example, it could be some JSON, XML, an integer, or a string.

            Examples could include:

              - `123345` - An ID from your system, that helps with linkage when returning the study.
              - `{ \"id\": \"45\", \"type\": \"finance\"}` - Some JSON that you want to store.
        credential_pool_id:
          type:
            - string
            - 'null'
          description: |-
            The ID of the credential pool to associate with this study. Credential pools contain
            username/password pairs that are distributed to participants when they start the study.

            When provided, participants will be assigned unique credentials from the pool. Each
            credential can only be used once and is tracked throughout the study lifecycle.

            **Note:** The credential pool must:
            - Exist and belong to the study's workspace
            - Have available (unredeemed) credentials

            See the [Credentials endpoints](#tag/Credentials) for managing credential pools.
        has_credentials:
          type: boolean
          description: |-
            Indicates whether this study requires participants to use credentials. This field is
            automatically set to `true` when a `credential_pool_id` is provided, and `false` when
            the credential pool is removed.

            **Note:** This field is automatically managed based on the `credential_pool_id` field
            and does not need to be set manually.
        data_collection_method:
          oneOf:
            - $ref: '#/components/schemas/CreateStudyDataCollectionMethod'
            - type: 'null'
          description: >-
            **Optional.** Specifies the data collection method for the study.


            - `AI_TASK_BUILDER_BATCH`: Use AI Task Builder for data annotation tasks.

            - `AI_TASK_BUILDER_COLLECTION`: Use AI Task Builder for data collection tasks.


            **Note:** This field is mutually exclusive with `external_study_url` and `access_details`. If not provided,
            you must specify one of those fields instead.
        data_collection_id:
          type:
            - string
            - 'null'
          description: >-
            The ID of the data collection batch or project from the Task Builder API.


            **Required when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH` or
            `AI_TASK_BUILDER_COLLECTION`.**
        data_collection_metadata:
          oneOf:
            - $ref: '#/components/schemas/CreateStudyDataCollectionMetadata'
            - type: 'null'
          description: >-
            **Optional.** Additional metadata for configuring AI Task Builder data annotation behavior. Only used when
            `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`.


            **Properties:**


            - `annotators_per_task` (integer): Number of annotators per task. **This field must be provided if you want
            multiple annotators per task.** Without this field, the default value of 1 will be used.
              - Minimum: 1
              - Default: 1 (if not provided)

            **Example:**

            ```json

            {
              "annotators_per_task": 5
            }

            ```


            **Important:** You must include `annotators_per_task` to control how many participants annotate each task.
            After the study is published, this value can only be increased (not decreased), which will increase the
            total available places on the study.
        access_details:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CreateStudyAccessDetailsItems'
          description: >-
            Array of access_details, which integrates with taskflow.


            While this field is nullable, you must provide one of `access_details` or `external_study_url`.


            The sum of all access_details must add to the `total_available_places` field, however the values can be
            different for an individual access_detail.
        is_external_study_url_secure:
          type: boolean
          description: >-
            When set to true, any query parameters in the external study url will be signed with a JSON Web Token. The
            token will be added to the URL as a query parameter named `prolific_token`.


            This feature is only available to certain workspaces.


            **The JWT payload**


            Header:


            ```json

            {
              "alg": "RS256",
              "kid": "<KEY_ID>",
              "typ": "JWT"
            }

            ```


            Where

            - alg is always RS256.

            - kid indicates the key ID that was used to secure the JWT.

            - typ is always JWT.


            Payload:


            ```json

            {
              "iss": "https://www.prolific.com",
              "iat": <CURRENT_TIME>,
              "exp": <CURRENT_TIME + 2 minutes>,
              "aud": "<EXTERNAL_STUDY_URL>",
              "sub": "<SESSION_ID>",
              "prolific":{
                "<QUERY_1>": "<VALUE_1>",
                "<QUERY_2>": "<VALUE_2>",
                ...
                "workspace_id": "<WORKSPACE_ID>",
                "organisation_id": "<ORGANISATION_ID>"
              }
            }

            ```


            `<ORGANISATION_ID>` appears only when the workspace is linked to an

            organisation; otherwise omit that key from `prolific`.


            The `prolific` object maps each URL parameter from your

            external study URL template to the resolved value for that

            placeholder (for example participant, study, and session

            identifiers). Prolific always adds `workspace_id` (string). When the

            workspace is linked to an organisation, `organisation_id` (string)

            is also present.


            For example (the sample below includes `organisation_id`; that key

            is omitted when the workspace has no linked organisation):


            ```json

            {
              "iss": "https://www.prolific.com",
              "iat": 1740496135,
              "exp": 1740496255,
              "aud": "https://x.com?STUDY_ID=1&...",
              "sub": "1234",
              "prolific":{
                "STUDY_ID": "abcd",
                "SESSION_ID": "1234",
                "PROLIFIC_PID": "xyz",
                "workspace_id": "507f1f77bcf86cd799439011",
                "organisation_id": "507f191e810c19729de860ea"
              }
            }

            ```


            **Verify the payload**


            When you receive the JWT, you must verify the following:

            - The JWT signature is authentic by verifying it with the public key from Prolific that correlates with the
            KID. The public keys can be retrieved from
            [/.well-known/study/jwks.json](#tag/Well-Known-Endpoints/paths/~1.well-known~1study~1jwks.json/get).

            - The JWT hasn't expired, by checking the `exp` claim.

            - The `aud` claim is the correct domain for your tool.

            - The `prolific` claim matches your expected payload as set in the `external_study_url` property. It always
            includes `workspace_id`. When the workspace is linked to an organisation, it also includes `organisation_id`
            (validate both against what your integration expects).
        id:
          type: string
          description: Study id. It is created by Prolific. **Read only**.
        status:
          $ref: '#/components/schemas/StudyStatus'
          description: |-
            Status of the study. **Read only**.

            To change the status you can use `/api/v1/studies/{id}/transition/`
        is_ready_to_publish:
          type: boolean
          description: >-
            Whether the study has all required fields completed for publishing. Does not check wallet balance or funding
            — only study-level field completeness.
      required:
        - name
        - description
        - external_study_url
        - prolific_id_option
        - total_available_places
        - estimated_completion_time
        - reward
      title: Study
    Studies_DeleteStudy_Response_200:
      type: object
      properties: {}
      description: Empty response body
      title: Studies_DeleteStudy_Response_200
    BaseStudyProlificIdOption:
      type: string
      enum:
        - question
        - url_parameters
        - not_required
      description: >-
        Use 'question' if you will add a question in your survey or experiment asking the participant ID


        **Recommended** Use 'url_parameters' if your survey or experiment can retrieve and store those parameters for
        your analysis.


        Use 'not_required' if you don't need to record them.
      title: BaseStudyProlificIdOption
    BaseStudyCompletionCodesItemsCodeType:
      type: string
      enum:
        - COMPLETED
        - FAILED_ATTENTION_CHECK
        - FOLLOW_UP_STUDY
        - GIVE_BONUS
        - INCOMPATIBLE_DEVICE
        - NO_CONSENT
        - OTHER
        - FIXED_SCREENOUT
        - SCREENED_IN
        - SCREENED_OUT
      description: >
        A name for your code to make it easier to understand its intention. Either use one of the predefined options or
        any other free text.
      title: BaseStudyCompletionCodesItemsCodeType
    BaseStudyCompletionCodesItemsActionsItems:
      oneOf:
        - $ref: '#/components/schemas/AutomaticallyApprove'
        - $ref: '#/components/schemas/AddToParticipantGroup'
        - $ref: '#/components/schemas/RemoveFromParticipantGroup'
        - $ref: '#/components/schemas/ManuallyReview'
        - $ref: '#/components/schemas/RequestReturn'
        - $ref: '#/components/schemas/DynamicPayment'
        - $ref: '#/components/schemas/FixedScreenOut'
      title: BaseStudyCompletionCodesItemsActionsItems
    BaseStudyCompletionCodesItemsActor:
      type: string
      enum:
        - participant
        - researcher
      default: participant
      description: The actor that can provide this completion code.
      title: BaseStudyCompletionCodesItemsActor
    BaseStudyCompletionCodesItems:
      type: object
      properties:
        code:
          type:
            - string
            - 'null'
          description: >
            The code the participant will either enter manually at the end of your study or be redirected as part of the
            return URL.


            If the code is null, then the participant will not be asked to submit a completion code when they return to
            Prolific.

            Null codes can only be provided when:
              - The actor is "participant"
              - There are no other completion codes with the "participant" actor
              - The actions array is empty

            The code must be unique within the study.
        code_type:
          $ref: '#/components/schemas/BaseStudyCompletionCodesItemsCodeType'
          description: >
            A name for your code to make it easier to understand its intention. Either use one of the predefined options
            or any other free text.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/BaseStudyCompletionCodesItemsActionsItems'
          description: >-
            The actions that will be completed automatically when the submission is completed with this code by the
            participant.


            You have the ability to use one or multiple `actions` together - it's up to you and your desired automated
            journey.


            If you’re looking to keep things simple, we recommend setting the `{"action": "MANUALLY_REVIEW"}` option
            only, so all submissions wait for your manual approval.
        actor:
          $ref: '#/components/schemas/BaseStudyCompletionCodesItemsActor'
          default: participant
          description: The actor that can provide this completion code.
      required:
        - code
        - code_type
        - actions
      title: BaseStudyCompletionCodesItems
    BaseStudyDeviceCompatibilityItems:
      type: string
      enum:
        - desktop
        - tablet
        - mobile
      title: BaseStudyDeviceCompatibilityItems
    BaseStudyPeripheralRequirementsItems:
      type: string
      enum:
        - audio
        - camera
        - download
        - microphone
      title: BaseStudyPeripheralRequirementsItems
    BaseStudyFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: BaseStudyFiltersItems
    BaseStudySubmissionsConfigAutoRejectionCategoriesItems:
      type: string
      enum:
        - EXCEPTIONALLY_FAST
      title: BaseStudySubmissionsConfigAutoRejectionCategoriesItems
    BaseStudySubmissionsConfig:
      type: object
      properties:
        max_submissions_per_participant:
          type:
            - integer
            - 'null'
          default: 1
          description: >-
            - **1** is the default Prolific experience. This means one submission, per participant, per study. If you do
              not specify this field, the **default is 1**.
            - **1+** turns your study into a multi-submission study, meaning a participant can create many submissions
            per study.
              As noted above, your survey system will need to handle providing a
            unique experience each time the participant takes the study.

            - **-1** will allow an indefinite number of submissions from a single participant, up to
            `total_available_places`.
        max_concurrent_submissions:
          type:
            - integer
            - 'null'
          default: -1
          description: |-
            - **-1** is the default value, meaning unlimited concurrent active/reserved submissions per study.
            - **1+** limits the number of concurrent active/reserved submissions a study can have at one time.
        auto_rejection_categories:
          type: array
          items:
            $ref: '#/components/schemas/BaseStudySubmissionsConfigAutoRejectionCategoriesItems'
          default: []
          description: >-
            List of rejection categories that trigger automatic submission rejections.


            **Available Categories:**

            - **EXCEPTIONALLY_FAST**: Automatically reject submissions completed in an exceptionally short time


            **Important Notes:**

            - **This feature is currently in an evaluation period and can be activated for your workspace upon
            request.**

            - Auto-rejections only apply to submissions in "AWAITING REVIEW" status

            - Submissions with return requests will not be auto-rejected

            - Auto-rejected submissions do not count towards your rejection limit

            - Set to an empty array `[]` or omit this field to disable auto-rejection
      description: >-
        **Advanced**: This helps with faster data collection. Your survey system will need to handle providing a

        unique experience each time the participant takes the study.


        Configuration related to study submissions. The purpose of this field is to capture any configuration options
        that impact the submissions made by participants in a study.
      title: BaseStudySubmissionsConfig
    BaseStudyStudyLabelsItems:
      type: string
      enum:
        - survey
        - writing_task
        - annotation
        - decision_making_task
        - interview
        - other
        - ai_annotation
        - ai_evaluation
        - ai_reasoning
        - ai_fact_checking
        - ai_safety
        - ai_data_creation_text
        - ai_data_creation_audio
        - ai_data_creation_video
        - ai_data_creation_images
        - ai_other
      title: BaseStudyStudyLabelsItems
    BaseStudyContentWarningsItems:
      type: string
      enum:
        - sensitive
        - explicit
      title: BaseStudyContentWarningsItems
    BaseStudyDataCollectionMethod:
      type: string
      enum:
        - AI_TASK_BUILDER_BATCH
        - AI_TASK_BUILDER_COLLECTION
      description: >-
        **Optional.** Specifies the data collection method for the study.


        - `AI_TASK_BUILDER_BATCH`: Use AI Task Builder for data annotation tasks.

        - `AI_TASK_BUILDER_COLLECTION`: Use AI Task Builder for data collection tasks.


        **Note:** This field is mutually exclusive with `external_study_url` and `access_details`. If not provided, you
        must specify one of those fields instead.
      title: BaseStudyDataCollectionMethod
    BaseStudyDataCollectionMetadata:
      type: object
      properties:
        annotators_per_task:
          type: integer
          description: >-
            Number of annotators required per task. Required for AI Task Builder Batch studies to set multiple
            annotators.
      description: >-
        **Optional.** Additional metadata for configuring AI Task Builder data annotation behavior. Only used when
        `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`.


        **Properties:**


        - `annotators_per_task` (integer): Number of annotators per task. **This field must be provided if you want
        multiple annotators per task.** Without this field, the default value of 1 will be used.
          - Minimum: 1
          - Default: 1 (if not provided)

        **Example:**

        ```json

        {
          "annotators_per_task": 5
        }

        ```


        **Important:** You must include `annotators_per_task` to control how many participants annotate each task. After
        the study is published, this value can only be increased (not decreased), which will increase the total
        available places on the study.
      title: BaseStudyDataCollectionMetadata
    BaseStudyAccessDetailsItems:
      oneOf:
        - $ref: '#/components/schemas/AccessDetail'
      title: BaseStudyAccessDetailsItems
    BaseStudy:
      type: object
      properties:
        name:
          type: string
          description: Public name or title of the study
        internal_name:
          type:
            - string
            - 'null'
          description: Internal name of the study, not shown to participants
        description:
          type: string
          description: >-
            Description of the study for the participants to read before

            starting the study


            **Supported HTML in `description`**


            The `description` field supports the following HTML tags for formatting participant instructions:


            * `<b>` - bold

            * `<i>` - italic

            * `<em>` - emphasized text

            * `<strong>` - strong importance

            * `<s>` - strikethrough

            * `<u>` - underline

            * `<h1>` - heading level 1

            * `<h2>` - heading level 2

            * `<ol>` - ordered list

            * `<ul>` - unordered list

            * `<li>` - list item

            * `<p>` - paragraph


            Other HTML tags will be stripped or escaped. Please ensure that you only use supported tags for formatting
            to avoid rendering issues.
        external_study_url:
          type: string
          description: >-
            URL of the survey or experiment you want participant to access. You can pass URL search parameters to your
            survey or experiment


            * Participant id {{%PROLIFIC_PID%}}

            * Study id {{%STUDY_ID%}}

            * Session id {{%SESSION_ID%}}


            For example `https://eggs-experriment.com?participant={{%PROLIFIC_PID%}}`
        prolific_id_option:
          $ref: '#/components/schemas/BaseStudyProlificIdOption'
          description: >-
            Use 'question' if you will add a question in your survey or experiment asking the participant ID


            **Recommended** Use 'url_parameters' if your survey or experiment can retrieve and store those parameters
            for your analysis.


            Use 'not_required' if you don't need to record them.
        completion_codes:
          type: array
          items:
            $ref: '#/components/schemas/BaseStudyCompletionCodesItems'
          description: >-
            Specify at least one completion code for your study. A participant will enter one of these codes when they
            complete your study.


            Each code must be unique within a study.


            You can specify as many actions as you like per code. However, some actions can't be used together (e.g.
            AutomaticallyApprove and ManuallyReview).


            **Note:** This field is optional when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH` or
            `AI_TASK_BUILDER_COLLECTION`. When omitted, a default COMPLETED code with a `MANUALLY_REVIEW` action is
            auto-generated. When provided, AITB studies must include exactly one code with `code_type` of `COMPLETED`
            and an action of `MANUALLY_REVIEW` or `AUTOMATICALLY_APPROVE`.
        total_available_places:
          type: number
          format: double
          description: >-
            How many participants are you looking to recruit.


            **Note:** This field is optional when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`, as the
            total available places are automatically calculated from the batch configuration.
        estimated_completion_time:
          type: number
          format: double
          description: Estimated duration in minutes of the experiment or survey
        maximum_allowed_time:
          type: number
          format: double
          description: >-
            Max time in minutes for a participant to finish the submission. Submissions are timed out if it takes
            longer.


            If it is not provided the default value is set to the max value.


            The min value is calculated as two minutes plus two times the estimated time plus two times the square root
            of the estimated time
        reward:
          type: number
          format: double
          description: |-
            How much are you going to pay the participants in cents. We
            use the currency of your account.
        device_compatibility:
          type: array
          items:
            $ref: '#/components/schemas/BaseStudyDeviceCompatibilityItems'
          description: |-
            Add all devices that participants can use.
            You can include one or more options.

            An empty array indicates that all options are available.
        peripheral_requirements:
          type: array
          items:
            $ref: '#/components/schemas/BaseStudyPeripheralRequirementsItems'
          description: |-
            Add all requirements that participants have to meet.

            An empty array indicates that there are no extra peripheral requirements.
        filters:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/BaseStudyFiltersItems'
          description: >-
            Array of filters.


            For advanced participant targeting with `and` / `or` groups, see [Advanced
            filtering](/api-reference/filters/advanced-filtering).


            Use empty array for "Everyone"
        filter_set_id:
          type:
            - string
            - 'null'
          description: |-
            The ID of a filter set, from which filters for the study will be taken.

            For more information, see [Filter Sets](/api-reference/filter-sets).

            Note, this cannot be used in combination with additional filters via the `filters` field.
        filter_set_version:
          type:
            - integer
            - 'null'
          description: |-
            The version of the filter set to be used.

            If not provided, this will default to the latest available version at the time of applying the filter set.
        naivety_distribution_rate:
          type:
            - number
            - 'null'
          format: double
          description: |-
            Control the balance between speed of your studies and the naivety of the participants.

            If not defined, by default Prolific calculates the best rate for most studies
            taking into account the `filters` and the `total_available_places` needed for this study.

            Use 0 if your priority is speed. When this property is set to 0 all eligible participants will have access
            to your study at the same time, without any prioritization.

            You can also set this at a workspace and project level.
        project:
          type: string
          description: >-
            Project ID. When you don't specify a project in your request, Prolific automatically uses your first created
            project as the default. For clarity, we recommend explicitly including the project ID in your requests.
        submissions_config:
          $ref: '#/components/schemas/BaseStudySubmissionsConfig'
          description: >-
            **Advanced**: This helps with faster data collection. Your survey system will need to handle providing a

            unique experience each time the participant takes the study.


            Configuration related to study submissions. The purpose of this field is to capture any configuration
            options that impact the submissions made by participants in a study.
        study_labels:
          type: array
          items:
            $ref: '#/components/schemas/BaseStudyStudyLabelsItems'
          description: >-
            This field allows you to tag studies with information about the type/topic of the study and the kind of work
            involved in completing it.


            We plan to make this information available to participants for easier self-selection. At present these
            options are mutually exclusive and only a single option can be selected, however in the future available
            categories will expand.
        content_warnings:
          type: array
          items:
            $ref: '#/components/schemas/BaseStudyContentWarningsItems'
          description: >-
            Allow researchers to define content warnings for their study.


            At present these options are mutually exclusive and only a single option can be selected, however in the
            future available warnings will expand.
        content_warning_details:
          type: string
          description: Allow researchers to add further details about their content warning.
        metadata:
          type:
            - string
            - 'null'
          description: |-
            This field can be used to store extra information required for a system integration.
            For example, it could be some JSON, XML, an integer, or a string.

            Examples could include:

              - `123345` - An ID from your system, that helps with linkage when returning the study.
              - `{ \"id\": \"45\", \"type\": \"finance\"}` - Some JSON that you want to store.
        credential_pool_id:
          type:
            - string
            - 'null'
          description: |-
            The ID of the credential pool to associate with this study. Credential pools contain
            username/password pairs that are distributed to participants when they start the study.

            When provided, participants will be assigned unique credentials from the pool. Each
            credential can only be used once and is tracked throughout the study lifecycle.

            **Note:** The credential pool must:
            - Exist and belong to the study's workspace
            - Have available (unredeemed) credentials

            See the [Credentials endpoints](#tag/Credentials) for managing credential pools.
        has_credentials:
          type: boolean
          description: |-
            Indicates whether this study requires participants to use credentials. This field is
            automatically set to `true` when a `credential_pool_id` is provided, and `false` when
            the credential pool is removed.

            **Note:** This field is automatically managed based on the `credential_pool_id` field
            and does not need to be set manually.
        data_collection_method:
          oneOf:
            - $ref: '#/components/schemas/BaseStudyDataCollectionMethod'
            - type: 'null'
          description: >-
            **Optional.** Specifies the data collection method for the study.


            - `AI_TASK_BUILDER_BATCH`: Use AI Task Builder for data annotation tasks.

            - `AI_TASK_BUILDER_COLLECTION`: Use AI Task Builder for data collection tasks.


            **Note:** This field is mutually exclusive with `external_study_url` and `access_details`. If not provided,
            you must specify one of those fields instead.
        data_collection_id:
          type:
            - string
            - 'null'
          description: >-
            The ID of the data collection batch or project from the Task Builder API.


            **Required when `data_collection_method` is set to `AI_TASK_BUILDER_BATCH` or
            `AI_TASK_BUILDER_COLLECTION`.**
        data_collection_metadata:
          oneOf:
            - $ref: '#/components/schemas/BaseStudyDataCollectionMetadata'
            - type: 'null'
          description: >-
            **Optional.** Additional metadata for configuring AI Task Builder data annotation behavior. Only used when
            `data_collection_method` is set to `AI_TASK_BUILDER_BATCH`.


            **Properties:**


            - `annotators_per_task` (integer): Number of annotators per task. **This field must be provided if you want
            multiple annotators per task.** Without this field, the default value of 1 will be used.
              - Minimum: 1
              - Default: 1 (if not provided)

            **Example:**

            ```json

            {
              "annotators_per_task": 5
            }

            ```


            **Important:** You must include `annotators_per_task` to control how many participants annotate each task.
            After the study is published, this value can only be increased (not decreased), which will increase the
            total available places on the study.
        access_details:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/BaseStudyAccessDetailsItems'
          description: >-
            Array of access_details, which integrates with taskflow.


            While this field is nullable, you must provide one of `access_details` or `external_study_url`.


            The sum of all access_details must add to the `total_available_places` field, however the values can be
            different for an individual access_detail.
        is_external_study_url_secure:
          type: boolean
          description: >-
            When set to true, any query parameters in the external study url will be signed with a JSON Web Token. The
            token will be added to the URL as a query parameter named `prolific_token`.


            This feature is only available to certain workspaces.


            **The JWT payload**


            Header:


            ```json

            {
              "alg": "RS256",
              "kid": "<KEY_ID>",
              "typ": "JWT"
            }

            ```


            Where

            - alg is always RS256.

            - kid indicates the key ID that was used to secure the JWT.

            - typ is always JWT.


            Payload:


            ```json

            {
              "iss": "https://www.prolific.com",
              "iat": <CURRENT_TIME>,
              "exp": <CURRENT_TIME + 2 minutes>,
              "aud": "<EXTERNAL_STUDY_URL>",
              "sub": "<SESSION_ID>",
              "prolific":{
                "<QUERY_1>": "<VALUE_1>",
                "<QUERY_2>": "<VALUE_2>",
                ...
                "workspace_id": "<WORKSPACE_ID>",
                "organisation_id": "<ORGANISATION_ID>"
              }
            }

            ```


            `<ORGANISATION_ID>` appears only when the workspace is linked to an

            organisation; otherwise omit that key from `prolific`.


            The `prolific` object maps each URL parameter from your

            external study URL template to the resolved value for that

            placeholder (for example participant, study, and session

            identifiers). Prolific always adds `workspace_id` (string). When the

            workspace is linked to an organisation, `organisation_id` (string)

            is also present.


            For example (the sample below includes `organisation_id`; that key

            is omitted when the workspace has no linked organisation):


            ```json

            {
              "iss": "https://www.prolific.com",
              "iat": 1740496135,
              "exp": 1740496255,
              "aud": "https://x.com?STUDY_ID=1&...",
              "sub": "1234",
              "prolific":{
                "STUDY_ID": "abcd",
                "SESSION_ID": "1234",
                "PROLIFIC_PID": "xyz",
                "workspace_id": "507f1f77bcf86cd799439011",
                "organisation_id": "507f191e810c19729de860ea"
              }
            }

            ```


            **Verify the payload**


            When you receive the JWT, you must verify the following:

            - The JWT signature is authentic by verifying it with the public key from Prolific that correlates with the
            KID. The public keys can be retrieved from
            [/.well-known/study/jwks.json](#tag/Well-Known-Endpoints/paths/~1.well-known~1study~1jwks.json/get).

            - The JWT hasn't expired, by checking the `exp` claim.

            - The `aud` claim is the correct domain for your tool.

            - The `prolific` claim matches your expected payload as set in the `external_study_url` property. It always
            includes `workspace_id`. When the workspace is linked to an organisation, it also includes `organisation_id`
            (validate both against what your integration expects).
      title: BaseStudy
    StudyTransitionAction:
      type: string
      enum:
        - PUBLISH
        - SCHEDULE_PUBLISH
        - CANCEL_PUBLISH
        - PAUSE
        - START
        - STOP
      description: The transition action to execute on the study.
      title: StudyTransitionAction
    StudyTransition:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/StudyTransitionAction'
          description: The transition action to execute on the study.
        publish_at:
          type: string
          format: date-time
          description: >-
            ISO 8601 datetime for when the study should be published. Required in the request when action is
            SCHEDULE_PUBLISH and the study does not already have a publish_at set.
      required:
        - action
      title: StudyTransition
    TestStudySetUpResponse:
      type: object
      properties:
        study_id:
          type: string
          format: objectId
          description: The ID of the study that was created for the test.
        study_url:
          type: string
          format: uri
          description: The URL of the study that was created for the test.
      title: TestStudySetUpResponse
    AccessDetailProgress:
      type: object
      properties:
        external_url:
          type: string
          description: >-
            URL of the task you want to send the participant to. You can pass URL search parameters as in
            `external_study_url`.
        total_allocation:
          type: number
          format: double
          description: >-
            The base number of places set by the researcher for this URL. This is the value used to determine the
            study's total available places and will match what was submitted when creating or updating the study.


            This value does not include screenout-driven capacity. For studies with custom screening (fixed screen-out
            reward), `allocated` may exceed `total_allocation` — use `capacity_increments` to understand why.
        allocated:
          type: number
          format: double
          description: >-
            The number of participants currently allocated to this URL.


            For studies with custom screening (fixed screen-out reward), this value may exceed `total_allocation`. This
            occurs when participants have been screened out — each screenout adds 1 to `capacity_increments`, allowing a
            replacement participant to be allocated. The relationship is always: `allocated ≤ total_allocation +
            capacity_increments`.
        capacity_increments:
          type: number
          format: double
          description: >-
            The cumulative number of additional capacity slots added to this URL by screenout events. Each time a
            participant is screened out, this value increases by 1, allowing a replacement participant to be allocated
            in their place.


            This field is read-only and system-managed — it cannot be set when creating or updating a study. It will be
            absent (or 0) for URLs where no screenouts have occurred.


            **Example:** If `total_allocation` is 10, `capacity_increments` is 3, and `allocated` is 11, it means 3
            participants were screened out, creating 3 extra slots, and 11 participants have been allocated in total — 2
            slots remain.
      required:
        - external_url
        - total_allocation
      title: AccessDetailProgress
    StudyAccessDetailsProgress:
      type: object
      properties:
        id:
          type: string
          description: The access details collection ID for this study's Taskflow configuration.
        progress:
          type: array
          items:
            $ref: '#/components/schemas/AccessDetailProgress'
          description: One row per `external_url` configured on the study.
        _links:
          type: object
          additionalProperties:
            description: Any type
          description: HAL-style links; typically includes `self` pointing at this endpoint.
      required:
        - id
        - progress
      title: StudyAccessDetailsProgress
    AmountAndCurrency:
      type: object
      properties:
        amount:
          type: number
          format: double
          description: Amount in subcurrency. £1 will return 100
        currency:
          type: string
          description: Currency Code
      title: AmountAndCurrency
    StudyCostBreakdown:
      type: object
      properties:
        rewards:
          $ref: '#/components/schemas/AmountAndCurrency'
        fees:
          $ref: '#/components/schemas/AmountAndCurrency'
        tax:
          $ref: '#/components/schemas/AmountAndCurrency'
      title: StudyCostBreakdown
    StudyTotalCost:
      type: object
      properties:
        rewards:
          $ref: '#/components/schemas/StudyCostBreakdown'
        bonuses:
          $ref: '#/components/schemas/StudyCostBreakdown'
        _links:
          type: object
          additionalProperties:
            description: Any type
      title: StudyTotalCost
    SubmissionShortStatus:
      type: string
      enum:
        - RESERVED
        - ACTIVE
        - TIMED-OUT
        - AWAITING REVIEW
        - APPROVED
        - RETURNED
        - REJECTED
        - SCREENED OUT
      description: Status of the submission.
      title: SubmissionShortStatus
    SubmissionShort:
      type: object
      properties:
        id:
          type: string
          description: Submission id.
        participant_id:
          type: string
          description: Participant id.
        status:
          $ref: '#/components/schemas/SubmissionShortStatus'
          description: Status of the submission.
        started_at:
          type: string
          format: date-time
          description: Date started
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Date completed
        has_siblings:
          type: boolean
          description: Whether or not the submission has sibling submissions (sharing the same study).
        study_code:
          type:
            - string
            - 'null'
          description: The completion code used by the participant to complete the study.
        return_requested:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time when a return request for the submission was made.
      required:
        - id
        - participant_id
        - status
        - started_at
        - has_siblings
      title: SubmissionShort
    SubmissionListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SubmissionShort'
          description: List of all submissions matching the criteria.
      required:
        - results
      title: SubmissionListResponse
    SubmissionsCountResponse:
      type: object
      properties:
        ACTIVE:
          type: number
          format: double
        APPROVED:
          type: number
          format: double
        AWAITING REVIEW:
          type: number
          format: double
        REJECTED:
          type: number
          format: double
        RESERVED:
          type: number
          format: double
        RETURNED:
          type: number
          format: double
        TIMED-OUT:
          type: number
          format: double
        PARTIALLY APPROVED:
          type: number
          format: double
        SCREENED OUT:
          type: number
          format: double
        TOTAL:
          type: number
          format: double
          description: The total number of submissions in the study.
      title: SubmissionsCountResponse
    DemographicExportRequestFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: DemographicExportRequestFiltersItems
    DemographicExportRequest:
      type: object
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/DemographicExportRequestFiltersItems'
          description: >-
            List of filters to apply to the demographic export.


            When filters are provided, the export includes both base demographic data and responses to the specified
            filters which were applied to the study.


            When empty, only base demographic data (age, sex, country, etc.) for all participants who took the study is
            exported, excluding study-specific filter responses.
      title: DemographicExportRequest
    DemographicExportHistoryResponseFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: DemographicExportHistoryResponseFiltersItems
    DemographicExportHistoryResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of different filter combinations that have been requested for demographic export
        filters:
          type: array
          items:
            $ref: '#/components/schemas/DemographicExportHistoryResponseFiltersItems'
          description: >-
            The filters used in the most recent export request. Returns an empty array if no exports have been requested
            yet.


            This shows you exactly what filter combination was used in your latest request, helping you track your
            export usage.
      required:
        - count
        - filters
      description: Response containing the latest demographic export request history for a study
      title: DemographicExportHistoryResponse
    StudyPredictedRecruitmentTimeResponse:
      type: object
      properties:
        precise_recruitment_time_hours:
          type: number
          format: double
          description: The predicted recruitment time in hours
        lower_bound_hours:
          type: number
          format: double
          description: The lower bound of the predicted recruitment time in hours
        upper_bound_hours:
          type: number
          format: double
          description: The upper bound of the predicted recruitment time in hours
        display_string:
          type: string
          description: A human-readable string representing the predicted recruitment time
        limit_at:
          type: number
          format: double
          description: |-
            The limit at which the accuracy of the prediction becomes unstable.
            This should be used when rendering the recruitment times in a GUI. For example if the limit_at is 10,
            and the predicted recruitment time is 12 hours, the display string should be "10 hours+". This
            has been done for you in the display_string field.
      title: StudyPredictedRecruitmentTimeResponse
    StudyPredictedRecruitmentTimeRequestFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: StudyPredictedRecruitmentTimeRequestFiltersItems
    StudyPredictedRecruitmentTimeRequestStudyType:
      type: string
      enum:
        - SINGLE
        - UK_REP_SAMPLE
        - REP_SAMPLE_UK_ENGLISH_AGE_POLITICAL_AFFILIATION_ETHNICITY
        - REP_SAMPLE_UK_ENGLISH_AGE_POLITICAL_AFFILIATION
        - US_REP_SAMPLE
        - REP_SAMPLE_US_ENGLISH_AGE_POLITICAL_AFFILIATION_ETHNICITY
        - REP_SAMPLE_US_ENGLISH_AGE_POLITICAL_AFFILIATION
        - UK_REGIONAL_REP_SAMPLE
        - US_REGIONAL_REP_SAMPLE
      description: Type of study.
      title: StudyPredictedRecruitmentTimeRequestStudyType
    StudyPredictedRecruitmentTimeRequestDeviceCompatibilityItems:
      type: string
      enum:
        - desktop
        - tablet
        - mobile
      title: StudyPredictedRecruitmentTimeRequestDeviceCompatibilityItems
    StudyPredictedRecruitmentTimeRequestPeripheralRequirementsItems:
      type: string
      enum:
        - audio
        - camera
        - download
        - microphone
      title: StudyPredictedRecruitmentTimeRequestPeripheralRequirementsItems
    StudyPredictedRecruitmentTimeRequestStudyLabels:
      type: string
      enum:
        - survey
        - writing_task
        - annotation
        - decision_making_task
        - interview
        - other
        - ai_annotation
        - ai_evaluation
        - ai_reasoning
        - ai_fact_checking
        - ai_safety
        - ai_data_creation_text
        - ai_data_creation_audio
        - ai_data_creation_video
        - ai_data_creation_images
        - ai_other
      description: The field that the study is about to get tagged with.
      title: StudyPredictedRecruitmentTimeRequestStudyLabels
    StudyPredictedRecruitmentTimeRequest:
      type: object
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/StudyPredictedRecruitmentTimeRequestFiltersItems'
          description: |-
            List of filters to apply to the count. This parameter uses the new, simplified
            filters schema for interacting with eligibility.
        workspace_id:
          type: string
          description: The ID of the workspace the study will be created in.
        reward:
          type: number
          format: double
          description: How much are you going to pay the participants in cents. We use the currency of the workspace
        study_type:
          $ref: '#/components/schemas/StudyPredictedRecruitmentTimeRequestStudyType'
          description: Type of study.
        total_available_places:
          type: number
          format: double
          description: How many participants are you looking to recruit
        estimated_completion_time:
          type: number
          format: double
          description: Estimated duration in minutes of the experiment or survey
        device_compatibility:
          type: array
          items:
            $ref: '#/components/schemas/StudyPredictedRecruitmentTimeRequestDeviceCompatibilityItems'
          description: |-
            Add all devices that participants can use.
            You can include one or more options.
        peripheral_requirements:
          type: array
          items:
            $ref: '#/components/schemas/StudyPredictedRecruitmentTimeRequestPeripheralRequirementsItems'
          description: Add all requirements that participants have to meet.
        study_labels:
          $ref: '#/components/schemas/StudyPredictedRecruitmentTimeRequestStudyLabels'
          description: The field that the study is about to get tagged with.
      required:
        - filters
        - workspace_id
        - reward
        - study_type
        - total_available_places
        - estimated_completion_time
      title: StudyPredictedRecruitmentTimeRequest
    StudyCostRequest:
      type: object
      properties:
        reward:
          type: number
          format: double
          description: How much are you going to pay the participants in cents. We use the currency of your account
        total_available_places:
          type: number
          format: double
          description: How many participants are you looking to recruit
      required:
        - reward
        - total_available_places
      title: StudyCostRequest
    StudyCostResponse:
      type: object
      properties:
        total_cost:
          type: number
          format: double
          description: >-
            Total cost of the study including VAT and fees in cents. We use your account VAT and Fee percentage. The
            amount is in your account's currency.
      required:
        - total_cost
      title: StudyCostResponse
    SelectFilterListResponseType:
      type: string
      enum:
        - select
        - range
      description: The filter type.
      title: SelectFilterListResponseType
    SelectFilterListResponseDataType:
      type: string
      enum:
        - ChoiceID
        - ParticipantID
        - StudyID
        - ParticipantGroupID
      description: |-
        The format of the keys in the choices object. If the keys are strings representing sequential integers,
        the data format is integer. If the keys are database ObjectIDs, the type of ID is specified.
      title: SelectFilterListResponseDataType
    SelectFilterListResponse:
      type: object
      properties:
        filter_id:
          type: string
          description: The ID of the filter, based on a slugified version of the title at the time the filter was created.
        title:
          type: string
          description: The title of the filter.
        description:
          type: string
          description: A description of the filter.
        type:
          $ref: '#/components/schemas/SelectFilterListResponseType'
          description: The filter type.
        question:
          type: string
          description: The question asked of participants to generate this filter.
        choices:
          type: object
          additionalProperties:
            description: Any type
          description: >-
            An object containing all the filter's possible responses as key-value pairs, with sequential integer IDs or
            database ObjectIDs as the keys and the text of the response as the values.
        data_type:
          $ref: '#/components/schemas/SelectFilterListResponseDataType'
          description: |-
            The format of the keys in the choices object. If the keys are strings representing sequential integers,
            the data format is integer. If the keys are database ObjectIDs, the type of ID is specified.
      title: SelectFilterListResponse
    SelectFilterListDetailedResponseType:
      type: string
      enum:
        - select
        - range
      description: The filter type.
      title: SelectFilterListDetailedResponseType
    SelectFilterListDetailedResponseDataType:
      type: string
      enum:
        - ChoiceID
        - ParticipantID
        - StudyID
        - ParticipantGroupID
      description: |-
        The format of the keys in the choices object. If the keys are strings representing sequential integers,
        the data format is integer. If the keys are database ObjectIDs, the type of ID is specified.
      title: SelectFilterListDetailedResponseDataType
    SelectFilterListDetailedResponse:
      type: object
      properties:
        filter_id:
          type: string
          description: The ID of the filter, based on a slugified version of the title at the time the filter was created.
        title:
          type: string
          description: The title of the filter.
        description:
          type: string
          description: A description of the filter.
        type:
          $ref: '#/components/schemas/SelectFilterListDetailedResponseType'
          description: The filter type.
        question:
          type: string
          description: The question asked of participants to generate this filter.
        choices:
          type: object
          additionalProperties:
            description: Any type
          description: >-
            An object containing all the filter's possible responses as key-value pairs, with sequential integer IDs or
            database ObjectIDs as the keys and the text of the response as the values.
        data_type:
          $ref: '#/components/schemas/SelectFilterListDetailedResponseDataType'
          description: |-
            The format of the keys in the choices object. If the keys are strings representing sequential integers,
            the data format is integer. If the keys are database ObjectIDs, the type of ID is specified.
        researcher_help_text:
          type:
            - string
            - 'null'
          description: Some help text to be displayed to researchers in the filter selection modal.
        participant_help_text:
          type:
            - string
            - 'null'
          description: Some help text to be displayed to participants in the About You section.
        category:
          type:
            - string
            - 'null'
          description: The category the filter is displayed in About You and the filter selection modal.
        subcategory:
          type:
            - string
            - 'null'
          description: The sub-category the filter is displayed in the filter selection modal.
        display_order:
          type:
            - integer
            - 'null'
          description: The order in which the filter is displayed within its sub-category in the filter selection modal.
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
          description: >-
            Some additional tags that can be used to display the filter in a specific way, e.g. recommended, new,
            expiring.
      title: SelectFilterListDetailedResponse
    RangeFilterListResponseType:
      type: string
      enum:
        - select
        - range
      description: The filter type.
      title: RangeFilterListResponseType
    RangeFilterListResponseMin:
      oneOf:
        - type: integer
        - type: number
          format: double
        - type: string
      description: The minimum valid value of the range.
      title: RangeFilterListResponseMin
    RangeFilterListResponseMax:
      oneOf:
        - type: integer
        - type: number
          format: double
        - type: string
      description: The maximum valid value of the range.
      title: RangeFilterListResponseMax
    RangeFilterListResponseDataType:
      type: string
      enum:
        - date
        - integer
        - float
      description: >-
        The data type of the range.

        - If the data type is integer, the lower and upper values must be integers. Example: `70`.

        - If the data type is date, the lower and upper values must be ISO8601 dates. Example: `2025-07-11`.

        - If the data type is float, the lower and upper values can be provided as floats or integers. Returned values
        will be floats. Example: `70.5` or `80.0`.
      title: RangeFilterListResponseDataType
    RangeFilterListResponseMinMax:
      oneOf:
        - type: integer
        - type: number
          format: double
        - type: string
      description: Optional maximum allowed value for the selected_range lower bound.
      title: RangeFilterListResponseMinMax
    RangeFilterListResponseMaxMin:
      oneOf:
        - type: integer
        - type: number
          format: double
        - type: string
      description: Optional minimum allowed value for the selected_range upper bound.
      title: RangeFilterListResponseMaxMin
    RangeFilterListResponse:
      type: object
      properties:
        filter_id:
          type: string
          description: The ID of the filter, based on a slugified version of the title at the time the filter was created.
        title:
          type: string
          description: The title of the filter.
        description:
          type: string
          description: A description of the filter.
        type:
          $ref: '#/components/schemas/RangeFilterListResponseType'
          description: The filter type.
        question:
          type: string
          description: The question asked of participants to generate this filter.
        min:
          $ref: '#/components/schemas/RangeFilterListResponseMin'
          description: The minimum valid value of the range.
        max:
          $ref: '#/components/schemas/RangeFilterListResponseMax'
          description: The maximum valid value of the range.
        data_type:
          $ref: '#/components/schemas/RangeFilterListResponseDataType'
          description: >-
            The data type of the range.

            - If the data type is integer, the lower and upper values must be integers. Example: `70`.

            - If the data type is date, the lower and upper values must be ISO8601 dates. Example: `2025-07-11`.

            - If the data type is float, the lower and upper values can be provided as floats or integers. Returned
            values will be floats. Example: `70.5` or `80.0`.
        min_max:
          $ref: '#/components/schemas/RangeFilterListResponseMinMax'
          description: Optional maximum allowed value for the selected_range lower bound.
        max_min:
          $ref: '#/components/schemas/RangeFilterListResponseMaxMin'
          description: Optional minimum allowed value for the selected_range upper bound.
      title: RangeFilterListResponse
    RangeFilterListDetailedResponseType:
      type: string
      enum:
        - select
        - range
      description: The filter type.
      title: RangeFilterListDetailedResponseType
    RangeFilterListDetailedResponseMin:
      oneOf:
        - type: integer
        - type: number
          format: double
        - type: string
      description: The minimum valid value of the range.
      title: RangeFilterListDetailedResponseMin
    RangeFilterListDetailedResponseMax:
      oneOf:
        - type: integer
        - type: number
          format: double
        - type: string
      description: The maximum valid value of the range.
      title: RangeFilterListDetailedResponseMax
    RangeFilterListDetailedResponseDataType:
      type: string
      enum:
        - date
        - integer
        - float
      description: >-
        The data type of the range.

        - If the data type is integer, the lower and upper values must be integers. Example: `70`.

        - If the data type is date, the lower and upper values must be ISO8601 dates. Example: `2025-07-11`.

        - If the data type is float, the lower and upper values can be provided as floats or integers. Returned values
        will be floats. Example: `70.5` or `80.0`.
      title: RangeFilterListDetailedResponseDataType
    RangeFilterListDetailedResponseMinMax:
      oneOf:
        - type: integer
        - type: number
          format: double
        - type: string
      description: Optional maximum allowed value for the selected_range lower bound.
      title: RangeFilterListDetailedResponseMinMax
    RangeFilterListDetailedResponseMaxMin:
      oneOf:
        - type: integer
        - type: number
          format: double
        - type: string
      description: Optional minimum allowed value for the selected_range upper bound.
      title: RangeFilterListDetailedResponseMaxMin
    RangeFilterListDetailedResponse:
      type: object
      properties:
        filter_id:
          type: string
          description: The ID of the filter, based on a slugified version of the title at the time the filter was created.
        title:
          type: string
          description: The title of the filter.
        description:
          type: string
          description: A description of the filter.
        type:
          $ref: '#/components/schemas/RangeFilterListDetailedResponseType'
          description: The filter type.
        question:
          type: string
          description: The question asked of participants to generate this filter.
        min:
          $ref: '#/components/schemas/RangeFilterListDetailedResponseMin'
          description: The minimum valid value of the range.
        max:
          $ref: '#/components/schemas/RangeFilterListDetailedResponseMax'
          description: The maximum valid value of the range.
        data_type:
          $ref: '#/components/schemas/RangeFilterListDetailedResponseDataType'
          description: >-
            The data type of the range.

            - If the data type is integer, the lower and upper values must be integers. Example: `70`.

            - If the data type is date, the lower and upper values must be ISO8601 dates. Example: `2025-07-11`.

            - If the data type is float, the lower and upper values can be provided as floats or integers. Returned
            values will be floats. Example: `70.5` or `80.0`.
        min_max:
          $ref: '#/components/schemas/RangeFilterListDetailedResponseMinMax'
          description: Optional maximum allowed value for the selected_range lower bound.
        max_min:
          $ref: '#/components/schemas/RangeFilterListDetailedResponseMaxMin'
          description: Optional minimum allowed value for the selected_range upper bound.
        researcher_help_text:
          type:
            - string
            - 'null'
          description: Some help text to be displayed to researchers in the filter selection modal.
        participant_help_text:
          type:
            - string
            - 'null'
          description: Some help text to be displayed to participants in the About You section.
        category:
          type:
            - string
            - 'null'
          description: The category the filter is displayed in About You and the filter selection modal.
        subcategory:
          type:
            - string
            - 'null'
          description: The sub-category the filter is displayed in the filter selection modal.
        display_order:
          type:
            - integer
            - 'null'
          description: The order in which the filter is displayed within its sub-category in the filter selection modal.
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
          description: >-
            Some additional tags that can be used to display the filter in a specific way, e.g. recommended, new,
            expiring.
      title: RangeFilterListDetailedResponse
    FilterListResultsItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilterListResponse'
        - $ref: '#/components/schemas/SelectFilterListDetailedResponse'
        - $ref: '#/components/schemas/RangeFilterListResponse'
        - $ref: '#/components/schemas/RangeFilterListDetailedResponse'
      title: FilterListResultsItems
    FilterList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/FilterListResultsItems'
        _links:
          type: object
          additionalProperties:
            description: Any type
        meta:
          type: object
          additionalProperties:
            description: Any type
      title: FilterList
    FilterDistributionDistribution:
      oneOf:
        - type: object
          additionalProperties:
            type: integer
        - type: object
          additionalProperties:
            type: integer
      title: FilterDistributionDistribution
    FilterDistribution:
      type: object
      properties:
        distribution:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FilterDistributionDistribution'
          description: Distribution data for the specified `distribution_filters`
      title: FilterDistribution
    RequirementsCountRequestFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: RequirementsCountRequestFiltersItems
    RequirementsCountRequest:
      type: object
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/RequirementsCountRequestFiltersItems'
          description: |-
            List of filters to apply to the count. This parameter uses the new, simplified
            filters schema for interacting with eligibility.
        workspace_id:
          type: string
          description: |-
            The ID of the workspace you will be creating a study in.

            Due to US tax laws, non US residents may not participate in studies created by US researchers.
            For this reason, we use the country specified in the workspace to determine eligibility.

            If you do not specify a workspace ID, we will use the current workspace ID of the user making the request.
            Your eligibility count may not be accurate if you do not specify a workspace ID.
        organisation_id:
          type: string
          description: The ID of the workspace you will be creating a filterset in.
      required:
        - filters
      title: RequirementsCountRequest
    RequirementsCount:
      type: object
      properties:
        count:
          type: number
          format: double
          description: Number of participants passing all the requirements
      required:
        - count
      title: RequirementsCount
    FilterSetFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: FilterSetFiltersItems
    FilterSet:
      type: object
      properties:
        id:
          type: string
          description: ID of the filter set.
        version:
          type: integer
          description: An incrementing integer indicating the version of the filter set.
        is_deleted:
          type: boolean
          description: Whether the filter set has been deleted.
        is_locked:
          type: boolean
          description: Whether the filter set has been locked.
        workspace_id:
          type:
            - string
            - 'null'
          description: ID of the workspace where the filter set can be used.
        organisation_id:
          type:
            - string
            - 'null'
          description: ID of the workspace where the filter set can be used.
        name:
          type: string
          description: Name of the filter set.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/FilterSetFiltersItems'
          description: List of all filters contained in the filter set.
      title: FilterSet
    FilterSetList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/FilterSet'
          description: List of filter sets.
      title: FilterSetList
    CreateFilterSetFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: CreateFilterSetFiltersItems
    CreateFilterSet:
      type: object
      properties:
        workspace_id:
          type: string
          description: ID of the workspace where the filter set can be used.
        organisation_id:
          type: string
          description: ID of the organisation where the filter set can be used.
        name:
          type: string
          description: Name of the filter set.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/CreateFilterSetFiltersItems'
          description: List of all filters contained in the filter set.
      title: CreateFilterSet
    ApiV1FilterSetsPostResponsesContentApplicationJsonSchemaFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: ApiV1FilterSetsPostResponsesContentApplicationJsonSchemaFiltersItems
    Filter Sets_CreateFilterSet_Response_201:
      type: object
      properties:
        id:
          type: string
          description: ID of the filter set.
        version:
          type: integer
          description: An incrementing integer indicating the version of the filter set.
        is_deleted:
          type: boolean
          description: Whether the filter set has been deleted.
        is_locked:
          type: boolean
          description: Whether the filter set has been locked.
        workspace_id:
          type:
            - string
            - 'null'
          description: ID of the workspace where the filter set can be used.
        organisation_id:
          type:
            - string
            - 'null'
          description: ID of the workspace where the filter set can be used.
        name:
          type: string
          description: Name of the filter set.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/ApiV1FilterSetsPostResponsesContentApplicationJsonSchemaFiltersItems'
          description: List of all filters contained in the filter set.
        eligible_participant_count:
          type: integer
          description: |-
            The number of participants who match the filter sets filters. Please note that if the number is
            lower than 25 the count will be obscured to prevent identification of participants.
      title: Filter Sets_CreateFilterSet_Response_201
    ApiV1FilterSetsIdGetResponsesContentApplicationJsonSchemaFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: ApiV1FilterSetsIdGetResponsesContentApplicationJsonSchemaFiltersItems
    Filter Sets_GetFilterSet_Response_200:
      type: object
      properties:
        id:
          type: string
          description: ID of the filter set.
        version:
          type: integer
          description: An incrementing integer indicating the version of the filter set.
        is_deleted:
          type: boolean
          description: Whether the filter set has been deleted.
        is_locked:
          type: boolean
          description: Whether the filter set has been locked.
        workspace_id:
          type:
            - string
            - 'null'
          description: ID of the workspace where the filter set can be used.
        organisation_id:
          type:
            - string
            - 'null'
          description: ID of the workspace where the filter set can be used.
        name:
          type: string
          description: Name of the filter set.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/ApiV1FilterSetsIdGetResponsesContentApplicationJsonSchemaFiltersItems'
          description: List of all filters contained in the filter set.
        eligible_participant_count:
          type: integer
          description: |-
            The number of participants who match the filter sets filters. Please note that if the number is
            lower than 25 the count will be obscured to prevent identification of participants.
      title: Filter Sets_GetFilterSet_Response_200
    UpdateFilterSetFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: UpdateFilterSetFiltersItems
    UpdateFilterSet:
      type: object
      properties:
        name:
          type: string
          description: Name of the filter set.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/UpdateFilterSetFiltersItems'
          description: List of all filters contained in the filter set.
      title: UpdateFilterSet
    ApiV1FilterSetsIdPatchResponsesContentApplicationJsonSchemaFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: ApiV1FilterSetsIdPatchResponsesContentApplicationJsonSchemaFiltersItems
    Filter Sets_UpdateFilterSet_Response_200:
      type: object
      properties:
        id:
          type: string
          description: ID of the filter set.
        version:
          type: integer
          description: An incrementing integer indicating the version of the filter set.
        is_deleted:
          type: boolean
          description: Whether the filter set has been deleted.
        is_locked:
          type: boolean
          description: Whether the filter set has been locked.
        workspace_id:
          type:
            - string
            - 'null'
          description: ID of the workspace where the filter set can be used.
        organisation_id:
          type:
            - string
            - 'null'
          description: ID of the workspace where the filter set can be used.
        name:
          type: string
          description: Name of the filter set.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/ApiV1FilterSetsIdPatchResponsesContentApplicationJsonSchemaFiltersItems'
          description: List of all filters contained in the filter set.
        eligible_participant_count:
          type: integer
          description: |-
            The number of participants who match the filter sets filters. Please note that if the number is
            lower than 25 the count will be obscured to prevent identification of participants.
      title: Filter Sets_UpdateFilterSet_Response_200
    ApiV1FilterSetsIdClonePostResponsesContentApplicationJsonSchemaFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: ApiV1FilterSetsIdClonePostResponsesContentApplicationJsonSchemaFiltersItems
    Filter Sets_CloneFilterSet_Response_201:
      type: object
      properties:
        id:
          type: string
          description: ID of the filter set.
        version:
          type: integer
          description: An incrementing integer indicating the version of the filter set.
        is_deleted:
          type: boolean
          description: Whether the filter set has been deleted.
        is_locked:
          type: boolean
          description: Whether the filter set has been locked.
        workspace_id:
          type:
            - string
            - 'null'
          description: ID of the workspace where the filter set can be used.
        organisation_id:
          type:
            - string
            - 'null'
          description: ID of the workspace where the filter set can be used.
        name:
          type: string
          description: Name of the filter set.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/ApiV1FilterSetsIdClonePostResponsesContentApplicationJsonSchemaFiltersItems'
          description: List of all filters contained in the filter set.
        eligible_participant_count:
          type: integer
          description: |-
            The number of participants who match the filter sets filters. Please note that if the number is
            lower than 25 the count will be obscured to prevent identification of participants.
      title: Filter Sets_CloneFilterSet_Response_201
    ApiV1FilterSetsIdLockPostResponsesContentApplicationJsonSchemaFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: ApiV1FilterSetsIdLockPostResponsesContentApplicationJsonSchemaFiltersItems
    Filter Sets_LockFilterSet_Response_200:
      type: object
      properties:
        id:
          type: string
          description: ID of the filter set.
        version:
          type: integer
          description: An incrementing integer indicating the version of the filter set.
        is_deleted:
          type: boolean
          description: Whether the filter set has been deleted.
        is_locked:
          type: boolean
          description: Whether the filter set has been locked.
        workspace_id:
          type:
            - string
            - 'null'
          description: ID of the workspace where the filter set can be used.
        organisation_id:
          type:
            - string
            - 'null'
          description: ID of the workspace where the filter set can be used.
        name:
          type: string
          description: Name of the filter set.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/ApiV1FilterSetsIdLockPostResponsesContentApplicationJsonSchemaFiltersItems'
          description: List of all filters contained in the filter set.
        eligible_participant_count:
          type: integer
          description: |-
            The number of participants who match the filter sets filters. Please note that if the number is
            lower than 25 the count will be obscured to prevent identification of participants.
      title: Filter Sets_LockFilterSet_Response_200
    ApiV1FilterSetsIdUnlockPostResponsesContentApplicationJsonSchemaFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: ApiV1FilterSetsIdUnlockPostResponsesContentApplicationJsonSchemaFiltersItems
    Filter Sets_UnlockFilterSet_Response_200:
      type: object
      properties:
        id:
          type: string
          description: ID of the filter set.
        version:
          type: integer
          description: An incrementing integer indicating the version of the filter set.
        is_deleted:
          type: boolean
          description: Whether the filter set has been deleted.
        is_locked:
          type: boolean
          description: Whether the filter set has been locked.
        workspace_id:
          type:
            - string
            - 'null'
          description: ID of the workspace where the filter set can be used.
        organisation_id:
          type:
            - string
            - 'null'
          description: ID of the workspace where the filter set can be used.
        name:
          type: string
          description: Name of the filter set.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/ApiV1FilterSetsIdUnlockPostResponsesContentApplicationJsonSchemaFiltersItems'
          description: List of all filters contained in the filter set.
        eligible_participant_count:
          type: integer
          description: |-
            The number of participants who match the filter sets filters. Please note that if the number is
            lower than 25 the count will be obscured to prevent identification of participants.
      title: Filter Sets_UnlockFilterSet_Response_200
    ApiV1ParticipantGroupsGetParametersActive:
      type: string
      enum:
        - 'true'
        - 'false'
      title: ApiV1ParticipantGroupsGetParametersActive
    ApiV1ParticipantGroupsGetParametersFilter0:
      type: object
      properties:
        workspace_id:
          type: string
          description: The id of the workspace to get participant groups for
      required:
        - workspace_id
      title: ApiV1ParticipantGroupsGetParametersFilter0
    ApiV1ParticipantGroupsGetParametersFilter1:
      type: object
      properties:
        project_id:
          type: string
          description: The id of the project to get participant groups for
      required:
        - project_id
      title: ApiV1ParticipantGroupsGetParametersFilter1
    ApiV1ParticipantGroupsGetParametersFilter:
      oneOf:
        - $ref: '#/components/schemas/ApiV1ParticipantGroupsGetParametersFilter0'
        - $ref: '#/components/schemas/ApiV1ParticipantGroupsGetParametersFilter1'
      title: ApiV1ParticipantGroupsGetParametersFilter
    ParticipantGroupFeederStudiesItemsFeederCompletionCodesItemsAction:
      type: string
      enum:
        - ADD_TO_PARTICIPANT_GROUP
        - REMOVE_FROM_PARTICIPANT_GROUP
      description: The action that will be taken when this code is used.
      title: ParticipantGroupFeederStudiesItemsFeederCompletionCodesItemsAction
    ParticipantGroupFeederStudiesItemsFeederCompletionCodesItems:
      type: object
      properties:
        code:
          type: string
          description: The code that will modify the participants in this group.
        code_type:
          type: string
          description: The label or code type given to this code within the context of the study.
        action:
          $ref: '#/components/schemas/ParticipantGroupFeederStudiesItemsFeederCompletionCodesItemsAction'
          description: The action that will be taken when this code is used.
      description: The code within this study that interacts with the participant group.
      title: ParticipantGroupFeederStudiesItemsFeederCompletionCodesItems
    ParticipantGroupFeederStudiesItems:
      type: object
      properties:
        id:
          type: string
          description: The id of the study.
        name:
          type: string
          description: The name of the study.
        internal_name:
          type: string
          description: The internal name of the study.
        status:
          type: string
          description: The current status of the study.
        feeder_completion_codes:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantGroupFeederStudiesItemsFeederCompletionCodesItems'
          description: The completion codes which will modify the participants in this group.
      title: ParticipantGroupFeederStudiesItems
    ParticipantGroup:
      type: object
      properties:
        id:
          type: string
          description: The id of the participant group
        name:
          type: string
          description: The name of the participant group
        project_id:
          type:
            - string
            - 'null'
          description: The id of the project the participant group belongs to
        workspace_id:
          type:
            - string
            - 'null'
          description: >-
            The id of the workspace the participant group belongs to. A participant group can only belong to either a
            workspace or an organisation.
        organisation_id:
          type:
            - string
            - 'null'
          description: >-
            The id of the organisation the participant group belongs to. A participant group can only belong to either a
            workspace or an organisation.
        description:
          type:
            - string
            - 'null'
          description: The user-provided description of the participant group
        participant_count:
          type: integer
          description: The number of participants in the participant group
        is_deleted:
          type: boolean
          description: Whether the participant group has been deleted
        feeder_studies:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantGroupFeederStudiesItems'
          description: >-
            Details of all studies which are configured to modify the participants in this group through completion
            codes.
      title: ParticipantGroup
    ParticipantGroupListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantGroup'
      title: ParticipantGroupListResponse
    ParticipantGroupResponse:
      type: object
      properties:
        id:
          type: string
          description: The id of the participant group
        name:
          type: string
          description: The name of the participant group
        project_id:
          type:
            - string
            - 'null'
          description: The id of the project the participant group belongs to
        workspace_id:
          type:
            - string
            - 'null'
          description: >-
            The id of the workspace the participant group belongs to. A participant group can only belong to either a
            workspace or an organisation.
        organisation_id:
          type:
            - string
            - 'null'
          description: >-
            The id of the organisation the participant group belongs to. A participant group can only belong to either a
            workspace or an organisation.
        description:
          type:
            - string
            - 'null'
          description: The user-provided description of the participant group
        participant_count:
          type: integer
          description: The number of participants in the participant group
        is_deleted:
          type: boolean
          description: Whether the participant group has been deleted
        feeder_studies:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantGroupFeederStudiesItems'
          description: >-
            Details of all studies which are configured to modify the participants in this group through completion
            codes.
      title: ParticipantGroupResponse
    ParticipantGroupUpdate:
      type: object
      properties:
        name:
          type: string
          description: The name of the participant group
        participant_ids:
          type: array
          items:
            type: string
          description: >-
            The ids of participants to be included in the group.


            Note, this overwrites any existing participants in the group; use the participant group membership endpoints
            to [append](#tag/Participant-Groups/operation/AddToParticipantGroup) or
            [remove](#tag/Participant-Groups/operation/RemoveFromParticipantGroup) participants from the group.
      title: ParticipantGroupUpdate
    ParticipantGroupMembership:
      type: object
      properties:
        participant_id:
          type: string
          description: The id of the participant
        datetime_created:
          type: string
          description: The date and time the participant was added to the Participant Group
      title: ParticipantGroupMembership
    ParticipantGroupMembershipListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ParticipantGroupMembership'
      title: ParticipantGroupMembershipListResponse
    ParticipantIDList:
      type: object
      properties:
        participant_ids:
          type: array
          items:
            type: string
      title: ParticipantIDList
    ApiV1SubmissionsGetParametersStatus:
      type: string
      enum:
        - ACTIVE
        - AWAITING_REVIEW
        - APPROVED
        - PARTIALLY_APPROVED
        - REJECTED
        - RETURNED
        - SCREENED_OUT
        - TIMED-OUT
        - UNKNOWN
      title: ApiV1SubmissionsGetParametersStatus
    ApiV1SubmissionsGetParametersCompleted:
      type: string
      enum:
        - '0'
        - '1'
        - 'true'
        - 'false'
        - 'yes'
        - 'no'
        - t
        - f
      title: ApiV1SubmissionsGetParametersCompleted
    ApiV1SubmissionsGetParametersReturned:
      type: string
      enum:
        - '0'
        - '1'
        - 'true'
        - 'false'
        - 'yes'
        - 'no'
        - t
        - f
      title: ApiV1SubmissionsGetParametersReturned
    ApiV1SubmissionsGetParametersAwaitingReview:
      type: string
      enum:
        - '0'
        - '1'
        - 'true'
        - 'false'
        - 'yes'
        - 'no'
        - t
        - f
      title: ApiV1SubmissionsGetParametersAwaitingReview
    ApiV1SubmissionsGetParametersApproved:
      type: string
      enum:
        - '0'
        - '1'
        - 'true'
        - 'false'
        - 'yes'
        - 'no'
        - t
        - f
      title: ApiV1SubmissionsGetParametersApproved
    ApiV1SubmissionsGetParametersActive:
      type: string
      enum:
        - '0'
        - '1'
        - 'true'
        - 'false'
        - 'yes'
        - 'no'
        - t
        - f
      title: ApiV1SubmissionsGetParametersActive
    ApiV1SubmissionsGetParametersTimeout:
      type: string
      enum:
        - '0'
        - '1'
        - 'true'
        - 'false'
        - 'yes'
        - 'no'
        - t
        - f
      title: ApiV1SubmissionsGetParametersTimeout
    ApiV1SubmissionsGetParametersRejected:
      type: string
      enum:
        - '0'
        - '1'
        - 'true'
        - 'false'
        - 'yes'
        - 'no'
        - t
        - f
      title: ApiV1SubmissionsGetParametersRejected
    ApiV1SubmissionsGetParametersScreenedOut:
      type: string
      enum:
        - '0'
        - '1'
        - 'true'
        - 'false'
        - 'yes'
        - 'no'
        - t
        - f
      title: ApiV1SubmissionsGetParametersScreenedOut
    ApiV1SubmissionsGetParametersCompleteoractive:
      type: string
      enum:
        - '0'
        - '1'
        - 'true'
        - 'false'
        - 'yes'
        - 'no'
        - t
        - f
      title: ApiV1SubmissionsGetParametersCompleteoractive
    ApiV1SubmissionsGetParametersOrdering:
      type: string
      enum:
        - started_at
        - '-started_at'
        - submission_reward
        - '-submission_reward'
        - study_name
        - '-study_name'
      title: ApiV1SubmissionsGetParametersOrdering
    SubmissionDetailStatus:
      type: string
      enum:
        - ACTIVE
        - APPROVED
        - PARTIALLY APPROVED
        - AWAITING REVIEW
        - REJECTED
        - RESERVED
        - RETURNED
        - TIMED-OUT
        - SCREENED OUT
        - UNKNOWN
      description: The current status of the submission
      title: SubmissionDetailStatus
    SubmissionDetail:
      type: object
      properties:
        id:
          type: string
          description: The id of the submission
        completed_at:
          type:
            - string
            - 'null'
          description: The time the submission was completed at.
        entered_code:
          type:
            - string
            - 'null'
          description: The completion code used by the participant to complete the study.
        participant:
          type: string
          description: Participant id.
        started_at:
          type: string
          description: The date and time that the user started the submission (UTC)
        status:
          $ref: '#/components/schemas/SubmissionDetailStatus'
          description: The current status of the submission
        study_id:
          type: string
          description: Study id.
        parent_study_id:
          type:
            - string
            - 'null'
          description: ID of the study's parent, if any. (This applies to representative sample and quota studies.)
        bonus_payments:
          type: array
          items:
            type: number
            format: double
          description: Bonus payments that have been paid on the submission. Returned in pence / cents.
        return_requested:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time when a return request for the submission was made.
      required:
        - id
        - started_at
        - status
        - study_id
      title: SubmissionDetail
    SubmissionTransitionAction:
      type: string
      enum:
        - APPROVE
        - COMPLETE
        - REJECT
        - RETURN
        - START
        - SCREEN_OUT
        - UNREJECT
        - UNRETURN
      description: The action that should be performed on the submission.
      title: SubmissionTransitionAction
    SubmissionTransitionRejectionCategory:
      type: string
      enum:
        - TOO_QUICKLY
        - TOO_SLOWLY
        - FAILED_INSTRUCTIONS
        - INCOMP_LONGITUDINAL
        - FAILED_CHECK
        - LOW_EFFORT
        - MALINGERING
        - NO_CODE
        - BAD_CODE
        - NO_DATA
        - UNSUPP_DEVICE
        - OTHER
      description: |-
        Required if action is 'REJECT', it sums as the category of
        the rejection.
      title: SubmissionTransitionRejectionCategory
    SubmissionTransitionCompletionCodeData:
      type: object
      properties:
        percentage_of_reward:
          type: number
          format: double
          description: Required if the code is for a DYNAMIC_PAYMENT action. Must be between 8 - 99 (inclusive).
        message_to_participant:
          type: string
          description: Optional message to the participant to be sent alongside a dynamic payment.
      description: Required if the action is 'COMPLETE' and the code has the action "DYNAMIC_PAYMENT" associated with it.
      title: SubmissionTransitionCompletionCodeData
    SubmissionTransition:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/SubmissionTransitionAction'
          description: The action that should be performed on the submission.
        message:
          type: string
          description: |-
            Required if action is 'REJECT'. Message sent to the participant
            explaining the reason for the rejection.
            It must be at least 100 chars long.
        rejection_category:
          $ref: '#/components/schemas/SubmissionTransitionRejectionCategory'
          description: |-
            Required if action is 'REJECT', it sums as the category of
            the rejection.
        completion_code:
          type: string
          description: >-
            Required if the action is 'COMPLETE'. The completion code must match a value provided when creating the
            study, and the actor must have been set to `researcher`. Any actions that were provided during the set up of
            the completion code (e.g. automatically approve) will then be carried out.
        completion_code_data:
          $ref: '#/components/schemas/SubmissionTransitionCompletionCodeData'
          description: Required if the action is 'COMPLETE' and the code has the action "DYNAMIC_PAYMENT" associated with it.
      required:
        - action
      title: SubmissionTransition
    SubmissionStatus:
      type: string
      enum:
        - ACTIVE
        - APPROVED
        - AWAITING REVIEW
        - REJECTED
        - RESERVED
        - RETURNED
        - TIMED-OUT
        - SCREENED OUT
        - UNKNOWN
      description: The current status of the submission
      title: SubmissionStatus
    Submission:
      type: object
      properties:
        id:
          type: string
          description: The id of the submission
        completed_at:
          type:
            - string
            - 'null'
          description: The time the submission was completed at.
        entered_code:
          type:
            - string
            - 'null'
          description: The completion code used by the participant to complete the study.
        participant:
          type: string
          description: Participant id.
        started_at:
          type: string
          description: The date and time that the user started the submission (UTC)
        status:
          $ref: '#/components/schemas/SubmissionStatus'
          description: The current status of the submission
        study_id:
          type: string
          description: Study id.
      required:
        - id
        - started_at
        - status
        - study_id
      title: Submission
    ReturnRequestedResponseStatus:
      type: string
      enum:
        - ACTIVE
        - APPROVED
        - AWAITING REVIEW
        - SCREENED OUT
        - REJECTED
        - RESERVED
        - RETURNED
        - TIMED-OUT
        - UNKNOWN
      description: The current status of the submission
      title: ReturnRequestedResponseStatus
    ReturnRequestedResponse:
      type: object
      properties:
        id:
          type: string
          description: the database id of the submission instance
        status:
          $ref: '#/components/schemas/ReturnRequestedResponseStatus'
          description: The current status of the submission
        participant:
          type: string
          description: The participant who took part in the study.
        return_requested:
          type:
            - string
            - 'null'
          format: date-time
          description: The date and time when a return request for the submission was made.
      title: ReturnRequestedResponse
    SubmissionsBulkApproveSubmissionsRequest0:
      type: object
      properties:
        study_id:
          type: string
        participant_ids:
          type: array
          items:
            type: string
      required:
        - study_id
        - participant_ids
      title: SubmissionsBulkApproveSubmissionsRequest0
    SubmissionsBulkApproveSubmissionsRequest1:
      type: object
      properties:
        submission_ids:
          type: array
          items:
            type: string
      required:
        - submission_ids
      title: SubmissionsBulkApproveSubmissionsRequest1
    Submissions_BulkApproveSubmissions_Request:
      oneOf:
        - $ref: '#/components/schemas/SubmissionsBulkApproveSubmissionsRequest0'
        - $ref: '#/components/schemas/SubmissionsBulkApproveSubmissionsRequest1'
      title: Submissions_BulkApproveSubmissions_Request
    ApiV1SubmissionsSignalsUploadUrlFilenameGetResponsesContentApplicationJsonSchemaHttpMethod:
      type: string
      enum:
        - PUT
      description: The HTTP method to use when uploading to `upload_url`.
      title: ApiV1SubmissionsSignalsUploadUrlFilenameGetResponsesContentApplicationJsonSchemaHttpMethod
    Submission Feedback Upload_GetSubmissionFeedbackUploadUrl_Response_201:
      type: object
      properties:
        upload_url:
          type: string
          description: The temporary, pre-signed URL to upload your file to with an HTTP `PUT` request.
        http_method:
          $ref: >-
            #/components/schemas/ApiV1SubmissionsSignalsUploadUrlFilenameGetResponsesContentApplicationJsonSchemaHttpMethod
          description: The HTTP method to use when uploading to `upload_url`.
        expires_at:
          type: string
          format: date-time
          description: The time at which the pre-signed `upload_url` expires.
      title: Submission Feedback Upload_GetSubmissionFeedbackUploadUrl_Response_201
    BulkBonus:
      type: object
      properties:
        id:
          type: string
          description: Bonus ID. It is the ID to be used when paying the bonus
        study:
          type: string
          description: Study ID
        amount:
          type: number
          format: double
          description: The amount the participant will receive in cents
        fees:
          type: number
          format: double
          description: The fees Prolific will charge for this bonus in cents
        vat:
          type: number
          format: double
          description: The VAT cost for this bonus in cents
        total_amount:
          type: number
          format: double
          description: Total amount that will be deducted from your balance in cents
      required:
        - id
        - total_amount
      title: BulkBonus
    MessageDataCategory:
      type: string
      enum:
        - payment-timing
        - payment-issues
        - technical-issues
        - feedback
        - rejections
        - other
      description: Participants can self-categorise their message before sending it.
      title: MessageDataCategory
    MessageData:
      type: object
      properties:
        study_id:
          type: string
          description: >-
            What study the message relates to. In case this is not automatically filled for the participant, they can
            choose which study their message relates to.
        category:
          $ref: '#/components/schemas/MessageDataCategory'
          description: Participants can self-categorise their message before sending it.
      description: Metadata for a message
      title: MessageData
    Message:
      type: object
      properties:
        id:
          type: string
          description: Unique ID of the message
        sender_id:
          type: string
          description: Id of the user who sent the message
        body:
          type: string
          description: Body of the message.
        sent_at:
          type: string
          format: date-time
          description: Date time when message was sent
        type:
          type: string
          description: Will only me message for now
        channel_id:
          type: string
          description: The channel ID, for linking back to a thread in the Prolific app.
        data:
          $ref: '#/components/schemas/MessageData'
          description: Metadata for a message
      required:
        - id
        - sender_id
        - body
        - sent_at
        - channel_id
      title: Message
    Messages:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Message'
      title: Messages
    SendMessage:
      type: object
      properties:
        recipient_id:
          type: string
          description: Recipient user's id
        body:
          type: string
          description: Message Body. Text is sanitised for safe storage and display.
        study_id:
          type: string
          description: This study is the reason for this message
      required:
        - recipient_id
        - body
        - study_id
      title: SendMessage
    SendBulkMessage:
      type: object
      properties:
        ids:
          type: array
          items:
            type: string
          description: A list of participant ID's
        body:
          type: string
          description: Message Body. Text is sanitised for safe storage and display.
        study_id:
          type: string
          description: A study ID
      required:
        - ids
        - body
        - study_id
      title: SendBulkMessage
    MessageParticipantGroup:
      type: object
      properties:
        participant_group_id:
          type: string
          description: A participant group ID
        body:
          type: string
          description: Message Body. Text is sanitised for safe storage and display.
        study_id:
          type: string
          description: A study ID
      required:
        - participant_group_id
        - body
      title: MessageParticipantGroup
    WorkspaceUser:
      type: object
      properties:
        id:
          type: string
          description: Id of user
        name:
          type: string
          description: Name of user
        email:
          type: string
          description: email of user
        roles:
          type: array
          items:
            type: string
          description: User roles in workspace
      required:
        - id
      title: WorkspaceUser
    WorkspaceShort:
      type: object
      properties:
        id:
          type: string
          description: Workspace id. It is created by Prolific.
        title:
          type: string
          description: Name of workspace
        description:
          type: string
          description: What is this workspace used for
        owner:
          type: string
          description: User id of the creator of the workspace. It is created by Prolific.
        users:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceUser'
          description: Data for all users who have access to this workspace
        naivety_distribution_rate:
          type:
            - number
            - 'null'
          format: double
          description: The rate at which the studies within this project are distributed.
      required:
        - id
        - title
      title: WorkspaceShort
    WorkspacesListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceShort'
          description: List of all workspaces for user
      required:
        - results
      title: WorkspacesListResponse
    CreateWorkspace:
      type: object
      properties:
        title:
          type: string
          description: Name of workspace
        naivety_distribution_rate:
          type:
            - number
            - 'null'
          format: double
          description: |-
            Control the balance between speed of your studies and the naivety of the participants.

            If not defined, by default Prolific calculates the best rate for most studies
            taking into account the `filters` and the `total_available_places` needed for this study.

            Use 0 if your priority is speed. When this property is set to 0 all eligible participants will have access
            to your study at the same time, without any prioritization.

            You can also set this at a project and study level.
        currency_code:
          type: string
          description: Currency used for all transactions within the workspace. Must be GBP or USD.
      required:
        - title
      title: CreateWorkspace
    ProjectType:
      type: string
      enum:
        - PRIVATE
        - PUBLIC
      description: Project visibility type.
      title: ProjectType
    PublicProjectStatus:
      type: string
      enum:
        - ENABLED
        - DISABLED
      description: Participant-facing publication status for a public project.
      title: PublicProjectStatus
    PublicDetails:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/PublicProjectStatus'
          description: Status of the public project metadata. Defaults to `ENABLED`.
        title:
          type: string
          description: Participant-facing title for the public project.
        short_description:
          type: string
          description: Short participant-facing summary shown to participants for the public project.
        description:
          type: string
          description: Additional participant-facing information shown to participants for the public project.
      title: PublicDetails
    ProjectShort:
      type: object
      properties:
        id:
          type: string
          description: Project id. It is created by Prolific.
        title:
          type: string
          description: Name of project
        description:
          type: string
          description: What is this project used for
        owner:
          type: string
          description: User id of the creator of the project. It is created by Prolific.
        type:
          $ref: '#/components/schemas/ProjectType'
        public_details:
          oneOf:
            - $ref: '#/components/schemas/PublicDetails'
            - type: 'null'
          description: Public metadata for `PUBLIC` projects. `null` for `PRIVATE` projects.
        users:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceUser'
          description: Data for all users who have access to this project
        naivety_distribution_rate:
          type:
            - number
            - 'null'
          format: double
          description: The rate at which the studies within this project are distributed.
      required:
        - id
        - title
        - type
      title: ProjectShort
    Workspace:
      type: object
      properties:
        id:
          type: string
          description: Workspace id. It is created by Prolific.
        title:
          type: string
          description: Name of workspace
        description:
          type: string
          description: What is this workspace used for
        owner:
          type: string
          description: Workspace id. It is created by Prolific.
        users:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceUser'
          description: Data for a user related to a workspace
        projects:
          type: array
          items:
            $ref: '#/components/schemas/ProjectShort'
          description: Data for a project related to a workspace
        wallet:
          type: string
          description: Wallet tied to workspace
        naivety_distribution_rate:
          type:
            - number
            - 'null'
          format: double
          description: The rate at which the studies within this workspace are distributed.
      required:
        - id
        - title
      title: Workspace
    WorkspaceBalanceBalanceBreakdown:
      type: object
      properties: {}
      description: |-
        A breakdown of the total balance of the workspace into:
        - Funds available to pay to participants
        - Funds pre-paid to Prolific for our services
        - Funds for any VAT applied to our Platform fees
      title: WorkspaceBalanceBalanceBreakdown
    WorkspaceBalanceAvailableBalanceBreakdown:
      type: object
      properties: {}
      description: |-
        A breakdown of the available balance of the workspace into:
        - Funds available to pay to participants
        - Funds pre-paid to Prolific for our services
        - Funds for any VAT applied to our Platform fees
      title: WorkspaceBalanceAvailableBalanceBreakdown
    WorkspaceBalance:
      type: object
      properties:
        currency_code:
          type: string
          description: The currency used for all financial transactions within the workspace.
        total_balance:
          type: integer
          description: |-
            The total balance of the workspace, including funds which have already been assigned to active studies.

            All monetary values are shown in the sub-currency of your workspace currency (e.g. pence, cents).
        balance_breakdown:
          $ref: '#/components/schemas/WorkspaceBalanceBalanceBreakdown'
          description: |-
            A breakdown of the total balance of the workspace into:
            - Funds available to pay to participants
            - Funds pre-paid to Prolific for our services
            - Funds for any VAT applied to our Platform fees
        available_balance:
          type: integer
          description: >-
            The remaining balance of your workspace which is available to spend, after removing funds assigned to
            already active studies, etc.
        available_balance_breakdown:
          $ref: '#/components/schemas/WorkspaceBalanceAvailableBalanceBreakdown'
          description: |-
            A breakdown of the available balance of the workspace into:
            - Funds available to pay to participants
            - Funds pre-paid to Prolific for our services
            - Funds for any VAT applied to our Platform fees
      title: WorkspaceBalance
    ProjectShortListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ProjectShort'
          description: List of all projects for a user
      required:
        - results
      title: ProjectShortListResponse
    LongitudinalConfigFiltersItems:
      oneOf:
        - $ref: '#/components/schemas/SelectFilter'
        - $ref: '#/components/schemas/RangeFilter'
        - $ref: '#/components/schemas/CompositeFilter'
      title: LongitudinalConfigFiltersItems
    LongitudinalConfig:
      type: object
      properties:
        target_completions:
          type: integer
          description: Target number of completions for the final wave.
        retention_rate:
          type: number
          format: double
          description: Expected retention rate between waves.
        filters:
          type: array
          items:
            $ref: '#/components/schemas/LongitudinalConfigFiltersItems'
          description: |-
            Recruitment filters applied to participants entering the first wave.
            Uses the same filter shapes as study creation.
      required:
        - target_completions
        - retention_rate
      title: LongitudinalConfig
    CreateProjectLongitudinal:
      type: object
      properties:
        config:
          $ref: '#/components/schemas/LongitudinalConfig'
      description: |-
        Longitudinal configuration. Only used when `is_longitudinal` is true.
        `waves` may not be set at creation — add studies via
        `POST /api/v1/projects/{project_id}/studies/` after creation.
      title: CreateProjectLongitudinal
    CreateProject:
      type: object
      properties:
        title:
          type: string
          description: Name of project
        description:
          type: string
          description: What is this project used for
        type:
          $ref: '#/components/schemas/ProjectType'
          default: PRIVATE
          description: |-
            Project visibility type.
            Set to `PUBLIC` to enable participant-facing public project metadata.
        public_details:
          oneOf:
            - $ref: '#/components/schemas/PublicDetails'
            - type: 'null'
          description: |-
            Public metadata exposed for `PUBLIC` projects.
            Omit for `PRIVATE` projects.
            When creating a public project, `status` defaults to `ENABLED`.
        naivety_distribution_rate:
          type:
            - number
            - 'null'
          format: double
          description: |-
            Control the balance between speed of your studies and the naivety of the participants.

            If not defined, by default Prolific calculates the best rate for most studies
            taking into account the `filters` and the `total_available_places` needed for this study.

            Use 0 if your priority is speed. When this property is set to 0 all eligible participants will have access
            to your study at the same time, without any prioritization.

            You can also set this at a workspace and study level.
        is_longitudinal:
          type: boolean
          default: false
          description: Whether this is a longitudinal (multi-wave) project.
        longitudinal:
          oneOf:
            - $ref: '#/components/schemas/CreateProjectLongitudinal'
            - type: 'null'
          description: |-
            Longitudinal configuration. Only used when `is_longitudinal` is true.
            `waves` may not be set at creation — add studies via
            `POST /api/v1/projects/{project_id}/studies/` after creation.
      required:
        - title
      title: CreateProject
    ProjectLongitudinalRetention:
      type: object
      properties: {}
      description: Computed retention projections and actuals, keyed by wave study id.
      title: ProjectLongitudinalRetention
    ProjectLongitudinal:
      type: object
      properties:
        config:
          oneOf:
            - $ref: '#/components/schemas/LongitudinalConfig'
            - type: 'null'
        retention:
          $ref: '#/components/schemas/ProjectLongitudinalRetention'
          description: Computed retention projections and actuals, keyed by wave study id.
      description: Only present when `is_longitudinal` is true.
      title: ProjectLongitudinal
    Project:
      type: object
      properties:
        id:
          type: string
          description: Project id. It is created by Prolific.
        title:
          type: string
          description: Name of project
        description:
          type: string
          description: What is this project used for
        owner:
          type: string
          description: User id of the creator of the project. It is created by Prolific.
        type:
          $ref: '#/components/schemas/ProjectType'
        public_details:
          oneOf:
            - $ref: '#/components/schemas/PublicDetails'
            - type: 'null'
          description: Public metadata for `PUBLIC` projects. `null` for `PRIVATE` projects.
        users:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceUser'
          description: Data for all users who have access to this project
        workspace:
          type: string
          description: Id of the workspace this project is in. This is created by Prolific.
        naivety_distribution_rate:
          type:
            - number
            - 'null'
          format: double
          description: The rate at which the studies within this project are distributed.
        is_longitudinal:
          type: boolean
          description: Whether this is a longitudinal (multi-wave) project.
        longitudinal:
          oneOf:
            - $ref: '#/components/schemas/ProjectLongitudinal'
            - type: 'null'
          description: Only present when `is_longitudinal` is true.
      required:
        - id
        - title
        - type
      title: Project
    UpdateProject:
      type: object
      properties:
        title:
          type: string
          description: Name of project
        description:
          type: string
          description: What is this project used for
        owner:
          type: string
          description: User id of the creator of the project.
        position:
          type: integer
          description: Position of the project within a workspace.
        hidden:
          type: boolean
          description: Whether the project is hidden in workspace listings.
        type:
          $ref: '#/components/schemas/ProjectType'
        public_details:
          $ref: '#/components/schemas/PublicDetails'
          description: Public metadata for `PUBLIC` projects. Omit to leave unchanged.
        is_sequential:
          type: boolean
          description: Whether the project is configured as sequential.
      description: Partial update payload for a project. All fields are optional.
      title: UpdateProject
    SurveyAnswerOption:
      type: object
      properties:
        id:
          type: string
          format: uuid
        value:
          type: string
          description: The answer option value that can be selected.
      required:
        - value
      description: Responsible for defining an answer model for a given question
      title: SurveyAnswerOption
    SurveyQuestionType:
      type: string
      enum:
        - single
        - multiple
      description: |-
        Responsible for articulating the question type. At the moment we have:

        - single answer
        - multiple answer

        Args:
            str (_type_): The type of question.
            Enum (_type_): The class to define an enum.
      title: SurveyQuestionType
    SurveyQuestion:
      type: object
      properties:
        answers:
          type: array
          items:
            $ref: '#/components/schemas/SurveyAnswerOption'
          description: An array of answer options for a question.
        id:
          type: string
          format: uuid
        title:
          type: string
          description: The question title.
        type:
          $ref: '#/components/schemas/SurveyQuestionType'
          description: The type of question being asked.
      required:
        - answers
        - title
        - type
      description: Responsible for defining a question within a survey.
      title: SurveyQuestion
    SurveySection:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Auto generated by the system.
        questions:
          type: array
          items:
            $ref: '#/components/schemas/SurveyQuestion'
          description: An array of questions a section within a Survey.
        title:
          type: string
          description: The section title.
      required:
        - questions
        - title
      description: |-
        Responsible for providing a section to the survey.

        This is more of a long term thing, but helps if we add now.
      title: SurveySection
    SurveyOut:
      type: object
      properties:
        _id:
          type: string
          description: Auto generated by the system.
        date_created:
          type: string
          format: date-time
          description: The date/time the survey was created (UTC).
        date_modified:
          type: string
          format: date-time
          description: The date/time the survey was modified (UTC).
        researcher_id:
          type: string
          description: The Prolific researcher ID.
        sections:
          type: array
          items:
            $ref: '#/components/schemas/SurveySection'
          description: 'Optional: An array of sections in the survey, otherwise `questions` will be defined.'
        questions:
          type: array
          items:
            $ref: '#/components/schemas/SurveyQuestion'
          description: 'Optional: An array of questions in the survey, otherwise `sections` will be defined.'
        title:
          type: string
          description: The survey title.
      required:
        - researcher_id
        - title
      description: The model used to create a serialised representation a `Survey`.
      title: SurveyOut
    GetAllSurveysResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SurveyOut'
          description: List of all surveys matching the criteria.
      required:
        - results
      title: GetAllSurveysResponse
    SurveyIn:
      type: object
      properties:
        researcher_id:
          type: string
          description: The Prolific researcher ID.
        sections:
          type: array
          items:
            $ref: '#/components/schemas/SurveySection'
          description: An array of sections in the survey, or use `questions`.
        questions:
          type: array
          items:
            $ref: '#/components/schemas/SurveyQuestion'
          description: An array of questions in the survey, or use `sections`.
        title:
          type: string
          description: The survey title.
      required:
        - researcher_id
        - title
      description: The model used to create a `Survey`.
      title: SurveyIn
    SurveyResponseAnswer:
      type: object
      properties:
        answer_id:
          type: string
          format: uuid
          description: The answer ID.
        value:
          type: string
          description: The answer option value selected.
      required:
        - answer_id
        - value
      description: Responsible for defining a response to a question
      title: SurveyResponseAnswer
    SurveyQuestionResponse:
      type: object
      properties:
        answers:
          type: array
          items:
            $ref: '#/components/schemas/SurveyResponseAnswer'
          description: The answers selected.
        question_id:
          type: string
          format: uuid
          description: The question ID.
        question_title:
          type: string
          description: The title of the survey question.
      required:
        - answers
        - question_id
        - question_title
      description: Responsible for defining an answer to a survey question
      title: SurveyQuestionResponse
    SurveyResponseSection:
      type: object
      properties:
        questions:
          type: array
          items:
            $ref: '#/components/schemas/SurveyQuestionResponse'
          description: The questions for a given section.
        section_id:
          type: string
          format: uuid
          description: The section ID.
      required:
        - questions
        - section_id
      description: |-
        Responsible for linking question/answers to a response for a survey.

        This is more of a long term thing, but helps if we add now.
      title: SurveyResponseSection
    SurveyResponseIn:
      type: object
      properties:
        participant_id:
          type: string
          description: The Prolific participant ID.
        sections:
          type: array
          items:
            $ref: '#/components/schemas/SurveyResponseSection'
          description: An array of sections from the survey, otherwise use `questions`.
        questions:
          type: array
          items:
            $ref: '#/components/schemas/SurveyQuestionResponse'
          description: An array of questions from the survey, otherwise use `sections`.
        submission_id:
          type: string
          description: The Prolific submission ID.
      required:
        - participant_id
        - submission_id
      description: The model used to create a `Response`.
      title: SurveyResponseIn
    SurveyResponseOut:
      type: object
      properties:
        _id:
          type: string
        date_created:
          type: string
          format: date-time
          description: The date/time the response was created (UTC).
        date_modified:
          type: string
          format: date-time
          description: The date/time the response was modified (UTC).
        participant_id:
          type: string
          description: The Prolific participant ID.
        sections:
          type: array
          items:
            $ref: '#/components/schemas/SurveyResponseSection'
          description: An array of sections from the survey, otherwise `questions`.
        questions:
          type: array
          items:
            $ref: '#/components/schemas/SurveyQuestionResponse'
          description: An array of questions from the survey, otherwise `sections`.
        submission_id:
          type: string
          description: The Prolific submission ID.
      required:
        - participant_id
        - submission_id
      description: The model used to create a serialised representation a `Response`.
      title: SurveyResponseOut
    SurveySummaryAnswer:
      type: object
      properties:
        answer_id:
          type: string
          format: uuid
          description: The answer ID.
        answer:
          type: string
          description: The answer selected.
        count:
          type: integer
          default: 0
          description: The count of how many times this answer was used in a response.
      required:
        - answer
      description: Responsible for housing the aggregation for a specific answer.
      title: SurveySummaryAnswer
    SurveySummaryQuestion:
      type: object
      properties:
        question_id:
          type: string
          format: uuid
          description: The question ID.
        question:
          type: string
          description: The title of the question.
        total_answers:
          type: integer
          default: 0
          description: The total number of answered responses for a given question.
        answers:
          type: array
          items:
            $ref: '#/components/schemas/SurveySummaryAnswer'
          description: A list of aggregated answer information.
      required:
        - question
      description: Responsible for housing the questions we want to aggregate for the summary.
      title: SurveySummaryQuestion
    SurveySummary:
      type: object
      properties:
        survey_id:
          type: string
          description: The survey ID.
        questions:
          type: array
          items:
            $ref: '#/components/schemas/SurveySummaryQuestion'
          description: A list of questions for the given survey.
      required:
        - survey_id
      description: Responsible for providing a base for all the aggregated answers for a survey.
      title: SurveySummary
    EventType:
      type: object
      properties:
        event_type:
          type: string
        description:
          type: string
      title: EventType
    EventTypeList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/EventType'
      title: EventTypeList
    SecretDetail:
      type: object
      properties:
        id:
          type: string
          description: The ID of the secret.
        value:
          type: string
          description: The secret value.
        workspace_id:
          type: string
          description: The ID of the workspace that the secret belongs to.
      title: SecretDetail
    SecretList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SecretDetail'
          description: A list of secrets.
      title: SecretList
    CreateSecret:
      type: object
      properties:
        workspace_id:
          type: string
          description: The ID of the workspace you are creating the secret in
      title: CreateSecret
    SubscriptionDetail:
      type: object
      properties:
        id:
          type: string
          description: The ID of the subscription.
        event_type:
          type: string
          description: The name of the event type associated to the subscription.
        target_url:
          type: string
          description: The URL that the subscription will notify when your event type is triggered.
        is_enabled:
          type: boolean
          description: Whether the subscription is enabled or not.
        workspace_id:
          type: string
          description: The ID of the workspace we will create the subscription in.
      required:
        - event_type
        - target_url
        - workspace_id
      title: SubscriptionDetail
    SubscriptionList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionDetail'
          description: List of all subscriptions.
      required:
        - results
      title: SubscriptionList
    SubscriptionConfirmation:
      type: object
      properties:
        secret:
          type: string
          description: The secret that was generated when the subscription was created and returned as the `X-Hook-Secret` header.
      required:
        - secret
      title: SubscriptionConfirmation
    SubscriptionUpdateDetail:
      type: object
      properties:
        event_type:
          type: string
          description: The name of the event type associated to the subscription.
        target_url:
          type: string
          description: The URL that the subscription will notify when your event type is triggered.
        is_enabled:
          type: boolean
          description: Whether the subscription is enabled or not.
      title: SubscriptionUpdateDetail
    SubscriptionEventStatus:
      type: string
      enum:
        - PENDING
        - SUCCEEDED
        - FAILED
      description: The status of the event. Will be `FAILED` if the `target_url` response is not 2xx.
      title: SubscriptionEventStatus
    SubscriptionEventPayload:
      type: object
      properties: {}
      description: The event payload that was sent to the target url.
      title: SubscriptionEventPayload
    SubscriptionEvent:
      type: object
      properties:
        id:
          type: string
          description: The ID of the subscription event.
        datetime_created:
          type: string
          description: The time the event was created.
        datetime_updated:
          type: string
          description: The last time the event was updated.
        event_type:
          type: string
          description: The event type that was triggered.
        resource_id:
          type: string
          description: The Prolific Resource ID that the event is linked to.
        status:
          $ref: '#/components/schemas/SubscriptionEventStatus'
          description: The status of the event. Will be `FAILED` if the `target_url` response is not 2xx.
        target_url:
          type: string
          description: The URL where the event payload is sent.
        payload:
          oneOf:
            - $ref: '#/components/schemas/SubscriptionEventPayload'
            - type: 'null'
          description: The event payload that was sent to the target url.
      title: SubscriptionEvent
    SubscriptionEventList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionEvent'
          description: All the events triggered for the subscription
      required:
        - results
      title: SubscriptionEventList
    CreateInvitationRequestRole:
      type: string
      enum:
        - WORKSPACE_ADMIN
        - WORKSPACE_COLLABORATOR
      description: >
        The role that the invited users will have in the workspace. This can be one of the following:

        - "WORKSPACE_ADMIN": The user will have administrative rights in the workspace. They can manage settings, invite
        users, and oversee all projects.

        - "WORKSPACE_COLLABORATOR": The user will be a regular collaborator in the workspace. They can contribute to
        projects but don't have administrative rights.
      title: CreateInvitationRequestRole
    CreateInvitationRequest:
      type: object
      properties:
        association:
          type: string
          format: objectId
          description: The ID of the workspace to which the users are being invited.
        emails:
          type: array
          items:
            type: string
            format: email
          description: An array of email addresses of the users to invite.
        role:
          $ref: '#/components/schemas/CreateInvitationRequestRole'
          description: >
            The role that the invited users will have in the workspace. This can be one of the following:

            - "WORKSPACE_ADMIN": The user will have administrative rights in the workspace. They can manage settings,
            invite users, and oversee all projects.

            - "WORKSPACE_COLLABORATOR": The user will be a regular collaborator in the workspace. They can contribute to
            projects but don't have administrative rights.
      title: CreateInvitationRequest
    InvitationInvitee:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
          format: objectId
          description: The unique ID of the invitee.
        name:
          type:
            - string
            - 'null'
          description: The name of the invitee.
        email:
          type: string
          format: email
          description: The email address of the invitee.
      title: InvitationInvitee
    InvitationStatus:
      type: string
      enum:
        - INVITED
        - ACCEPTED
      description: The current status of the invitation.
      title: InvitationStatus
    InvitationRole:
      type: string
      enum:
        - WORKSPACE_ADMIN
        - WORKSPACE_COLLABORATOR
      description: Assigned role for the user in this workspace.
      title: InvitationRole
    Invitation:
      type: object
      properties:
        association:
          type: string
          format: objectId
          description: The ID of the workspace to which the invitee was invited.
        invitee:
          $ref: '#/components/schemas/InvitationInvitee'
        invited_by:
          type: string
          format: objectId
          description: The ID of the user who sent the invitation.
        status:
          $ref: '#/components/schemas/InvitationStatus'
          description: The current status of the invitation.
        invite_link:
          type: string
          format: uri
          description: The link that the invitee can use to accept the invitation.
        role:
          $ref: '#/components/schemas/InvitationRole'
          description: Assigned role for the user in this workspace.
      title: Invitation
    CreateInvitationResponse:
      type: object
      properties:
        invitations:
          type: array
          items:
            $ref: '#/components/schemas/Invitation'
      title: CreateInvitationResponse
    ApiV1RewardRecommendationsGetParametersCurrency:
      type: string
      enum:
        - USD
        - GBP
      title: ApiV1RewardRecommendationsGetParametersCurrency
    RewardRecommendationsResponseItemsCurrency:
      type: string
      enum:
        - USD
        - GBP
      description: An ISO 4217 currency code. Note that we only support a selection of currency codes as per the enum values.
      title: RewardRecommendationsResponseItemsCurrency
    RewardRecommendationsResponseItems:
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/RewardRecommendationsResponseItemsCurrency'
          description: An ISO 4217 currency code. Note that we only support a selection of currency codes as per the enum values.
        min_reward_per_hour:
          type: integer
          description: >
            The **minimum** hourly reward rate that we recommend you pay to your study's participants.


            **Note that** this is returned as the hundredth subunit of the given currency i.e:


            * for USD, this will be the value in cents

            * for GBP, this will be the value in pence


            To display this as USD or GBP respectively, you'll need to divide this value by 100 and use an appropriate
            number formatting API e.g:


            JavaScript:


            ```js

            new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(2000/ 100); // "$20.00"

            ```
        recommended_reward_per_hour:
          type: integer
          description: >
            The **good** hourly reward rate that we recommend you pay to your study's participants.


            **Note that** this is returned as the hundredth subunit of the given currency i.e:


            * for USD, this will be the value in cents

            * for GBP, this will be the value in pence


            To display this as USD or GBP respectively, you'll need to divide this value by 100 and use an appropriate
            number formatting API e.g:


            JavaScript:


            ```js

            new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(2000/ 100); // "$20.00"

            ```
      title: RewardRecommendationsResponseItems
    RewardRecommendationsResponse:
      type: array
      items:
        $ref: '#/components/schemas/RewardRecommendationsResponseItems'
      title: RewardRecommendationsResponse
    JwkKty:
      type: string
      enum:
        - RSA
      description: Key type, always "RSA".
      title: JwkKty
    JwkAlg:
      type: string
      enum:
        - RS256
      description: Algorithm used, always "RS256".
      title: JwkAlg
    JwkUse:
      type: string
      enum:
        - sig
      description: The intended use of the public key.
      title: JwkUse
    JwkKeyOpsItems:
      type: string
      enum:
        - verify
      title: JwkKeyOpsItems
    JWK:
      type: object
      properties:
        kty:
          $ref: '#/components/schemas/JwkKty'
          description: Key type, always "RSA".
        kid:
          type: string
          description: Key ID used to match the key to the JWT header.
        alg:
          $ref: '#/components/schemas/JwkAlg'
          description: Algorithm used, always "RS256".
        'n':
          type: string
          description: The modulus of the RSA public key.
        e:
          type: string
          description: The exponent of the RSA public key.
        use:
          $ref: '#/components/schemas/JwkUse'
          description: The intended use of the public key.
        key_ops:
          type: array
          items:
            $ref: '#/components/schemas/JwkKeyOpsItems'
          description: The operations that the key is intended to be used for.
      required:
        - kty
        - kid
        - alg
        - 'n'
        - e
        - use
        - key_ops
      title: JWK
    JWKSResponse:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/JWK'
      title: JWKSResponse
    ApiV1CredentialsGetResponsesContentApplicationJsonSchemaCredentialPoolsItems:
      type: object
      properties:
        credential_pool_id:
          type: string
          description: The unique identifier for the credential pool
        total_credentials:
          type: integer
          description: Total number of credentials in the pool
        available_credentials:
          type: integer
          description: Number of unredeemed credentials available
      title: ApiV1CredentialsGetResponsesContentApplicationJsonSchemaCredentialPoolsItems
    Credentials_ListCredentialPools_Response_200:
      type: object
      properties:
        credential_pools:
          type: array
          items:
            $ref: '#/components/schemas/ApiV1CredentialsGetResponsesContentApplicationJsonSchemaCredentialPoolsItems'
      title: Credentials_ListCredentialPools_Response_200
    Credentials_CreateCredentialPool_Response_201:
      type: object
      properties:
        credential_pool_id:
          type: string
          description: The unique identifier for the created credential pool
      title: Credentials_CreateCredentialPool_Response_201
    Credentials_UpdateCredentialPool_Response_200:
      type: object
      properties:
        credential_pool_id:
          type: string
          description: The unique identifier for the updated credential pool
      title: Credentials_UpdateCredentialPool_Response_200
  securitySchemes:
    token:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        The Prolific API uses API token to authenticate requests. You can create an API token directly from your
        settings.


        Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.


        If your token is leaked, delete it and create a new one directly in the app.


        In your requests add `Authorization` header with the value `Token <your token>`.