--- title: "Update a Collection" method: PUT path: "/api/v1/data-collection/collections/{collection_id}" tags: ["aiTaskBuilder"] --- # Update a Collection `PUT /api/v1/data-collection/collections/{collection_id}` 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. ## Path parameters - `collection_id` string, required ## Headers - `Authorization` string, required ## Request body - CollectionUpdateRequest - `name` string, required — The name of the collection - `task_details` TaskDetails, required — Task metadata displayed to participants - `task_name` string, required — The title displayed to participants - `task_introduction` string, required — HTML formatted introduction shown at the start of the task - `task_steps` string, required — HTML formatted step-by-step instructions - `collection_items` CollectionItemInput[], required — Pages within the collection. Include `id` to preserve existing items. - `id` string, uuid — Include to preserve an existing page when updating - `page_items` PageItemInput[], required — Instructions and content blocks on this page - union — An instruction or content block input. Include `id` to preserve an existing item when updating. - CollectionInstructionInput — Instruction input for a collection page - `id` string, uuid — Include to preserve an existing instruction when updating - `type` 'multiple_choice' | 'free_text' | 'free_text_with_unit' | 'multiple_choice_with_free_text' | 'file_upload', required - `description` string, required — The question or prompt displayed to participants - `order` integer, required — Position of this instruction relative to others - `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. Use 1 for single-select, -1 for unlimited. - `disable_dropdown` boolean — When true, always renders checkbox/radio elements instead of a dropdown select. - `options` CollectionInstructionInputOptionsItems[] - `label` string, required - `value` union, required - … - `heading` string — Required for multiple_choice_with_free_text - `exclusive` boolean — When true, selecting this option deselects all other options. Useful for "None of the above" style options. - `unit_options` CollectionInstructionInputUnitOptionsItems[] — Required for free_text_with_unit. List of available units that participants can select from. - `label` string, required - `value` union, required - … - `validation` ValidationRule — Optional validation constraints for input values - … - `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. - `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. - ContentBlockInput — Content block input for a collection page - `id` string, uuid — Include to preserve an existing content block when updating - `type` 'image' | 'rich_text', required - `url` string, uri — HTTPS URL for image content blocks - `alt_text` string — Alt text for image content blocks (required for accessibility) - `caption` string — Optional caption for image content blocks - `content` string — Content for rich_text content blocks. Interpreted as HTML by default, or Markdown if content_format is set to "markdown". - `content_format` 'html' | 'markdown' — Format of the content field. When set to "markdown", content is converted to HTML server-side before storage. Defaults to "html". ## Response `200` OK - Collection - `id` string, uuid, required - `schema_version` '1', required - `created_at` string, date-time, required — ISO-8601 formatted creation timestamp in UTC - `created_by` string, required — User ID of the Prolific user that created the collection - `workspace_id` string, required — The ID of the Prolific workspace - `name` string, required — The name of the collection - `task_details` TaskDetails, required — Task metadata displayed to participants - `task_name` string, required — The title displayed to participants - `task_introduction` string, required — HTML formatted introduction shown at the start of the task - `task_steps` string, required — HTML formatted step-by-step instructions - `collection_items` CollectionItem[], required — Pages within the collection. Each collection item represents a page. - `id` string, uuid, required - `created_at` string, date-time, required - `created_by` string, required - `schema_version` '1', required - `page_items` PageItem[], required — Instructions and content blocks on this page - union — An instruction or content block within a page - 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 - `order` integer, required - `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 - `disable_dropdown` boolean - `options` CollectionMultipleChoiceInstructionOptionsItems[], required - `label` string, required - `value` union, required - … - `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 - `order` integer, required - `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 - `order` integer, required - `helper_text` string — Additional guidance text displayed below the question - `placeholder_text_input` string — Placeholder text displayed in the input field - `unit_options` CollectionFreeTextWithUnitInstructionUnitOptionsItems[], 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 - … - `validation` ValidationRule — Optional validation constraints for input values - … - `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 - `order` integer, required - `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 - `disable_dropdown` boolean - `options` CollectionMultipleChoiceWithFreeTextInstructionOptionsItems[], required - `label` string, required - `value` union, required - … - `heading` string, required - `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 - `order` integer, required - `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. - object — image variant - `type` 'image', required - `id` string, uuid, required - `created_at` string, date-time, required - `parent_id` string, uuid, required — ID of the parent collection item (page) - `parent_type` 'collection' | 'batch', required - `created_by` string, required - `schema_version` '1', required - `url` string, uri, required — HTTPS URL of the image - `alt_text` string, required — Alt text for accessibility - `caption` string — Optional caption displayed below the image - object — rich_text variant - `type` 'rich_text', required - `id` string, uuid, required - `created_at` string, date-time, required - `parent_id` string, uuid, required — ID of the parent collection item (page) - `parent_type` 'collection' | 'batch', required - `created_by` string, required - `schema_version` '1', required - `content` string, required — HTML content. If the original input used Markdown, it has been converted to HTML. - `last_modified_at` string, date-time — ISO-8601 formatted last modification timestamp in UTC - `last_modified_by` string — User ID of the Prolific user that last modified the collection ## Other responses - `400` — Error --- [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)