---
title: "update dataset"
method: PATCH
path: "/datasets/{id}"
tags: ["Dataset CRUD"]
---

# update dataset

`PATCH /datasets/{id}`

## Request

- Base URL: `https://api.riveterhq.com/v1`
- URL: `https://api.riveterhq.com/v1/datasets/{id}`
- Auth: HTTP bearer

Edit a dataset's structure: `name`, `index_column`, `input_columns` (add, rename, delete), `output` columns (add, change the prompt or schema, pin or unpin a tool, rename, delete), and the per-row `budget` / `budget_locked` of its enrichment. Nothing runs; fill with [POST /enrich](#tag/enrich/post/enrich). Changing a column's prompt, schema, or pinned tool marks its filled cells `stale`. A saved or shared enrichment is copied before the edit, so `enrichment_id` may change. Refused with 409 `dataset_in_use` while a run is on the dataset.

The budget follows the columns as on [PATCH /enrichments/{id}](#tag/enrich/patch/enrichments/{id}): adding an output column raises `budget_credits_per_row` by 1.5, removing one lowers it by 1.5, until `budget_locked` is true. `budget_locked: true` or `budget` sent in the same request as column changes wins over that adjustment, so one call can lock the budget and add columns. Both need an output column to land on: on a dataset without one, send them with the first `output` add.

## Path parameters

- `id` string, required

## Request body

- object
  - `name` string
  - `index_column` string: The input column rows are unique on (by name). Every row is re-keyed.
  - `input_columns` InputColumnOperations: Input column edits keyed by column name. `{}` adds the column; `rename` renames it; `delete: true` removes it (not the index column). Rows are untouched: an added column reads empty, a removed column's values are dropped from reads.
  - `output` OutputColumnOperations: Output column edits keyed by column name. A name not on the enrichment adds a column; `prompt` / `output_schema` / `tool` change one (its filled cells read `stale`); `rename` renames it (cells kept); `delete: true` removes it.
  - `budget` number: Credits the row agent may spend per row, on the dataset's enrichment. Sent with column changes, it wins over the per-column adjustment.
  - `budget_locked` boolean: true keeps the budget as set when output columns are added or removed; false lets it move by 1.5 per column again.

## Response `200`

The dataset after the edit

- Dataset
  - `id` string: ds_...
  - `name` string, nullable
  - `input_columns` string[]: Input column names, in order (row identity)
  - `index_column` string, nullable: The input column rows are unique on
  - `enrichment_id` string, nullable: The bound enrichment (its output columns are the dataset's)
  - `output_columns` string[]: Output column names, in order (from the bound enrichment; [] without one). Prompts and schemas are on GET /enrichments/{enrichment_id}
  - `row_count` integer
  - `rows_expired` boolean: True once the rows were removed by retention; the structure stays
  - `import_in_progress` boolean: A CSV import accepted with 202 has not landed yet
  - `runs` DatasetRunSummary[]: The five newest runs on the dataset
    - `id` string: run_...
    - `type` 'dataset_build' | 'enrichment': dataset_build = list generation; enrichment = a fill
    - `status` string
    - `created_at` string, date-time
    - `finished_at` string, date-time, nullable
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `400`: The request is malformed or names a conflicting parameter combination
- `401`: Missing or invalid API key (`request_status` body — see the AuthError schema)
- `403`: The API key's account may not access this resource or endpoint (`forbidden`), or the account has not migrated to Datasets yet (`feature_not_enabled` — open Datasets in the app and click "Migrate to Datasets")
- `404`: No resource with that id on this account
- `409`: Duplicate run_key or a run already in progress
- `422`: The request is valid but can't be executed (e.g. insufficient_credits, credit_cap_exceeded when max_credits is set, validation failure)

## Changes

- **2026-11-13** `fac56b649559`: 2 info
  - api tag `Dataset CRUD` added
  - api tag `Datasets` removed
- **2026-10-30** `dcb4d45ade1a`: 10 info
  - added the optional property `error/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/typical` to the response with the `400` status
  - added the optional property `error/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/typical` to the response with the `403` status
  - added the optional property `error/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/typical` to the response with the `404` status
  - added the optional property `error/credit_detail/estimate/oneOf[#/components/schemas/CreditEstimate]/typical` to the response with the `409` status
  - …6 more
- **2026-10-19** `76aabcc5686b`: 2 info
  - api tag `Datasets` added
  - api tag `Datasets (beta)` removed
- **2026-10-16** `7ebb804e781e`: 1 breaking, 2 warning
  - the `output/additionalProperties/tool` request property type changed from `object` to `string`
  - removed the request property `output/additionalProperties/tool/name`
  - removed the request property `output/additionalProperties/tool/params`
- **2026-10-16** `5af893c5bc21`: 1 info
  - added the new optional request property `output/additionalProperties/tool`

[Operation history](https://skmtc.dev/riveterhq/apis/riveter-api/changes/datasets/:id/patch.md)

---

[API](https://skmtc.dev/riveterhq/apis/riveter-api.md) - [All operations](https://skmtc.dev/riveterhq/apis/riveter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/riveterhq/apis/riveter-api/revisions/fac56b649559?raw)