---
title: "Apply an upload to a dataset"
method: POST
path: "/dataset/{dataset_id}/mutation"
tags: ["Datasets"]
---

# Apply an upload to a dataset

`POST /dataset/{dataset_id}/mutation`

## Request

- Base URL: `https://api.indexone.io`
- URL: `https://api.indexone.io/dataset/{dataset_id}/mutation`
- Auth: API key in header `x-api-key` and API key in header `Authorization`

Step two of the upload flow. Reads the file you uploaded and folds it into the dataset's current parquet.

- `append` — concatenate the new rows onto the existing data. Columns are unioned, so a schema mismatch produces nulls rather than an error.
- `replace` — discard the existing data and use the upload as the new dataset.
- `delete` — **deletes the entire dataset**: every S3 object under its prefix, the DynamoDB record and the team link. `mutation_data_url` is ignored. `DELETE /dataset/{dataset_id}` does exactly the same thing and says so in its name; prefer it.

`mutation_data_url` is the presigned URL with its query string removed (or any `s3://` or `https://<bucket>.s3.amazonaws.com/<key>` URL). `.csv`, `.tsv` and `.parquet` are recognised by extension.

On success a `dataset_update` trigger is posted so workflows consuming this dataset can react.

## Path parameters

- `dataset_id` string, required

## Request body

- object
  - `mutation` 'append' | 'replace' | 'delete', required
  - `mutation_data_url` string: URL of the uploaded file. Required for `append` and `replace`.

## Response `200`

The updated dataset plus the trigger result. For `delete`, a `deletion` summary instead.

- object
  - `dataset` object
  - `trigger_notification` object
  - `deletion` object: Only for `mutation: delete`.

## Other responses

- `400`: `mutation type not specified`, or `unsupported mutation type: <value>`.
- `401`: Missing or invalid id token.
- `403`: Missing or invalid `x-api-key`.
- `404`: No such dataset.
- `429`: API key usage-plan rate limit exceeded.

---

[API](https://skmtc.dev/indexone/apis/index-one-rest-api.md) · [All operations](https://skmtc.dev/indexone/apis/index-one-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/indexone/apis/index-one-rest-api/revisions/df5a92216a9c?raw)