---
title: "Create or replace span iframe"
method: PUT
path: "/v1/span_iframe"
tags: ["SpanIframes"]
---

# Create or replace span iframe

`PUT /v1/span_iframe`

## Request

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

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

## Request body

- CreateSpanIFrame
  - `project_id` string, uuid, required: Unique identifier for the project that the span iframe belongs under
  - `name` string, required: Name of the span iframe
  - `description` string, nullable: Textual description of the span iframe
  - `url` string, required: URL to embed the project viewer in an iframe
  - `post_message` boolean, nullable: Whether to post messages to the iframe containing the span's data. This is useful when you want to render more data than fits in the URL.

## Response `200`

Returns the new span iframe object

- SpanIFrame
  - `id` string, uuid, required: Unique identifier for the span iframe
  - `project_id` string, uuid, required: Unique identifier for the project that the span iframe belongs under
  - `user_id` string, uuid, nullable: Identifies the user who created the span iframe
  - `created` string, date-time, nullable: Date of span iframe creation
  - `deleted_at` string, date-time, nullable: Date of span iframe deletion, or null if the span iframe is still active
  - `name` string, required: Name of the span iframe
  - `description` string, nullable: Textual description of the span iframe
  - `url` string, required: URL to embed the project viewer in an iframe
  - `post_message` boolean, nullable: Whether to post messages to the iframe containing the span's data. This is useful when you want to render more data than fits in the URL.

## 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`: 2 breaking
  - the request property `description` became not nullable
  - the request property `post_message` became not nullable
- **2026-09-03** `ebac33c1422e`: 1 breaking
  - request body became required
- **2025-06-17** `77a2d5797d94`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/braintrustdata/apis/braintrust-api/changes/v1/span_iframe/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)