---
title: "Create Batch Instructions"
method: POST
path: "/api/v1/data-collection/batches/{batch_id}/instructions"
tags: ["aiTaskBuilder"]
---

# Create Batch Instructions

`POST /api/v1/data-collection/batches/{batch_id}/instructions`

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>

## Path parameters

- `batch_id` string, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `instructions` ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItems[], required — The instructions to create for the AI Task Builder batch.
    - `type` 'multiple_choice' | 'free_text' | 'free_text_with_unit' | 'multiple_choice_with_free_text' | 'file_upload', required — The type of instruction.
    - `description` string, required — The question or prompt displayed to participants.
    - `helper_text` string — Additional guidance text displayed below the question.
    - `placeholder_text_input` string — Placeholder text displayed in the input field.
    - `answer_limit` integer — 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` boolean — 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` ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems[] — The options (required for multiple_choice and multiple_choice_with_free_text).
      - `label` string, required — The display label for the option.
      - `value` string, required — The value associated with the option.
      - `heading` string — The heading for the option (required for multiple_choice_with_free_text).
    - `unit_options` ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsUnitOptionsItems[] — The unit options (required for free_text_with_unit). List of available units that participants can select from.
      - `label` string, required — The display label for the unit.
      - `value` union, required — The value associated with the unit.
        - string
        - number, double
        - boolean
      - `validation` ValidationRule — Optional validation constraints for input values
        - `type` 'number' | 'string', required — 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` number, double, nullable — 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` number, double, nullable — 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.
    - `default_unit` string — For free_text_with_unit. Default selected unit (must match a value from unit_options).
    - `unit_position` 'prefix' | 'suffix' — 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` ValidationRule — Optional validation constraints for input values
      - `type` 'number' | 'string', required — 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` number, double, nullable — 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` number, double, nullable — 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.

## Response `201`

Created. Returned only for legacy batches (`batch_items` is `null`).

- AITaskBuilderInstruction[]
  - union
    - object — multiple_choice variant
      - `type` 'multiple_choice', required
      - `id` string, uuid, required
      - `created_at` string, date-time, required
      - `parent_id` string, uuid, required — ID of the parent batch or collection
      - `parent_type` 'batch' | 'collection', required
      - `created_by` string, required
      - `description` string, required — The question or prompt displayed to participants
      - `helper_text` string — Additional guidance text displayed below the question
      - `placeholder_text_input` string — Placeholder text displayed in the input field
      - `answer_limit` integer, required — 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` boolean — 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` AiTaskBuilderMultipleChoiceInstructionOptionsItems[], required
        - `label` string, required — Display text shown to participants
        - `value` union, required — Value returned in responses
          - string
          - number, double
          - boolean
        - `exclusive` boolean — When true, selecting this option deselects all other options. Useful for "None of the above" style options.
    - object — free_text variant
      - `type` 'free_text', required
      - `id` string, uuid, required
      - `created_at` string, date-time, required
      - `parent_id` string, uuid, required — ID of the parent batch or collection
      - `parent_type` 'batch' | 'collection', required
      - `created_by` string, required
      - `description` string, required — The question or prompt displayed to participants
      - `helper_text` string — Additional guidance text displayed below the question
      - `placeholder_text_input` string — Placeholder text displayed in the input field
      - `validation` ValidationRule — Optional validation constraints for input values
        - `type` 'number' | 'string', required — 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` number, double, nullable — 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` number, double, nullable — 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.
    - object — free_text_with_unit variant
      - `type` 'free_text_with_unit', required
      - `id` string, uuid, required
      - `created_at` string, date-time, required
      - `parent_id` string, uuid, required — ID of the parent batch or collection
      - `parent_type` 'batch' | 'collection', required
      - `created_by` string, required
      - `description` string, required — The question or prompt displayed to participants
      - `helper_text` string — Additional guidance text displayed below the question
      - `placeholder_text_input` string — Placeholder text displayed in the input field
      - `unit_options` AiTaskBuilderFreeTextWithUnitInstructionUnitOptionsItems[], required — List of available units that participants can select from
        - `label` string, required — Display text shown to participants
        - `value` union, required — Value returned in responses
          - string
          - number, double
          - boolean
        - `validation` ValidationRule — Optional validation constraints for input values
          - `type` 'number' | 'string', required — 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` number, double, nullable — 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` number, double, nullable — 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.
      - `default_unit` string — Default selected unit (must match a value from unit_options)
      - `unit_position` 'prefix' | 'suffix', required — 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).
    - object — multiple_choice_with_free_text variant
      - `type` 'multiple_choice_with_free_text', required
      - `id` string, uuid, required
      - `created_at` string, date-time, required
      - `parent_id` string, uuid, required — ID of the parent batch or collection
      - `parent_type` 'batch' | 'collection', required
      - `created_by` string, required
      - `description` string, required — The question or prompt displayed to participants
      - `helper_text` string — Additional guidance text displayed below the question
      - `placeholder_text_input` string — Placeholder text displayed in the input field
      - `answer_limit` integer, required — 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` boolean — 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` AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItems[], required
        - `label` string, required — Display text shown to participants
        - `value` union, required — Value returned in responses
          - string
          - number, double
          - boolean
        - `heading` string, required — Section heading that groups this option
        - `exclusive` boolean — When true, selecting this option deselects all other options. Useful for "None of the above" style options.
    - object — file_upload variant
      - `type` 'file_upload', required
      - `id` string, uuid, required
      - `created_at` string, date-time, required
      - `parent_id` string, uuid, required — ID of the parent batch or collection
      - `parent_type` 'batch' | 'collection', required
      - `created_by` string, required
      - `description` string, required — The prompt describing what to upload
      - `helper_text` string — Additional guidance text displayed below the question
      - `placeholder_text_input` string — Placeholder text displayed in the input field
      - `accepted_file_types` string[] — 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` number, double — Maximum file size in megabytes per file. Must be a positive number. Defaults to 25.
      - `min_file_count` integer — Minimum number of files required. Must be at least 1. Defaults to 1.
      - `max_file_count` integer — Maximum number of files allowed. Must be at least 1 and greater than or equal to min_file_count. Defaults to 10.

## Other responses

- `400` — Error
- `422` — Returned when the target batch uses `batch_items`. Instructions must be managed via the `batch_items` payload instead of this endpoint.

---

[API](https://skmtc.net/prolific/apis/api-reference.md) · [All operations](https://skmtc.net/prolific/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prolific/api-reference/versions/dc6f073a9827/schema)