> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create project-level AI providers via API

> Create and update project-level AI provider credentials and configuration programmatically.

> [!NOTE]
>
> **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](https://docs.braintrust.dev/integrations/ai-providers.md) 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](https://docs.braintrust.dev/api-reference/envvars/create-or-replace-env-var.md).

### 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

1. Open **Settings → Models → Project** for your project.
2. Confirm the provider appears with the expected configuration.
3. Open a playground in the same project, select the configured provider and model, and run a short prompt.
4. 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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`.

> [!NOTE]
>
> 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](https://docs.braintrust.dev/admin/ai-providers.md#request-routing).

See [Use project-level AI providers](https://docs.braintrust.dev/deploy/gateway.md#use-project-level-ai-providers) for SDK examples.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.