How to Create/Update Dataset Schemas with the API

Last updated: January 26, 2026

Prerequisites

Plans: Any

Deployments: Any

Use case: Datasets with schemas

Steps

Step 1: Navigate to the Dataset you wish to add or update the schema of.

Step 2: Click the ellipses next to the Dataset name and then select "Copy dataset ID" from the dropdown.

Step 3: Use one of the following methods to call the API:

Javascript

const options = {
  method: "PATCH",
  headers: {
    Authorization: "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    metadata: {
      __schemas: {
        input: {
          type: "object",
          properties: {
            postal: { type: "number" },
          },
          additionalProperties: false,
          enforce: true
        },
      },
    },
  }),
};

fetch(
  "https://api.braintrust.dev/v1/dataset/<dataset-id>",
  options,
)
  .then((res) => res.json())
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

Python

import requests
import json

headers = {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
}

data = {
    "metadata": {
        "__schemas": {
            "input": {
                "type": "object",
                "properties": {
                    "postal": {"type": "number"},
                },
                "additionalProperties": False,
                "enforce": True
            },
        },
    },
}

try:
    response = requests.patch(
        "https://api.braintrust.dev/v1/dataset/<dataset-id>",
        headers=headers,
        json=data
    )
    response.raise_for_status()
    print(response.json())
except requests.exceptions.RequestException as err:
    print(f"Error: {err}")

CURL

  curl -X PATCH "https://api.braintrust.dev/v1/dataset/<dataset-id>" \
    -H "Authorization: Bearer <your-api-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "metadata": {
        "__schemas": {
          "input": {
            "type": "object",
            "properties": {
              "postal": {
                "type": "number"
              }
            },
            "additionalProperties": false,
            "enforce": true
          }
        }
      }
    }'

Example Schema Body:

{
  "__schemas": {
    // input schema
    "input": {
      // input type
      "type": "object",
      // whether this schema should be enforced when adding new data
      "enforce": true,
      // the object properties since it is of type object
      "properties": {
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string"
        },
        "postal": {
          "type": "number"
        },
        "street": {
          "type": "string"
        }
      },
      // whether to allow extending the properties listed above
      "additionalProperties": false
    },
    // expected schema
    "expected": {
      "type": "string",
      "description": "The expected property is a string."
    },
    // metadata schema
    "metadata": {
      "type": "object",
      // the object properties since it is of type object
      "properties": {
        "isTestData": {
          "type": "boolean"
        },
        "estimatedCost": {
          "type": "number"
        }
      },
      // whether to allow extending the properties listed above
      "additionalProperties": false
    },
  }
}