PRprolific
aiTaskBuilder

Update a Dataset Schema

Changed on

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.
patch/api/v1/data-collection/datasets/{dataset_id}

Request

  • Base URL
    https://api.prolific.com
  • URL
    https://api.prolific.com/api/v1/data-collection/datasets/{dataset_id}
  • Auth
    API key in header Authorization

Path parameters

dataset_idstring uuid required

The unique identifier of the V4 dataset to update

Request body

Response

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.

idstring uuid required
namestring required
created_atstring date-time required
created_bystring required
workspace_idstring required
total_datapoint_countinteger required
schema_version'3' | '4' required

Internal dataset version. 3 = legacy CSV/ZIP; 4 = structured schema with JSONL/CSV import tracking.

status'ERROR' | 'PROCESSING' | 'READY' | 'UNINITIALISED'

Processing status. V3 datasets only. V4 datasets track status per import job via imports.

filenamestring nullable

Filename of the uploaded data file. V3 datasets only.

has_predetermined_grouping_idboolean nullable

Whether the dataset contains a META_TASK_GROUP_ID column. V3 datasets only.

migration_job_idstring uuid

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}.

Changes

  • d0e32ae96e4eRevision changes
    • info

      added the new optional request property ///

    • info

      added the optional property //// to the response with the status

  • 6c9aa73fa51fRevision changes
    • warning

      deleted the header request parameter Authorization

    • info

      the endpoint scheme security token was added to the API