---
title: "Update a Dataset Schema"
method: PATCH
path: "/api/v1/data-collection/datasets/{dataset_id}"
tags: ["aiTaskBuilder"]
---

# Update a Dataset Schema

`PATCH /api/v1/data-collection/datasets/{dataset_id}`

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

## Path parameters

- `dataset_id` string, uuid, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `schema` DatasetSchema, required — A researcher-defined schema that specifies the fields in a V4 dataset. Each field has a type that determines how it is rendered to participants and how it can be referenced in `batch_items`. Constraints: - Maximum 200 fields per schema. - Field keys: 1–128 characters. - Field labels: maximum 255 characters.
    - `strict` boolean, required — When `true`, records that are missing any field defined in the schema are rejected during import. When `false`, missing fields are allowed and treated as absent.
    - `fields` object, required — A map of field key to field descriptor. The key is used to reference the field in `batch_items` (`dataset_field` items) and in JSONL records.

## Response `200`

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.

- AITaskBuilderUpdateTaskBuilderDatasetResponse200 — An AI Task Builder dataset. The shape of the response varies by `schema_version`: - **V3 datasets** include `status`, `filename`, and `has_predetermined_grouping_id`. - **V4 datasets** include `schema` (the researcher-defined field schema, or `null` if not yet set) and `imports` (the list of import jobs for this dataset). V4 datasets do not include `status` or `filename`.
  - `id` string, uuid, required
  - `name` string, required
  - `created_at` string, date-time, required
  - `created_by` string, required
  - `workspace_id` string, required
  - `total_datapoint_count` integer, 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`.
  - `filename` string, nullable — Filename of the uploaded data file. **V3 datasets only.**
  - `has_predetermined_grouping_id` boolean, nullable — Whether the dataset contains a `META_TASK_GROUP_ID` column. **V3 datasets only.**
  - `schema` DatasetSchema — A researcher-defined schema that specifies the fields in a V4 dataset. Each field has a type that determines how it is rendered to participants and how it can be referenced in `batch_items`. Constraints: - Maximum 200 fields per schema. - Field keys: 1–128 characters. - Field labels: maximum 255 characters.
    - `strict` boolean, required — When `true`, records that are missing any field defined in the schema are rejected during import. When `false`, missing fields are allowed and treated as absent.
    - `fields` object, required — A map of field key to field descriptor. The key is used to reference the field in `batch_items` (`dataset_field` items) and in JSONL records.
  - `imports` DatasetImportJob[], nullable — Import jobs for this dataset, most recent first. **V4 datasets only.** `null` for V3 datasets.
    - `dataset_id` string, uuid, required — The dataset this import job belongs to.
    - `import_id` string, uuid, required — The unique identifier of the import job.
    - `type` 'file_upload', required — The type of import. Currently always `file_upload`.
    - `filename` string, nullable — The original filename supplied when the upload URL was requested.
    - `created_at` string, date-time, required — When the import job was created (ISO 8601, UTC).
    - `updated_at` string, date-time, required — When the import job was last updated (ISO 8601, UTC).
    - `status` 'uninitialised' | 'queued' | 'processing' | 'complete' | 'partial' | 'failed' | 'pending_schema', required — Current status of the import job.
    - `accepted_count` integer — Number of records successfully ingested. Present when status is `complete` or `partial`.
    - `rejected_count` integer — Number of records rejected. Present when status is `partial`.
    - `errors` ImportJobError[] — Record-level validation errors. Present when status is `partial`.
      - `record_index` integer, nullable — Zero-based index of the rejected record in the uploaded file.
      - `field` string, nullable — The schema field key that caused the rejection, or `null` if no specific field is implicated. The special value `_raw` indicates a whole-record parse failure (e.g. malformed JSON) rather than a field-level error.
      - `reason` string, nullable — Human-readable description of why the record was rejected.
    - `reason` string — Human-readable reason for failure. Present when status is `failed`.
  - `migration_job_id` string, 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}`.

## Other responses

- `400` — Bad request — not a V4 dataset, or an attempt to change the `task_group_id` column on a dataset that already has datapoints.
- `403` — Forbidden — the user does not have access to the dataset's workspace.
- `404` — Dataset not found

---

[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)