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

# Create a Provider

> Creates a named upstream provider. Providers whose auth type needs a secret must reference an existing credential with `connection_id`; sending `api_key` or `credentials` here is rejected with `400`.

Pass `models` to enable a list of upstream model names as 1:1 model routes in the same call.

A **Provider** is a named upstream that authenticates with one credential and
serves a model family. Pass `connection_id` referencing an existing
[Credential](/api-reference/llm-gateway/credentials/createCredential); the
provider takes its `auth_type` and settings from it.

<Warning>
  Providers can't store their own key. Sending `api_key` or `credentials` here is
  rejected with `400`, and so is a provider with no `connection_id` unless its auth
  type stores no secret (`claude_oauth` or `codex_oauth`). To rotate a key, update
  the credential.
</Warning>

## Auto-enabling models in one call

Pass a list of upstream model names in `models` and Barndoor will create a 1:1
[Model Route](/api-reference/llm-gateway/model-routes/listAllRoutes) for each
one in the same call. The route's alias matches the upstream model name so
callers can address it as `<provider>/<model>`. Add bare-name aliases or
failover routes afterwards via the Model Routes endpoints.

## Example

```bash theme={null}
curl -X POST https://app.barndoor.ai/api/llm-gateway/admin/providers \
  -H "Authorization: Bearer $BARNDOOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI Production (US)",
    "model_provider": "openai",
    "base_url": "https://api.openai.com/v1",
    "connection_id": "4f8b2a3c-12ee-4d92-9c7b-e7d2f8b0a111",
    "models": ["gpt-5.5", "gpt-5.4-mini", "text-embedding-3-large"]
  }'
```

<Note>
  See the [Quickstart Guide](/how-tos/llm-gateway-quickstart#step-2-create-a-provider) for the full walkthrough.
</Note>


## OpenAPI

````yaml api-reference/llm-gateway-openapi.yml post /admin/providers
openapi: 3.1.0
info:
  title: Barndoor LLM Gateway Admin API
  version: 1.0.0
  description: >
    Configure the Barndoor LLM Gateway programmatically: credentials and
    providers,

    model routes and route groups, pricing, routing policies and rules, launch
    profiles,

    budgets, rate limits, model access, API keys, and organization-wide
    governance settings.


    These are the same APIs the Barndoor app uses under **LLM Management**, and
    the

    Barndoor Terraform provider manages its LLM Gateway resources through them.
    Every

    endpoint is scoped to the organization of the calling token.


    ## Base URL


    ```

    https://app.barndoor.ai/api/llm-gateway

    ```


    For a dedicated deployment, replace `app.barndoor.ai` with the host you sign
    in to.


    ## Authentication


    Send an access token from Barndoor's identity provider in the
    `Authorization` header:


    ```

    Authorization: Bearer <access-token>

    ```


    For scripts and CI, use a service-account token from the OAuth 2.0
    client-credentials

    grant, as the Terraform provider does. The caller needs the admin role in
    the

    organization.


    The `bd-...` API keys you create with these endpoints are for LLM traffic

    (`/v1/chat/completions`, `/v1/messages`, and so on), not for these
    administrative calls.


    ## Partial updates


    Most `PUT` endpoints change only the fields you send. Where a field can be
    cleared,

    send it as `null`; omitting it leaves it unchanged. The exceptions are
    called out on

    the endpoint: `PUT /admin/governance-config` replaces the whole
    configuration,

    `PUT /admin/routing-rules/{id}` replaces the whole rule, and

    `PUT /admin/agent-runtime-profiles/{slug}` replaces the profile's models.


    ## Errors


    Errors are returned as JSON:


    ```json

    { "error": { "message": "retry_on_429_count must be between 0 and 10",
    "type": "invalid_request_error" } }

    ```
  contact:
    name: Barndoor Support
    url: https://barndoor.ai
servers:
  - url: https://{host}/api/llm-gateway
    description: Your Barndoor platform host.
    variables:
      host:
        default: app.barndoor.ai
        description: >-
          The host serving your Barndoor deployment. Use the default for
          Barndoor SaaS; for a dedicated deployment, use the host you sign in
          to.
security:
  - BearerAuth: []
tags:
  - name: Credentials
    description: >-
      Stored upstream secrets (API keys, AWS roles, Google credentials) that
      providers reference
  - name: Providers
    description: Named upstream providers backed by a credential and a model family
  - name: Model Routes
    description: >-
      Map caller-facing aliases to upstream models on one or more providers,
      with failover order, retries, timeouts, and cooldowns
  - name: Route Groups
    description: >-
      Named sets of model aliases that model access policies can target as one
      unit
  - name: Model Pricing
    description: >-
      Versioned per-million-token costs used for cost reporting and cost-based
      budgets
  - name: Routing Policies
    description: Model aliases that pick one of several model slots for each request
  - name: Routing Rules
    description: >-
      Plain-English rules that set a minimum slot or forbid slots on a routing
      policy
  - name: Launch Profiles
    description: >-
      Models and capabilities applied when members start an agent with barndoor
      run
  - name: Rate Limits
    description: Requests-per-minute and tokens-per-minute ceilings
  - name: Budgets
    description: Daily, weekly, or monthly token and cost ceilings
  - name: Model Access
    description: >-
      Allowlist and denylist policies for models, providers, aliases, and route
      groups
  - name: Governance
    description: Organization-wide LLM Gateway settings
  - name: API Keys
    description: Organization-managed `bd-...` gateway API keys for LLM traffic
paths:
  /admin/providers:
    post:
      tags:
        - Providers
      summary: Create a provider
      description: >-
        Creates a named upstream provider. Providers whose auth type needs a
        secret must reference an existing credential with `connection_id`;
        sending `api_key` or `credentials` here is rejected with `400`.


        Pass `models` to enable a list of upstream model names as 1:1 model
        routes in the same call.
      operationId: createProvider
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProviderRequest'
        required: true
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Provider'
        '400':
          description: Invalid request. The error message says which field or rule failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Your role does not allow this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such record in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Another record already uses this name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []
components:
  schemas:
    CreateProviderRequest:
      type: object
      required:
        - name
        - model_provider
        - base_url
      properties:
        api_key:
          type:
            - string
            - 'null'
          description: >-
            Not accepted for auth types that need a stored secret: create a
            credential and pass `connection_id` instead.
        auth_type:
          type:
            - string
            - 'null'
          description: How the gateway authenticates upstream. Defaults by provider family.
        base_url:
          type: string
        billing_mode:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/BillingMode'
              description: >-
                Whether the gateway records a per-token cost. Defaults to
                `per_token`.
        billing_note:
          type:
            - string
            - 'null'
          description: Optional note about the billing arrangement, up to 200 characters.
        billing_reason:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/BillingReason'
              description: >-
                How the vendor bills. Required when `billing_mode` is
                `not_metered`.
        catalog_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Optional provider catalog entry this provider was created from.
        change_note:
          type:
            - string
            - 'null'
          description: >-
            Optional note explaining why this was created. Shown with the record
            and in the audit log.
        connection_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            ID of the credential this provider uses. Required for every auth
            type that needs a stored secret.
        credentials:
          description: >-
            Not accepted for auth types that need a stored secret: create a
            credential and pass `connection_id` instead.
        enforce_health_check:
          type:
            - boolean
            - 'null'
          description: >-
            Whether routing waits on the connectivity check. Defaults to `true`;
            set `false` to serve the provider even while its check fails.
        model_provider:
          type: string
          description: >-
            Provider family, which decides the protocol the gateway speaks
            upstream, for example `openai`, `anthropic`, `azure_openai`,
            `bedrock`, `vertex`, or `custom`.
        model_sync_mode:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ModelSyncMode'
              description: >-
                Whether the provider follows Barndoor's model catalog. Defaults
                to `off`.
        models:
          type: array
          items:
            type: string
          description: Upstream model names to enable as 1:1 model routes in the same call.
        name:
          type: string
        request_timeout_secs:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Provider-wide fallback for the non-streaming request timeout, in
            seconds (1–600). Rarely needed: routes carry their own timeout.
        settings:
          description: >-
            Provider-specific settings as a JSON object, such as `region` for
            Bedrock or `api_version` for Azure OpenAI.
        stream_idle_timeout_secs:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Provider-wide fallback for the streaming idle timeout, in seconds
            (1–300). Rarely needed: routes carry their own timeout.
    Provider:
      allOf:
        - $ref: '#/components/schemas/ChangeAttribution'
        - type: object
          required:
            - id
            - org_id
            - name
            - model_provider
            - auth_type
            - base_url
            - secret_path
            - enabled
            - settings
            - created_at
            - updated_at
            - health_status
            - enforce_health_check
            - model_sync_mode
            - billing_mode
          properties:
            auth_type:
              type: string
            base_url:
              type: string
            billing_mode:
              $ref: '#/components/schemas/BillingMode'
              description: >-
                Whether the gateway records a per-token cost for this provider's
                traffic.
            billing_note:
              type:
                - string
                - 'null'
              description: Note about the billing arrangement.
            billing_reason:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/BillingReason'
                  description: How the vendor bills this provider. Descriptive only.
            catalog_id:
              type:
                - string
                - 'null'
              format: uuid
            catalog_slug:
              type:
                - string
                - 'null'
            connection_id:
              type:
                - string
                - 'null'
              format: uuid
              description: ID of the credential this provider uses.
            created_at:
              type: string
              format: date-time
            enabled:
              type: boolean
              description: Whether the provider may serve traffic.
            enforce_health_check:
              type: boolean
              description: >-
                Whether routing waits on the connectivity check. When `false`
                the provider serves even while its check fails; health is still
                recorded.
            health_checked_at:
              type:
                - string
                - 'null'
              format: date-time
              description: >-
                When the last connectivity check ran; null before the first
                check.
            health_detail:
              type:
                - string
                - 'null'
              description: Reason for the last `unhealthy` result; null otherwise.
            health_status:
              type: string
              description: >-
                Upstream reachability from the connectivity check: `unverified`,
                `healthy`, or `unhealthy`. Separate from `enabled`. An enabled
                provider that turns `unhealthy` stops receiving traffic until a
                check records it healthy again, unless `enforce_health_check` is
                `false`. Some provider families are not checked and stay
                `unverified`.
            id:
              type: string
              format: uuid
            model_provider:
              type: string
            model_sync_mode:
              $ref: '#/components/schemas/ModelSyncMode'
              description: Whether this provider follows Barndoor's model catalog.
            name:
              type: string
            org_id:
              type: string
              format: uuid
            request_timeout_secs:
              type:
                - integer
                - 'null'
              format: int32
              description: >-
                Provider-wide fallback for the non-streaming request timeout, in
                seconds.
            secret_path:
              type: string
              description: Internal reference to the stored secret. This is not the secret.
            settings: {}
            stream_idle_timeout_secs:
              type:
                - integer
                - 'null'
              format: int32
              description: >-
                Provider-wide fallback for the streaming idle timeout, in
                seconds.
            updated_at:
              type: string
              format: date-time
      description: An upstream provider.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              description: Human-readable explanation of what went wrong.
            type:
              type: string
              description: >-
                Error category, such as `invalid_request_error`,
                `authentication_error`, `permission_error`, `not_found_error`,
                or `conflict_error`.
            code:
              type:
                - string
                - 'null'
              description: Machine-readable code, when one applies.
      example:
        error:
          message: retry_on_429_count must be between 0 and 10
          type: invalid_request_error
    BillingMode:
      type: string
      description: >-
        `per_token`: the gateway records a per-token cost for this provider's
        traffic. `not_metered`: traffic records no cost, for example under a
        flat-rate subscription or for a local model.
      enum:
        - per_token
        - not_metered
    BillingReason:
      type: string
      description: >-
        How the vendor bills this provider: `subscription`, `local`, `external`,
        or `other`. Required when `billing_mode` is `not_metered`. Descriptive
        only.
      enum:
        - subscription
        - local
        - external
        - other
    ModelSyncMode:
      type: string
      description: >-
        Whether a provider follows Barndoor's model catalog: `off` (default),
        `additive` (new catalog models are added), or `full` (models are also
        disabled when they leave the catalog).
      enum:
        - 'off'
        - additive
        - full
    ChangeAttribution:
      type: object
      description: >-
        Who created and last changed the record, and why. Records created before
        attribution was added have no values until their next change.
      properties:
        created_by_email:
          type:
            - string
            - 'null'
        created_by_name:
          type:
            - string
            - 'null'
        created_by_user_id:
          type:
            - string
            - 'null'
          format: uuid
        last_change_note:
          type:
            - string
            - 'null'
          description: Note explaining the last change.
        last_modified_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the last attributed change was made.
        last_modified_by_email:
          type:
            - string
            - 'null'
        last_modified_by_name:
          type:
            - string
            - 'null'
        last_modified_by_user_id:
          type:
            - string
            - 'null'
          format: uuid
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        An access token from Barndoor's identity provider, sent as
        `Authorization: Bearer <token>`. Use a service-account token from the
        OAuth 2.0 client-credentials grant for scripts and CI, or a signed-in
        user's token. The caller needs the admin role in the organization.
        Gateway API keys (`bd-...`) are not accepted here.

````

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