openapi: 3.1.0
info:
title: API Reference aiTaskBuilder API
version: 1.0.0
servers:
- url: https://api.prolific.com
description: Production
tags:
- name: aiTaskBuilder
paths:
/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 i
# --- truncated at 32 KB (181 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/prolific/refs/heads/main/openapi/prolific-aitaskbuilder-api-openapi.yml