--- title: "Update a Batch" method: PATCH path: "/api/v1/data-collection/batches/{batch_id}" tags: ["aiTaskBuilder"] --- # Update a Batch `PATCH /api/v1/data-collection/batches/{batch_id}` 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. ## Path parameters - `batch_id` string, required ## Headers - `Authorization` string, required ## Request body - object - `name` string - `task_details` ApiV1DataCollectionBatchesBatchIdPatchRequestBodyContentApplicationJsonSchemaTaskDetails - `task_name` string, required - `task_introduction` string, required — HTML formatted task introduction - `task_steps` string, required — HTML formatted task steps - `dataset_id` string, uuid - `batch_items` BatchItemsPage[], nullable — 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. - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing page when updating. - `display_position` 'intro' | 'outro' | 'body' — Renders the page once — before ("intro") or after ("outro") the repeating body — instead of once per datapoint. Omit (or set "body") for the default repeating behaviour. Pages with display_position "intro" or "outro" may only contain rich_text/image content blocks, not instructions or dataset_field refs. - `rows` BatchItemsRow[], required - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing row when updating. - `columns` BatchItemsColumn[], required - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing column when updating. - `items` BatchItemsItem[], required - union — 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`. - object — 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`, `image_url`, `audio_url`, or `video_url` are permitted, and the same field may not be referenced more than once on the same page. - … - object — An image content block rendered inline within the batch layout. - … - object — A rich-text content block rendered inline within the batch layout. - … - object — Free-text input instruction. - … - object — Free-text input instruction paired with a unit selector. - … - object — Multiple-choice instruction. - … - object — Multiple-choice instruction with an additional free-text input per selected option. - … - object — File upload instruction. - … - `auto_sync_enabled` boolean — 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. ## Response `200` Ok - AITaskBuilderBatch - `id` string, uuid, required - `created_at` string, date-time, required — An ISO-8601 formatted string representing the batch creation time, in UTC. - `created_by` string, required — User ID of the Prolific user that created the resource. - `datasets` AiTaskBuilderBatchDatasetsItems[], required - `id` string, uuid, required - `total_datapoint_count` integer, required - `filename` string, required — The filename of the dataset - `name` string, required - `status` 'UNINITIALISED' | 'PROCESSING' | 'READY' | 'ERROR', required - `total_task_count` integer, required - `total_instruction_count` integer, required - `workspace_id` string, required - `schema_version` integer, required - `task_details` AiTaskBuilderBatchTaskDetails, required - `task_name` string, required - `task_introduction` string, required — HTML formatted task introduction - `task_steps` string, required — HTML formatted task steps - `total_task_groups` integer, required - `batch_items` BatchItemsPage[], nullable — 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`. - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing page when updating. - `display_position` 'intro' | 'outro' | 'body' — Renders the page once — before ("intro") or after ("outro") the repeating body — instead of once per datapoint. Omit (or set "body") for the default repeating behaviour. Pages with display_position "intro" or "outro" may only contain rich_text/image content blocks, not instructions or dataset_field refs. - `rows` BatchItemsRow[], required - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing row when updating. - `columns` BatchItemsColumn[], required - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing column when updating. - `items` BatchItemsItem[], required - union — 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`. - object — 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`, `image_url`, `audio_url`, or `video_url` are permitted, and the same field may not be referenced more than once on the same page. - … - object — An image content block rendered inline within the batch layout. - … - object — A rich-text content block rendered inline within the batch layout. - … - object — Free-text input instruction. - … - object — Free-text input instruction paired with a unit selector. - … - object — Multiple-choice instruction. - … - object — Multiple-choice instruction with an additional free-text input per selected option. - … - object — File upload instruction. - … - `auto_sync_enabled` boolean — 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. ## Other responses - `400` — Error - `422` — Unprocessable Entity — `batch_items` failed validation --- [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)