Configure project-level resources - project scores, tags, automations, saved views, and span iframes - that shape how data is scored and displayed.
openapi: 3.0.3
info:
title: Braintrust REST API
description: >-
The Braintrust REST API for building, evaluating, and observing AI
applications. The API is organized around REST, uses predictable
resource-oriented URLs under https://api.braintrust.dev/v1, accepts and
returns JSON, and authenticates with a Bearer API key. This specification
covers the core documented resource surface - projects, experiments,
datasets, logs/spans, prompts, functions and scorers, evals, project
configuration, organization/ACL management, credentials, and the
OpenAI-compatible AI proxy.
termsOfService: https://www.braintrust.dev/legal/terms-of-service
contact:
name: Braintrust Support
email: support@braintrust.dev
url: https://www.braintrust.dev/docs
version: '1.0'
servers:
- url: https://api.braintrust.dev
description: US data plane (default)
- url: https://api-eu.braintrust.dev
description: EU data plane
security:
- bearerAuth: []
tags:
- name: Projects
- name: Experiments
- name: Datasets
- name: Logs
- name: Prompts
- name: Functions
- name: Evals
- name: Project Configuration
- name: Organization
- name: ACL
- name: Credentials
- name: AI Proxy
paths:
/v1/project:
get:
operationId: getProject
tags:
- Projects
summary: List projects
description: List out all projects, optionally filtered and paginated.
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/StartingAfter'
- $ref: '#/components/parameters/EndingBefore'
- name: org_name
in: query
schema:
type: string
description: Filter projects to a single organization by name.
- name: project_name
in: query
schema:
type: string
description: Filter to a project with the given name.
responses:
'200':
description: Returns a list of projects.
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/Project'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: postProject
tags:
- Projects
summary: Create project
description: >-
Create a new project. If there is an existing project with the same
name in the organization, will return the existing project unmodified.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProject'
responses:
'200':
description: Returns the new project object.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/project/{project_id}:
parameters:
- $ref: '#/components/parameters/ProjectId'
get:
operationId: getProjectId
tags:
- Projects
summary: Get project
description: Get a project by its unique identifier.
responses:
'200':
description: Returns the project object.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: patchProjectId
tags:
- Projects
summary: Partially update project
description: >-
Partially update a project object. Specify the fields to update in the
payload. Unspecified fields are left unchanged.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchProject'
responses:
'200':
description: Returns the updated project object.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteProjectId
tags:
- Projects
summary: Delete project
description: Delete a project by its unique identifier.
responses:
'200':
description: Returns the deleted project object.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/experiment:
get:
operationId: getExperiment
tags:
- Experiments
summary: List experiments
description: List out all experiments, optionally filtered and paginated.
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/StartingAfter'
- $ref: '#/components/parameters/EndingBefore'
- name: project_id
in: query
schema:
type: string
format: uuid
description: Filter experiments to a project.
- name: experiment_name
in: query
schema:
type: string
description: Filter to an experiment with the given name.
responses:
'200':
description: Returns a list of experiments.
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/Experiment'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: postExperiment
tags:
- Experiments
summary: Create experiment
description: >-
Create a new experiment. If there is an existing experiment with the
same name as the one specified in the request, will return the existing
experiment unmodified.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateExperiment'
responses:
'200':
description: Returns the new experiment object.
content:
application/json:
schema:
$ref: '#/components/schemas/Experiment'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/experiment/{experiment_id}:
parameters:
- $ref: '#/components/parameters/ExperimentId'
get:
operationId: getExperimentId
tags:
- Experiments
summary: Get experiment
responses:
'200':
description: Returns the experiment object.
content:
application/json:
schema:
$ref: '#/components/schemas/Experiment'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: patchExperimentId
tags:
- Experiments
summary: Partially update experiment
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description:
type: string
metadata:
type: object
additionalProperties: true
responses:
'200':
description: Returns the updated experiment object.
content:
application/json:
schema:
$ref: '#/components/schemas/Experiment'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteExperimentId
tags:
- Experiments
summary: Delete experiment
responses:
'200':
description: Returns the deleted experiment object.
content:
application/json:
schema:
$ref: '#/components/schemas/Experiment'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/experiment/{experiment_id}/insert:
parameters:
- $ref: '#/components/parameters/ExperimentId'
post:
operationId: postExperimentIdInsert
tags:
- Experiments
summary: Insert experiment events
description: >-
Insert a set of events into the experiment. Events are upserted by id;
equivalent to the SDK's logging interface.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- events
properties:
events:
type: array
description: A list of experiment events to insert.
items:
$ref: '#/components/schemas/InsertEvent'
responses:
'200':
description: Returns the row ids of the inserted events.
content:
application/json:
schema:
$ref: '#/components/schemas/InsertEventsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/experiment/{experiment_id}/fetch:
parameters:
- $ref: '#/components/parameters/ExperimentId'
post:
operationId: postExperimentIdFetch
tags:
- Experiments
summary: Fetch experiment (POST form)
description: >-
Fetch the events in an experiment. Use the POST form to express complex
filters, limits, and cursors in the request body.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FetchEventsRequest'
responses:
'200':
description: Returns the fetched events.
content:
application/json:
schema:
$ref: '#/components/schemas/FetchEventsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: getExperimentIdFetch
tags:
- Experiments
summary: Fetch experiment (GET form)
parameters:
- $ref: '#/components/parameters/Limit'
- name: max_xact_id
in: query
schema:
type: string
- name: max_root_span_id
in: query
schema:
type: string
responses:
'200':
description: Returns the fetched events.
content:
application/json:
schema:
$ref: '#/components/schemas/FetchEventsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/experiment/{experiment_id}/feedback:
parameters:
- $ref: '#/components/parameters/ExperimentId'
post:
operationId: postExperimentIdFeedback
tags:
- Experiments
summary: Feedback for experiment events
description: Log feedback for a set of experiment events.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- feedback
properties:
feedback:
type: array
items:
$ref: '#/components/schemas/FeedbackItem'
responses:
'200':
$ref: '#/components/responses/Empty'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/experiment/{experiment_id}/summarize:
parameters:
- $ref: '#/components/parameters/ExperimentId'
get:
operationId: getExperimentIdSummarize
tags:
- Experiments
summary: Summarize experiment
description: Summarize the scores and metrics of an experiment.
parameters:
- name: summarize_scores
in: query
schema:
type: boolean
- name: comparison_experiment_id
in: query
schema:
type: string
format: uuid
responses:
'200':
description: Returns the experiment summary.
content:
application/json:
schema:
$ref: '#/components/schemas/SummarizeExperimentResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/eval:
post:
operationId: evalLaunch
tags:
- Evals
summary: Launch an eval
description: >-
Launch an evaluation. This is the API-equivalent of the Eval function
in the SDK; it runs a task function over a dataset and applies scorers.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EvalLaunchRequest'
responses:
'200':
description: Returns a summary of the launched eval.
content:
application/json:
schema:
$ref: '#/components/schemas/SummarizeExperimentResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/dataset:
get:
operationId: getDataset
tags:
- Datasets
summary: List datasets
parameters:
- $ref: '#/components/parameters/Limit'
- name: project_id
in: query
schema:
type: string
format: uuid
- name: dataset_name
in: query
schema:
type: string
responses:
'200':
description: Returns a list of datasets.
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/Dataset'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: postDataset
tags:
- Datasets
summary: Create dataset
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDataset'
responses:
'200':
description: Returns the new dataset object.
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/dataset/{dataset_id}:
parameters:
- $ref: '#/components/parameters/DatasetId'
get:
operationId: getDatasetId
tags:
- Datasets
summary: Get dataset
responses:
'200':
description: Returns the dataset object.
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: patchDatasetId
tags:
- Datasets
summary: Partially update dataset
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description:
type: string
metadata:
type: object
additionalProperties: true
responses:
'200':
description: Returns the updated dataset object.
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteDatasetId
tags:
- Datasets
summary: Delete dataset
responses:
'200':
description: Returns the deleted dataset object.
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/dataset/{dataset_id}/insert:
parameters:
- $ref: '#/components/parameters/DatasetId'
post:
operationId: postDatasetIdInsert
tags:
- Datasets
summary: Insert dataset events
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- events
properties:
events:
type: array
items:
$ref: '#/components/schemas/InsertEvent'
responses:
'200':
description: Returns the row ids of the inserted events.
content:
application/json:
schema:
$ref: '#/components/schemas/InsertEventsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/dataset/{dataset_id}/fetch:
parameters:
- $ref: '#/components/parameters/DatasetId'
post:
operationId: postDatasetIdFetch
tags:
- Datasets
summary: Fetch dataset (POST form)
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FetchEventsRequest'
responses:
'200':
description: Returns the fetched events.
content:
application/json:
schema:
$ref: '#/components/schemas/FetchEventsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: getDatasetIdFetch
tags:
- Datasets
summary: Fetch dataset (GET form)
parameters:
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Returns the fetched events.
content:
application/json:
schema:
$ref: '#/components/schemas/FetchEventsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/dataset/{dataset_id}/feedback:
parameters:
- $ref: '#/components/parameters/DatasetId'
post:
operationId: postDatasetIdFeedback
tags:
- Datasets
summary: Feedback for dataset events
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- feedback
properties:
feedback:
type: array
items:
$ref: '#/components/schemas/FeedbackItem'
responses:
'200':
$ref: '#/components/responses/Empty'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/dataset/{dataset_id}/summarize:
parameters:
- $ref: '#/components/parameters/DatasetId'
get:
operationId: getDatasetIdSummarize
tags:
- Datasets
summary: Summarize dataset
parameters:
- name: summarize_data
in: query
schema:
type: boolean
responses:
'200':
description: Returns the dataset summary.
content:
application/json:
schema:
type: object
properties:
project_name:
type: string
dataset_name:
type: string
data_summary:
type: object
nullable: true
properties:
total_records:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
/v1/project_logs/{project_id}/insert:
parameters:
- $ref: '#/components/parameters/ProjectId'
post:
operationId: postProjectLogsIdInsert
tags:
- Logs
summary: Insert project logs events
description: Insert a set of trace span / log events into a project's logs.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- events
properties:
events:
type: array
items:
$ref: '#/components/schemas/InsertEvent'
responses:
'200':
description: Returns the row ids of the inserted events.
content:
application/json:
schema:
$ref: '#/components/schemas/InsertEventsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/project_logs/{project_id}/fetch:
parameters:
- $ref: '#/components/parameters/ProjectId'
post:
operationId: postProjectLogsIdFetch
tags:
- Logs
summary: Fetch project logs (POST form)
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FetchEventsRequest'
responses:
'200':
description: Returns the fetched log events.
content:
application/json:
schema:
$ref: '#/components/schemas/FetchEventsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: getProjectLogsIdFetch
tags:
- Logs
summary: Fetch project logs (GET form)
parameters:
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Returns the fetched log events.
content:
application/json:
schema:
$ref: '#/components/schemas/FetchEventsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/project_logs/{project_id}/feedback:
parameters:
- $ref: '#/components/parameters/ProjectId'
post:
operationId: postProjectLogsIdFeedback
tags:
- Logs
summary: Feedback for project logs events
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- feedback
properties:
feedback:
type: array
items:
$ref: '#/components/schemas/FeedbackItem'
responses:
'200':
$ref: '#/components/responses/Empty'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/prompt:
get:
operationId: getPrompt
tags:
- Prompts
summary: List prompts
parameters:
- $ref: '#/components/parameters/Limit'
- name: project_id
in: query
schema:
type: string
format: uuid
- name: prompt_name
in: query
schema:
type: string
- name: slug
in: query
schema:
type: string
responses:
'200':
description: Returns a list of prompts.
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/Prompt'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: postPrompt
tags:
- Prompts
summary: Create prompt
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePrompt'
responses:
'200':
description: Returns the new prompt object.
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'401':
$ref: '#/components/responses/Unauthorized'
put:
operationId: putPrompt
tags:
- Prompts
summary: Create or replace prompt
description: >-
Create or replace a prompt. If a prompt with the same slug already
exists in the project, it will be replaced.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePrompt'
responses:
'200':
description: Returns the prompt object.
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/prompt/{prompt_id}:
parameters:
- name: prompt_id
in: path
required: true
schema:
type: string
format: uuid
get:
operationId: getPromptId
tags:
- Prompts
summary: Get prompt
responses:
'200':
description: Returns the prompt object.
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: patchPromptId
tags:
- Prompts
summary: Partially update prompt
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description:
type: string
prompt_data:
$ref: '#/components/schemas/PromptData'
tags:
type: array
items:
type: string
responses:
'200':
description: Returns the updated prompt object.
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deletePromptId
tags:
- Prompts
summary: Delete prompt
responses:
'200':
description: Returns the deleted prompt object.
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/function:
get:
operationId: getFunction
tags:
- Functions
summary: List functions
parameters:
- $ref: '#/components/parameters/Limit'
- name: project_id
in: query
schema:
type: string
format: uuid
- name: function_name
in: query
schema:
type: string
- name: slug
in: query
schema:
type: string
responses:
'200':
description: Returns a list of functions.
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/Function'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: postFunction
tags:
- Functions
summary: Create function
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFunction'
responses:
'200':
description: Returns the new function object.
content:
application/json:
schema:
$ref: '#/components/schemas/Function'
'401':
$ref: '#/components/responses/Unauthorized'
put:
operationId: putFunction
tags:
- Functions
summary: Create or replace function
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFunction'
responses:
'200':
description: Returns the function object.
content:
application/json:
schema:
$ref: '#/components/schemas/Function'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/function/{function_id}:
parameters:
- name: function_id
in: path
required: true
schema:
type: string
format: uuid
get:
operationId: getFunctionId
tags:
- Functions
summary: Get function
responses:
'200':
description: Returns the function object.
content:
application/json:
schema:
$ref: '#/components/schemas/Function'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: patchFunctionId
tags:
- Functions
summary: Partially update function
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description:
type: string
function_data:
type: object
additionalProperties: true
responses:
'200':
description: Returns the updated function object.
content:
application/json:
schema:
$ref: '#/components/schemas/Function'
'401':
$ref: '#/components/responses/Unauthorized'
delete:
operationId: deleteFunctionId
tags:
- Functions
summary: Delete function
responses:
'200':
description: Returns the deleted function object.
content:
application/json:
schema:
$ref: '#/components/schemas/Function'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/function/{function_id}/invoke:
parameters:
- name: function_id
in: path
required: true
schema:
type: string
format: uuid
post:
operationId: postFunctionIdInvoke
tags:
- Functions
summary: Invoke function
description: >-
Invoke a function (a prompt, code, or LLM scorer) server-side with the
given input. Optionally stream the result and write a trace span to a
parent object.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InvokeFunctionRequest'
responses:
'200':
description: Returns the function result, or an SSE stream when stream is true.
content:
application/json:
schema:
description: The return value of the function. Shape depends on the function.
text/event-stream:
schema:
type: string
description: Server-Sent Events stream of the function result when stream is true.
'401':
$ref: '#/components/responses/Unauthorized'
/v1/project_score:
get:
operationId: getProjectScore
tags:
- Project Configuration
summary: List project scores
parameters:
- $ref: '#/components/parameters/Limit'
- name: project_id
in: query
schema:
type: string
format: uuid
responses:
'200':
description: Returns a list of project scores.
content:
application/json:
schema:
# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/braintrust-data/refs/heads/main/openapi/braintrust-data-openapi.yml