The Agents API from Braintrust — 2 operation(s) for agents.
0 of 6 operations are conformant: apis.io called them with no credentials and the responses matched this contract; 1 more answered but could not be checked against a schema. Checked 2026-11-12. how this works · status file
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/braintrust:braintrust-agents-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
version: 1.0.0
title: Braintrust Agents API
description: 'API specification for the backend data server. The API is hosted globally at
https://api.braintrust.dev or in your own environment.
You can access the OpenAPI spec for this API at https://github.com/braintrustdata/braintrust-openapi.'
license:
name: Apache 2.0
servers:
- url: https://api.braintrust.dev
security:
- bearerAuth: []
- {}
tags:
- name: Agents
paths:
/v1/agent:
post:
tags:
- Agents
security:
- bearerAuth: []
- {}
operationId: postAgent
description: Create a new agent. If there is an existing agent with the same name as the one specified in the request, will return the existing agent unmodified
summary: Create agent
requestBody:
description: Any desired information about the new agent object
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAgent'
responses:
'200':
description: Returns the new agent object
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'400':
description: The request was unacceptable, often due to missing a required parameter
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'401':
description: No valid API key provided
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'403':
description: The API key doesn’t have permissions to perform the request
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'429':
description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
headers:
Retry-After:
schema:
type: string
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'500':
description: Something went wrong on Braintrust's end. (These are rare.)
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
put:
tags:
- Agents
security:
- bearerAuth: []
- {}
operationId: putAgent
description: Create or replace agent. If there is an existing agent with the same name as the one specified in the request, will replace the existing agent with the provided fields
summary: Create or replace agent
requestBody:
description: Any desired information about the new agent object
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAgent'
responses:
'200':
description: Returns the new agent object
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'400':
description: The request was unacceptable, often due to missing a required parameter
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'401':
description: No valid API key provided
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'403':
description: The API key doesn’t have permissions to perform the request
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'429':
description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
headers:
Retry-After:
schema:
type: string
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'500':
description: Something went wrong on Braintrust's end. (These are rare.)
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
get:
operationId: getAgent
tags:
- Agents
description: List out all agents. The agents are sorted by creation date, with the most recently-created agents coming first
summary: List agents
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/AppLimitParam'
- $ref: '#/components/parameters/StartingAfter'
- $ref: '#/components/parameters/EndingBefore'
- $ref: '#/components/parameters/Ids'
- $ref: '#/components/parameters/AgentName'
- $ref: '#/components/parameters/OrgName'
responses:
'200':
description: Returns a list of agent objects
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/Agent'
description: A list of agent objects
required:
- objects
additionalProperties: false
'400':
description: The request was unacceptable, often due to missing a required parameter
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'401':
description: No valid API key provided
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'403':
description: The API key doesn’t have permissions to perform the request
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'429':
description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
headers:
Retry-After:
schema:
type: string
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'500':
description: Something went wrong on Braintrust's end. (These are rare.)
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
/v1/agent/{agent_id}:
get:
operationId: getAgentId
tags:
- Agents
description: Get a agent object by its id
summary: Get agent
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/AgentIdParam'
responses:
'200':
description: Returns the agent object
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'400':
description: The request was unacceptable, often due to missing a required parameter
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'401':
description: No valid API key provided
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'403':
description: The API key doesn’t have permissions to perform the request
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'429':
description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
headers:
Retry-After:
schema:
type: string
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'500':
description: Something went wrong on Braintrust's end. (These are rare.)
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
patch:
operationId: patchAgentId
tags:
- Agents
description: Partially update a agent object. Specify the fields to update in the payload. Any object-type fields will be deep-merged with existing content. Currently we do not support removing fields or setting them to null.
summary: Partially update agent
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/AgentIdParam'
requestBody:
description: Fields to update
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/PatchAgent'
responses:
'200':
description: Returns the agent object
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'400':
description: The request was unacceptable, often due to missing a required parameter
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'401':
description: No valid API key provided
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'403':
description: The API key doesn’t have permissions to perform the request
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'429':
description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
headers:
Retry-After:
schema:
type: string
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'500':
description: Something went wrong on Braintrust's end. (These are rare.)
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
delete:
operationId: deleteAgentId
tags:
- Agents
description: Delete a agent object by its id
summary: Delete agent
security:
- bearerAuth: []
- {}
parameters:
- $ref: '#/components/parameters/AgentIdParam'
responses:
'200':
description: Returns the deleted agent object
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'400':
description: The request was unacceptable, often due to missing a required parameter
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'401':
description: No valid API key provided
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'403':
description: The API key doesn’t have permissions to perform the request
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'429':
description: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
headers:
Retry-After:
schema:
type: string
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
'500':
description: Something went wrong on Braintrust's end. (These are rare.)
content:
text/plain:
schema:
type: string
application/json:
schema:
nullable: true
components:
schemas:
OrgName:
type: string
description: Filter search results to within a particular organization
PatchAgent:
type: object
properties:
name:
type: string
nullable: true
description: Name of the agent. Within a project, agent names are unique
description:
type: string
nullable: true
description: Textual description of the agent
metadata:
type: object
nullable: true
additionalProperties:
nullable: true
description: User-controlled metadata about the agent
description: An agent is a project-scoped durable object that identifies an AI agent or service emitting spans
StartingAfter:
type: string
format: uuid
description: 'Pagination cursor id.
For example, if the final item in the last page you fetched had an id of `foo`, pass `starting_after=foo` to fetch the next page. Note: you may only pass one of `starting_after` and `ending_before`'
AgentIdParam:
type: string
format: uuid
description: Agent id
CreateAgent:
type: object
properties:
project_id:
type: string
format: uuid
description: Unique identifier for the project that the agent belongs under
name:
type: string
description: Name of the agent. Within a project, agent names are unique
description:
type: string
nullable: true
description: Textual description of the agent
metadata:
type: object
nullable: true
additionalProperties:
nullable: true
description: User-controlled metadata about the agent
required:
- project_id
- name
description: An agent is a project-scoped durable object that identifies an AI agent or service emitting spans
Agent:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier for the agent
project_id:
type: string
format: uuid
description: Unique identifier for the project that the agent belongs under
user_id:
type: string
format: uuid
created:
type: string
nullable: true
format: date-time
description: Date of agent creation
name:
type: string
description: Name of the agent. Within a project, agent names are unique
slug:
type: string
description: Stable, URL-safe identifier for the agent, unique within its project.
kind:
type: string
description: 'Agent classification: ''custom'' for customer-defined agents, ''loop'' for built-in Loop agents.'
description:
type: string
nullable: true
description: Textual description of the agent
metadata:
type: object
nullable: true
additionalProperties:
nullable: true
description: User-controlled metadata about the agent
required:
- id
- project_id
- user_id
- name
- slug
- kind
description: An agent is a project-scoped durable object that identifies an AI agent or service emitting spans
Ids:
anyOf:
- type: string
format: uuid
- type: array
items:
type: string
format: uuid
description: Filter search results to a particular set of object IDs. To specify a list of IDs, include the query param multiple times
AgentName:
type: string
description: Name of the agent to search for
EndingBefore:
type: string
format: uuid
description: 'Pagination cursor id.
For example, if the initial item in the last page you fetched had an id of `foo`, pass `ending_before=foo` to fetch the previous page. Note: you may only pass one of `starting_after` and `ending_before`'
AppLimitParam:
type: integer
nullable: true
minimum: 0
description: Limit the number of objects to return
parameters:
Ids:
schema:
$ref: '#/components/schemas/Ids'
required: false
description: Filter search results to a particular set of object IDs. To specify a list of IDs, include the query param multiple times
name: ids
in: query
AgentName:
schema:
$ref: '#/components/schemas/AgentName'
required: false
description: Name of the agent to search for
name: agent_name
in: query
allowReserved: true
StartingAfter:
schema:
$ref: '#/components/schemas/StartingAfter'
required: false
description: 'Pagination cursor id.
For example, if the final item in the last page you fetched had an id of `foo`, pass `starting_after=foo` to fetch the next page. Note: you may only pass one of `starting_after` and `ending_before`'
name: starting_after
in: query
EndingBefore:
schema:
$ref: '#/components/schemas/EndingBefore'
required: false
description: 'Pagination cursor id.
For example, if the initial item in the last page you fetched had an id of `foo`, pass `ending_before=foo` to fetch the previous page. Note: you may only pass one of `starting_after` and `ending_before`'
name: ending_before
in: query
OrgName:
schema:
$ref: '#/components/schemas/OrgName'
required: false
description: Filter search results to within a particular organization
name: org_name
in: query
allowReserved: true
AppLimitParam:
schema:
$ref: '#/components/schemas/AppLimitParam'
required: false
description: Limit the number of objects to return
name: limit
in: query
AgentIdParam:
schema:
$ref: '#/components/schemas/AgentIdParam'
required: true
description: Agent id
name: agent_id
in: path
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key or JWT
description: 'Most Braintrust endpoints are authenticated by providing your API key as a header `Authorization: Bearer [api_key]` to your HTTP request. You can create an API key in the Braintrust [organization settings page](https://www.braintrustdata.com/app/settings?subroute=api-keys).'