HTTP API Reference

Backups API reference

Reference documentation for the Backups API.

The Backups API lets you enable or disable backups for a dataset, list its backups, and fetch a backup's files for download. Backups are off by default, and you can enable them only if your project's plan includes the backups feature.

Want to get started?

Backups

Sanity's dataset backups for disaster recovery and auditing. Backups need a plan that includes them, are off by default, and are enabled per dataset with the Sanity CLI.

Authentication

All requests must be authenticated. To enable or disable backups, the user or token needs the update grant on sanity.project.datasets. To list backups or fetch a backup, it needs the update grant on sanity.project, so a token without that grant receives a 401 response.

Base API server URL

Sanity API base URL

https://api.sanity.io/{apiVersion}/projects/{projectId}

Variables

  • projectIdstringdefault: "projectId"

    Project ID

  • apiVersionstringdefault: "v2025-02-19"

    API version

Endpoints

Enable or disable backups

put/datasets/{datasetName}/settings/backups

Path parameters

Request body application/json

  • enabledbooleanrequired

    Enable or disable backups

Examplesapplication/json
{
  "enabled": true
}

Responses

204

Successfully updated backup settings

List backups

get/datasets/{datasetName}/backups

Path parameters

Query parameters

  • limitintegerdefault: 10

    Max number of backups returned. The response contains the most recent backups, ordered oldest first.

  • afterstring (date)

    Only return backups created on or after this date (YYYY-MM-DD). Matched against the date in the backup ID.

  • beforestring (date)

    Only return backups created before this date (YYYY-MM-DD). Backups from this date are excluded. Matched against the date in the backup ID.

Responses

200

List of backups

  • backupsarrayrequired

    The most recent backups, up to limit, ordered oldest first.

    Show child attributes
    items
    • idstringrequired

      The backup ID, in the format YYYY-MM-DD-<uuid>. The date is the day the backup was created.

    • createdAtstring (date-time)required

      When the backup was created

  • limitintegerrequired

    The limit used for the request. This is the default of 10 if you didn't pass one.

Examplesapplication/json
{
  "backups": [
    {
      "id": "2024-02-02-19083f95-1741-4e29-997a-76b56c773e24",
      "createdAt": "2024-02-02T14:13:06Z"
    }
  ],
  "limit": 20
}

Get a backup

get/datasets/{datasetName}/backups/{backupId}

This endpoint is primarily designed for use through the Sanity CLI sanity backups download command, which handles paging, downloading all files, and constructing a tarball in the format expected by sanity datasets import.

Path parameters

Query parameters

  • nextCursorstring

    The nextCursor value from the previous page's response. Omit it to fetch the first page.

  • limitintegerdefault: 1000

    Max number of files returned per page

Responses

200

Backup details

  • createdAtstring (date-time)required
  • totalFilesintegerrequired

    Total number of files in the backup, across all pages.

  • filesarrayrequired
    Show child attributes
    items
    • namestring
    • urlstring

      Signed download URL. It expires 24 hours after the request.

    • typestring
  • nextCursorstringrequired

    Cursor for the next page of files. Pass it as the nextCursor query parameter. An empty string means there are no more pages.

Examplesapplication/json
{
  "createdAt": "2023-12-12T06:03:01Z",
  "totalFiles": 1021,
  "files": [
    {
      "name": "document1",
      "url": "https://storage.googleapis.com/example-bucket/document1?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=example%40example-project.iam.gserviceaccount.com%2F20181026%2Fus-central1%2Fstorage%2Fgoog4_request&X-Goog-Date=20181026T181309Z&X-Goog-Expires=86400&X-Goog-SignedHeaders=host&X-Goog-Signature=247a2aa45f169edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa8496def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dcc1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c20580e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b133447032ea7abedc098d2eb14a7",
      "type": "document"
    }
  ],
  "nextCursor": "MTAwMA=="
}