---
title: "Create or replace dataset snapshot"
method: PUT
path: "/v1/dataset_snapshot"
tags: ["DatasetSnapshots"]
---

# Create or replace dataset snapshot

`PUT /v1/dataset_snapshot`

## Request

- Base URL: `https://api.braintrust.dev`
- URL: `https://api.braintrust.dev/v1/dataset_snapshot`
- Auth: one of:
  - HTTP bearer
  - none

Create or replace dataset snapshot. If there is an existing dataset snapshot with the same name as the one specified in the request, will replace the existing dataset snapshot with the provided fields

## Request body

- CreateDatasetSnapshot
  - `dataset_id` string, uuid, required: Unique identifier for the dataset that this snapshot belongs to
  - `name` string, required: Name of the dataset snapshot
  - `description` string, nullable: Textual description of the dataset snapshot
  - `xact_id` string, required: Transaction id of the brainstore version at the time of the snapshot

## Response `200`

Returns the new dataset snapshot object

- DatasetSnapshot
  - `id` string, uuid, required: Unique identifier for the dataset snapshot
  - `dataset_id` string, uuid, required: Unique identifier for the dataset that this snapshot belongs to
  - `name` string, required: Name of the dataset snapshot
  - `description` string, nullable, required
  - `xact_id` string, required: Transaction id of the brainstore version at the time of the snapshot
  - `created` string, date-time, nullable, required: Date of dataset snapshot creation

## Other responses

- `400`: The request was unacceptable, often due to missing a required parameter
- `401`: No valid API key provided
- `403`: The API key doesn’t have permissions to perform the request
- `429`: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
- `500`: Something went wrong on Braintrust's end. (These are rare.)

## Changes

- **2026-10-30** `8f5039399f77`: 1 breaking
  - the request property `description` became not nullable
- **2026-09-03** `ebac33c1422e`: 1 breaking
  - request body became required
- **2026-04-08** `a21b724fece9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/braintrustdata/apis/braintrust-api/changes/v1/dataset_snapshot/put.md)

---

[API](https://skmtc.dev/braintrustdata/apis/braintrust-api.md) - [All operations](https://skmtc.dev/braintrustdata/apis/braintrust-api/llms.txt) - [OpenAPI document](https://skmtc.dev/braintrustdata/apis/braintrust-api/revisions/19184ec94018?raw)