## Quickstart

1. **Get a Braintrust API key**  
   Create a [Braintrust API key](/content/docs/admin/organizations#manage-api-keys/index.html) and set it as an environment variable:
   
   ```bash
   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](/content/docs/admin/ai-providers#add-an-organization-level-provider/index.html) (available across all projects) or the [project level](/content/docs/admin/ai-providers#add-a-project-level-provider/index.html) (overrides organization defaults). See [how project overrides work](/content/docs/admin/ai-providers#how-project-overrides-work/index.html) 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.

```markdown
https://gateway.braintrust.dev
```

### Using the OpenAI SDK

```typescript
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

```typescript
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.

```typescript
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](/content/docs/admin/ai-providers#add-an-organization-level-provider/index.html) on the **AI providers** settings page.
   - **Project-level AI providers** Configure provider API keys at the [project level](/content/docs/admin/ai-providers#add-a-project-level-provider/index.html) 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](/content/docs/deploy/supported-models/index.html) page. If you need a model that is not listed, [let us know](mailto:support@braintrust.dev).

### 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:
- **x-bt-use-cache**: `auto | always | never` - Control caching behavior
- **x-bt-cache-ttl**: Seconds (max 604800) - Set cache TTL
- **x-bt-org-name**: Organization name - Specify organization for multi-org users
- **x-bt-project-id**: Project ID - Use project-level AI provider credentials
- **x-bt-fallback-providers**: Comma-separated provider credential names - Retry eligible provider failures on fallback providers.