canonical: https://jentic.com/apis/braintrust.dev/braintrust

# Braintrust API

The Braintrust API runs evaluations and logging for AI applications. It manages projects, experiments, and datasets, and inserts, fetches, and attaches feedback to the events those hold, so an agent can record model runs and their scores. It logs production events through project logs and reads them back for analysis. It also manages prompts, functions, roles, groups, and access-control entries, and summarizes an experiment's results. Requests carry a bearer token; a subset of endpoints are open, and the rest act within the scope the token grants.

## For AI agents

Run and log AI evaluations on Braintrust: manage projects, experiments, and datasets, insert events and feedback, read production logs, and summarize experiment results.

## Scope

Does not handle model inference, billing, or user authentication. Use for Braintrust project, experiment, dataset, and logging operations only.

## Capabilities

- Manage projects, experiments, and datasets
- Insert events into experiments and datasets and fetch them back
- Attach feedback and scores to logged events
- Log production events through project logs and read them back
- Summarize an experiment's results
- Manage prompts, functions, roles, and access-control entries

## Use cases

### AI agent evaluation logging

An agent pipeline needs to record its own runs and scores so a team can track quality over time. Through Jentic the agent creates or looks up a project, inserts experiment events with their inputs, outputs, and scores, and can summarize the experiment when the run finishes. This turns ad hoc runs into a comparable evaluation history without a person wiring the client.

Example prompt: Search Jentic for 'log an experiment event', call POST `/v1/experiment` to create the experiment, then POST `/v1/experiment/{experiment_id}/insert` to record each scored event.

### Production log capture

A deployed AI feature needs to send its live events somewhere they can be reviewed and scored later. The project-logs operations insert production events and fetch them back, so an agent can stream real traffic into Braintrust and a reviewer can pull it for analysis. This keeps production behaviour observable rather than lost.

Example prompt: Call POST `/v1/project_logs/{project_id}/insert` to log each production event, then GET `/v1/project_logs/{project_id}/fetch` to pull recent events for review.

### Feedback collection

A human-in-the-loop workflow needs to attach reviewer judgements to recorded runs. The feedback operations tie a score or comment to a specific logged event in an experiment or project log, so an agent can fold reviewer input back into the evaluation record and later measure against it.

Example prompt: Call POST `/v1/experiment/{experiment_id}/feedback` with the event id and score to record the reviewer's judgement against that run.

### Dataset curation

A test-set workflow needs to build and grow the datasets that experiments run against. The dataset operations insert records, fetch them back, and summarize a dataset, so an agent can add newly labelled examples and keep the evaluation set current instead of editing files by hand.

Example prompt: Call POST `/v1/dataset` to create the dataset, then POST `/v1/dataset/{dataset_id}/insert` to add each labelled example.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/project` | Create a project |
| POST | `/v1/experiment` | Create an experiment |
| POST | `/v1/experiment/{experiment_id}/insert` | Insert events into an experiment |
| GET | `/v1/experiment/{experiment_id}/summarize` | Summarize an experiment's results |
| POST | `/v1/project_logs/{project_id}/insert` | Log production events |
| GET | `/v1/project_logs/{project_id}/fetch` | Fetch logged production events |
| POST | `/v1/experiment/{experiment_id}/feedback` | Attach feedback to an event |
| POST | `/v1/dataset/{dataset_id}/insert` | Insert records into a dataset |

## Why Jentic

- **Setup:** Wiring the Braintrust API by hand means creating a bearer token, holding it in your logging code, and building the insert and fetch calls before the first run is recorded. Through Jentic you install once, store the token, and import it from the API Directory, and your agent calls it without you writing the client.
- **Permission scoping:** The Braintrust API exposes logging, read, and administrative operations, so a rule bounds which of them the agent may call: inserting and reading experiment events without the role, group, or access-control operations unless you add them. You choose the allowed set, so the agent only runs the operations you pick.
- **Credential handling:** You store the bearer token once and Jentic keeps it server-side, so it never sits in the agent's prompt or context; the agent calls the Braintrust operations and the token is attached out of band.
- **Discovery method:** Agents search Jentic by intent such as 'log an experiment event' or 'summarize an experiment', and Jentic returns the matching Braintrust operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **Langfuse** — Langfuse traces and evaluates LLM applications as an alternative observability platform
- **OpenAI** — The OpenAI API produces the model outputs that a Braintrust experiment records and scores
- **Sentry** — Sentry captures application errors alongside the model-quality signals Braintrust records

## FAQ

### Is there a Braintrust API MCP server?

You don't need an MCP server to give your agent the Braintrust API. Jentic connects it directly from the API Directory: import it, store your bearer token once, and your agent calls the experiment, dataset, and logging operations on demand without loading another server's tool definitions into its context.

### What authentication does the Braintrust API use?

The Braintrust API authenticates with a bearer token, which most endpoints need, and the token determines which projects and organizations the caller can reach. When you connect it through Jentic, the token is stored server-side, so it stays out of the agent's prompt while the agent still makes the calls.

### Can I log evaluation runs with the Braintrust API?

Yes. POST `/v1/experiment/{experiment_id}/insert` records scored events against an experiment and GET `/v1/experiment/{experiment_id}/summarize` returns its aggregate results, so an agent can log a run and read back how it scored.

### What are the rate limits for the Braintrust API?

The OpenAPI spec does not state rate limits for the Braintrust API. Because event logging is often bursty, batch inserts where the endpoint accepts a list and check Braintrust's own documentation for any account-level limits, which the spec does not carry.

### How do I record production events through Jentic?

Search Jentic for 'log a production event', load the matching operation, and call POST `/v1/project_logs/{project_id}/insert` with the event payload. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Braintrust API?

Yes. Because Jentic One is self-hosted, you decide which operations the agent may call: you might allow logging and reading experiment events with POST `/v1/experiment/{experiment_id}/insert` while withholding role and access-control changes, and the calls the agent makes are logged.