Create project-level AI providers via API

Applies to:

Plan - Any
Deployment - Any
Use case - Create and manage project-level AI provider credentials and configuration programmatically

Summary

Use /v1/env_var to create an AI provider for a specific project. Store the provider credential in value and its configuration in metadata. This lets you automate project-level provider setup instead of adding each provider manually in the UI.

What is happening

Project-level AI providers are stored as environment variables with object_type: "project" and secret_category: "ai_provider". The provider configuration determines which service Braintrust calls. This can be a supported AI provider or a custom endpoint, including an external AI gateway. The provider type, credentials, and configuration must match the service you want to use. See AI provider integrations for provider-specific requirements.

Fix or suggestion

Step 1: Gather your configuration

You need:

A Braintrust API key with permission to update the project.
Your project ID, available from Copy Project ID on the project’s configuration page.
The provider’s credentials and required configuration.

For a custom endpoint, also gather its API base URL and the exact model names it accepts.

Step 2: Create the project provider

Send a PUT request to /v1/env_var with these fields:

Field	Purpose
`object_type`	Set to `"project"`.
`object_id`	The Braintrust project ID.
`name`	The provider configuration name.
`value`	The provider credential.
`secret_category`	Set to `"ai_provider"`.
`secret_type`	The underlying provider type.
`metadata`	Provider-specific configuration, such as the endpoint and custom models.

Create the provider using the request below. Replace the placeholders with your project ID, provider credentials, endpoint URL, and model name. The example uses OpenAI-compatible chat settings. Adjust these to match your provider. Set BRAINTRUST_API_KEY to your Braintrust API key and put your provider credential in value. If your organization uses a different Braintrust API URL, replace https://api.braintrust.dev with that URL.

curl --fail-with-body -X PUT \
  "https://api.braintrust.dev/v1/env_var" \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "object_type": "project",
    "object_id": "<project_id>",
    "name": "My New Provider",
    "value": "<provider_token>",
    "secret_type": "openai",
    "secret_category": "ai_provider",
    "metadata": {
      "api_base": "https://provider.example.com/v1",
      "customModels": {
        "<model_name>": {
          "format": "openai",
          "flavor": "chat"
        }
      }
    }
  }'

Save the returned id for future updates. See Create or replace env var.

Step 3: Update the configuration when needed

Use PATCH /v1/env_var/<id> to update the endpoint or model configuration in metadata. Omit value to keep the stored credential. Metadata is replaced, not merged. Include api_base, the complete customModels map, and any other settings you want to keep.

How to confirm it worked

Open Settings → Models → Project for your project.
Confirm the provider appears with the expected configuration.
Open a playground in the same project, select the configured provider and model, and run a short prompt.
Confirm the request succeeds and returns a model response.

Notes

/v1/env_var configures project-level providers. For organization-level providers, use /v1/ai_secret.
PUT /v1/env_var creates or replaces the matching entry. Reusing the same provider name in the same project updates that entry.
For custom models, list each exact model name in metadata.customModels; wildcards are not supported.
The example’s "format": "openai" and "flavor": "chat" settings apply to an OpenAI-compatible chat endpoint. Use settings appropriate to your provider and model.
Creating the configuration does not grant access to models at the upstream provider. Your provider credentials must allow access to the models you configure.

Optional: Use the provider through the Gateway

When calling the Braintrust Gateway, include x-bt-project-id to load the project’s providers and x-bt-endpoint-name to select My New Provider by its exact, case-sensitive name. The example below uses the hosted Gateway.

curl --fail-with-body \
  "https://gateway.braintrust.dev/chat/completions" \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-bt-org-name: <organization_name>" \
  -H "x-bt-project-id: <project_id>" \
  -H "x-bt-endpoint-name: My New Provider" \
  -d '{
    "model": "<model_name>",
    "messages": [
      {"role": "user", "content": "Say hello"}
    ]
  }'

Use your deployment’s Gateway URL if different. A successful request returns a model response. You can set these headers once in your model client’s default headers. Alternatively, use x-bt-project-name with the exact project name instead of x-bt-project-id.

If the name doesn’t match an existing project, the Gateway creates a new project with that name and logs the request to it. Use the exact name of your intended project to avoid logging to an unintended one.

Gateway-specific notes:

Assigning a project to Eval(...) does not automatically pass that context to a separately configured model client. The Gateway request needs its own project context.
When organization and project providers overlap, provider eligibility depends on model support, permissions, and deployment. See provider routing rules.

See Use project-level AI providers for SDK examples.

​Summary

​What is happening

​Fix or suggestion

​Step 1: Gather your configuration

​Step 2: Create the project provider

​Step 3: Update the configuration when needed

​How to confirm it worked

​Notes

​Optional: Use the provider through the Gateway

Summary

What is happening

Fix or suggestion

Step 1: Gather your configuration

Step 2: Create the project provider

Step 3: Update the configuration when needed

How to confirm it worked

Notes

Optional: Use the provider through the Gateway