Integration Guide

Braintrust proxy + Meridian

Route your AI requests through a secure server-side proxy to keep your Braintrust API keys hidden from the client. Full observability with Braintrust logging, zero key exposure.

Get startedBraintrust docs ↗

Step 1 — Environment variables

Add your Braintrust credentials to .env.local. Never expose these on the client.

BRAINTRUST_API_KEY=sk-...
BRAINTRUST_PROJECT_ID=...
BRAINTRUST_BASE_URL=https://api.braintrust.dev/v1/proxy

Step 2 — API proxy route

Create a server-side route handler at app/api/braintrust-proxy/route.ts. This forwards requests to Braintrust with your secret key.

// POST /api/braintrust-proxy
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const body = await req.json();
  const apiKey = process.env.BRAINTRUST_API_KEY;
  const projectId = process.env.BRAINTRUST_PROJECT_ID;
  const baseUrl = process.env.BRAINTRUST_BASE_URL;

  if (!apiKey || !projectId || !baseUrl) {
    return NextResponse.json(
      { error: 'Missing Braintrust configuration' },
      { status: 500 }
    );
  }

  const targetUrl = `${baseUrl}/${projectId}/chat/completions`;

  const response = await fetch(targetUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${apiKey}`,
    },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    const errorText = await response.text();
    return NextResponse.json(
      { error: 'Braintrust proxy error', detail: errorText },
      { status: response.status }
    );
  }

  const data = await response.json();
  return NextResponse.json(data);
}

Step 3 — Client-side call

Call your proxy endpoint from the browser. The API key stays server-side. Braintrust logs every request automatically.

// components/chat.tsx
const response = await fetch('/api/braintrust-proxy', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'Hello from Meridian!' },
    ],
    temperature: 0.7,
    max_tokens: 1024,
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

Why proxy through Meridian?

  • 1Zero key exposure. Your Braintrust API key never leaves the server. Client code only talks to your own endpoint.
  • 2Full observability. Braintrust logs every request, response, latency, and token usage — no client-side instrumentation needed.
  • 3Rate limiting ready. Add per-user quotas, IP throttling, or circuit breakers at the proxy layer without touching your AI logic.
  • 4Model routing. Swap models or add fallback logic server-side. The client sends one request — the proxy decides which model handles it.
← Back to docsOpenAI proxy guide →