Use the Braintrust gateway - Braintrust

Quickstart

  1. Get a Braintrust API key
    Create a Braintrust API key and set it as an environment variable:

    export BRAINTRUST_API_KEY="<your-braintrust-api-key>"

  2. Add your AI provider key
    Add your provider API key in Braintrust so the gateway can call it on your behalf — you won’t need to set your provider key locally.You can do this at the organization level (available across all projects) or the project level (overrides organization defaults). See how project overrides work for the rules that decide which provider a request uses.

  3. Point your SDK at the gateway
    Change your SDK’s base URL to https://gateway.braintrust.dev and pass your Braintrust API key as the API key. That’s it — no other code changes needed.

https://gateway.braintrust.dev

Using the OpenAI SDK

import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.braintrust.dev",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

async function main() {
  const response = await client.responses.create({
    model: "gpt-5-mini",
    input: [
      { role: "user", content: "Say hello!" },
    ],
  });

console.log(response.output_text);
}

main();

Using the Anthropic SDK

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://gateway.braintrust.dev",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

async function main() {
  const response = await client.messages.create({
    model: "claude-haiku-4-5",
    messages: [{ role: "user", content: "Say hello!" }],
  });
  console.log(response.content[0].type === "text" ? response.content[0].text : "");
}

main();

Generating Embeddings

The gateway supports generating embeddings through the OpenAI-compatible /embeddings endpoint.

import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.braintrust.dev",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const response = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: "What is machine learning?",
});
console.log(response.data[0].embedding);

Configure API Keys

Configure two things for gateway requests: a Braintrust auth token to call the gateway, and AI provider keys that the gateway uses to run model requests.

  1. Create a Braintrust auth token
    Set BRAINTRUST_API_KEY to a Braintrust auth token and pass it in Authorization: Bearer ... when calling the gateway.

  2. Add AI provider keys

    • Organization-level AI providers Add provider API keys at the organization level on the AI providers settings page.
    • Project-level AI providers Configure provider API keys at the project level when a project needs separate billing, usage isolation, or different credentials.

Supported Providers

The gateway supports a large and fast-moving set of models across OpenAI-compatible, Anthropic, Google, and AWS Bedrock APIs. Browse the full list on the supported models page. If you need a model that is not listed, let us know.

Enable Provider Failover

Use provider failover when more than one configured AI provider can serve the same model and you want the gateway to retry the request on another provider after a provider-side failure. To enable failover for a request, set x-bt-fallback-providers to a comma-separated list of AI provider credential names.

Advanced Configuration

Configure gateway behavior with these request headers: