> ## 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 or Schedule Pricing

> - Omit (or `null`) `effective_from` to activate the price now.
- Pass a future `effective_from` to schedule the change ahead of time.


Creates a new pricing version for a model. Pricing drives every cost-aware
feature on the platform — usage attribution, spend reporting, and
[token budgets](/api-reference/llm-gateway/token-budgets/listBudgets) with a
`cost_limit`.

## Activate now or schedule for later

The `effective_from` field decides whether the change is immediate or
scheduled:

* **Omit (or `null`)** — the price activates immediately and replaces the
  current effective price for this rule.
* **Future timestamp** — the price activates on that date, recorded as a
  scheduled change. Visible to admins via the [history](/api-reference/llm-gateway/model-pricing/getPricingHistory)
  endpoint and the **Scheduled** affordance in the portal.

Past versions are immutable; to correct a mistake, create a new version with
an immediate `effective_from`.

## Sync mode

`sync_mode` controls whether Barndoor's seeded defaults can move this row
later:

* `pinned` (default for manually-created rules) — never auto-sync.
* `tracking` — show the user a prompt when defaults change.
* `auto` — silently follow the default. Useful when you want to outsource
  pricing maintenance entirely to Barndoor.

## Example

```bash theme={null}
curl -X POST https://app.barndoor.ai/api/llm-gateway/admin/model-pricing \
  -H "Authorization: Bearer $BARNDOOR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "model_provider": "openai",
    "model_pattern": "gpt-4o-mini",
    "input_cost_per_million_tokens": 0.15,
    "output_cost_per_million_tokens": 0.60,
    "sync_mode": "pinned",
    "change_reason": "Q1 2026 negotiated discount"
  }'
```

<Note>
  For wildcards, scheduling, and the four-tier resolution order, see
  [Manage Model Pricing](/how-tos/manage-model-pricing).
</Note>


## OpenAPI

````yaml api-reference/llm-gateway-openapi.yml post /admin/model-pricing
openapi: 3.1.0
info:
  title: Barndoor LLM Gateway API
  version: 1.0.0
  description: >
    REST API for the Barndoor LLM Gateway: configure providers, model routes,

    pricing, governance, and operate a multi-provider LLM platform
    programmatically.


    All endpoints in this document are scoped to your organization. They are the

    same APIs powering the Barndoor portal under **LLM Configuration**,

    **LLM Controls**, and **Settings - My Models**, exposed for teams that

    prefer scripting over the UI.


    ## Base URL


    All requests are issued against your Barndoor instance:


    ```

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

    ```


    Replace `app.barndoor.ai` with your tenant host if you run on Enterprise.


    ## Authentication


    Endpoints accept a JWT Bearer token issued by your Barndoor identity

    provider. Tokens can be obtained interactively via the Barndoor SDK:


    ```ts

    const sdk = await loginInteractive();

    ```


    The token must be sent in the `Authorization` header on every request:


    ```

    Authorization: Bearer eyJhbGciOi...

    ```


    Note: the `bd-...` API keys you create through these endpoints are for

    runtime LLM traffic (`/v1/chat/completions`, `/v1/messages`, etc.), not for

    administrative calls. Administrative endpoints require a user/admin JWT.


    ## Permissions


    Most endpoints require an `admin` (or higher) role on the calling user.

    Read-only endpoints are typically accessible by all authenticated users.

    Read-only listings under `/user/...` are scoped to the authenticated user.


    ## Errors


    Errors are returned as JSON with a stable shape:


    ```json

    { "error": "BadRequest", "message": "request_timeout_secs must be between 1
    and 3600" }

    ```
  contact:
    name: Barndoor Support
    url: https://barndoor.ai
servers:
  - url: https://{host}/api/llm-gateway
    description: >-
      Production / Trial (Barndoor SaaS). The gateway lives on your Barndoor
      control-plane host. For Enterprise or self-hosted deployments, replace the
      host with your portal hostname — the authoritative value is shown on
      Settings → My Models in the portal.
    variables:
      host:
        description: Your Barndoor control-plane (portal) hostname
        default: app.barndoor.ai
  - url: https://app.barndooruat.com/api/llm-gateway
    description: UAT
  - url: https://app.barndoordev.com/api/llm-gateway
    description: Dev
security:
  - BearerAuth: []
tags:
  - name: Credentials
    description: >-
      Reusable upstream credentials (API keys, AWS roles, Vertex service
      accounts)
  - name: Providers
    description: Named upstream providers backed by credentials and a model family
  - name: Provider Catalog
    description: Read-only catalog of supported upstream provider templates
  - name: Model Routes
    description: Map client-facing aliases to one or more upstream provider/model pairs
  - name: Model Pricing
    description: Per-million-token input/output costs for usage and budget reporting
  - name: Rate Limits
    description: Requests-per-minute and tokens-per-minute caps
  - name: Token Budgets
    description: Daily, weekly, or monthly token and cost ceilings
  - name: Model Access
    description: Allowlist or denylist policies for models, providers, or aliases
  - name: Smart Models
    description: Routing policies that pick a target model based on the request
  - name: Governance Configuration
    description: Org-wide behavior toggles for the LLM Gateway
  - name: Route Health
    description: Operational view of upstream route ejection and recovery
  - name: API Keys
    description: Org-managed gateway API keys (the `bd-...` keys callers send on `/v1/...`)
  - name: User
    description: Self-service endpoints for the authenticated user
paths:
  /admin/model-pricing:
    post:
      tags:
        - Model Pricing
      summary: Create or schedule a pricing rule
      description: |
        - Omit (or `null`) `effective_from` to activate the price now.
        - Pass a future `effective_from` to schedule the change ahead of time.
      operationId: createModelPricing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModelPricingRequest'
      responses:
        '200':
          description: The created or no-op'd pricing version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelPricingRule'
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  schemas:
    CreateModelPricingRequest:
      type: object
      required:
        - model_pattern
        - input_cost_per_million_tokens
        - output_cost_per_million_tokens
      properties:
        model_provider:
          type: string
          description: Optional. Defaults to `catalog_slug` if both are unset.
        model_pattern:
          type: string
          example: gpt-4o-mini
        input_cost_per_million_tokens:
          type: number
        output_cost_per_million_tokens:
          type: number
        effective_from:
          type: string
          format: date-time
          nullable: true
          description: |
            When the price activates. Omit (or `null`) for "now". A future
            timestamp creates a scheduled change.
        provider_id:
          type: string
          format: uuid
          nullable: true
        catalog_slug:
          type: string
          nullable: true
        sync_mode:
          $ref: '#/components/schemas/PricingSyncMode'
        change_reason:
          type: string
          example: Q1 negotiated pricing
        cache_read_cost_per_million_tokens:
          type: number
          nullable: true
        cache_write_cost_per_million_tokens:
          type: number
          nullable: true
    ModelPricingRule:
      type: object
      description: |
        A single pricing rule version. Each "rule" (logical row) has a stack
        of versions; the latest version with `effective_from <= now()` is the
        one that bills.
      required:
        - id
        - org_id
        - model_pattern
        - input_cost_per_million_tokens
        - output_cost_per_million_tokens
        - effective_from
        - sync_mode
        - change_source
        - is_archived
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        model_provider:
          type: string
          nullable: true
        model_pattern:
          type: string
          description: Upstream model name (or `*` wildcard)
          example: gpt-4o-mini
        provider_id:
          type: string
          format: uuid
          nullable: true
          description: When set, the rule only applies to routes served by this provider
        catalog_slug:
          type: string
          nullable: true
        input_cost_per_million_tokens:
          type: number
          example: 0.15
        output_cost_per_million_tokens:
          type: number
          example: 0.6
        cache_read_cost_per_million_tokens:
          type: number
          nullable: true
        cache_write_cost_per_million_tokens:
          type: number
          nullable: true
        effective_from:
          type: string
          format: date-time
          description: When this version takes effect. Past = active; future = scheduled
        sync_mode:
          $ref: '#/components/schemas/PricingSyncMode'
        change_source:
          $ref: '#/components/schemas/PricingChangeSource'
        change_reason:
          type: string
          nullable: true
        created_by_user_id:
          type: string
          format: uuid
          nullable: true
        created_by_email:
          type: string
          nullable: true
        is_archived:
          type: boolean
    PricingSyncMode:
      type: string
      description: |
        How the row tracks Barndoor's managed defaults:
          - `tracking` — show the user a prompt when defaults change
          - `pinned` — never sync; this is your number
          - `auto` — silently follow updates to the managed defaults
      enum:
        - tracking
        - pinned
        - auto
    PricingChangeSource:
      type: string
      description: How this version of the pricing rule was produced
      enum:
        - admin_create
        - admin_edit
        - admin_schedule
        - import
        - sync_manual
        - sync_auto
        - admin_archive
        - admin_restore
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: A short machine-readable error code
          example: BadRequest
        message:
          type: string
          description: A human-readable description of what went wrong
          example: request_timeout_secs must be between 1 and 3600
  responses:
    BadRequest:
      description: The request body or query parameters were invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT obtained through Barndoor's authentication flow. Pass the token
        verbatim in `Authorization: Bearer <token>`. Use the Barndoor SDK's
        `loginInteractive()` helper to obtain a token in scripts and notebooks.

````