# AUTO-GENERATED tier-A mirror spec — do not edit.
# Source: openapi/runtime/ai-providers.yaml (runtime 0.124.0)
#  + policy: openapi/mirror-policies/ai-providers.json
# Regenerate: node scripts/generate-mirror-specs.mjs
openapi: 3.0.3
info:
  title: naturali.ai — AI Providers API
  version: 1.0.0
  description: >-
    AI providers: the credentialed model vendors a project generates through, the models each one
    offers, and their per-token prices. A fully runtime-backed module — this spec is generated
    verbatim from the runtime's own, re-rooted under /v1/projects/{project_id}. The project in the
    path is authorized by naturali and enforced upstream by the project's scoped credential.


    The first page of every project's listing also carries naturali's shared provider, which serves
    every model `GET /v1/models` lists on naturali's own model access. A project reads it and
    generates through it; it cannot change, price or delete it.


    This module mirrors the upstream runtime verbatim (tier A): paths are the runtime's own
    re-rooted under /v1/projects/{project_id}, and every field, method, status code and error shape
    passes through unchanged. Errors raised by the runtime arrive in its envelope; errors raised by
    naturali itself (authentication, project resolution, an unreachable runtime) use naturali's.
  contact:
    name: naturali.ai
    url: https://naturali.ai
servers:
  - url: "{baseUrl}"
    description: Host of your naturali.ai deployment; every path carries the /v1 prefix.
    variables:
      baseUrl:
        description: Base host URL.
        default: https://api.naturali.ai
tags:
  - name: AI Providers
    description: Manage AI providers
security:
  - bearerAuth: []
  - oauth2:
      - mcp:access
paths:
  /v1/projects/{project_id}/ai-providers:
    get:
      tags:
        - AI Providers
      summary: List AI providers
      description: Returns a list of AI provider configurations for a project
      operationId: listAiProviders
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: List of AI providers
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            provider:
                              type: string
                              enum:
                                - openai
                                - anthropic
                                - google
                                - xai
                                - groq
                                - ollama
                                - azure
                                - bedrock
                                - vertex
                                - gateway
                                - custom
                            default_model:
                              type: string
                            secret_id:
                              x-naturali-ref: secrets
                              type: string
                              nullable: true
                              description: Secret ID containing API credentials, or null when the record links none.
                            base_url:
                              type: string
                              description: Custom base URL for the provider. Absent when the record sets none.
                            config:
                              type: object
                              description: Additional provider-specific configuration. Absent when the record sets none. Never
                                carries a credential.
                            model_aliases:
                              type: object
                              additionalProperties:
                                $ref: "#/components/schemas/ModelAliasTarget"
                              description: Alias → the model id sent to the vendor, or `{ ai_provider_id, model }` naming another
                                provider of the project that serves it. A model named beside this
                                provider may be an alias; reads, usage, prices and traces answer the
                                alias and this provider, and only the vendor call uses the target
                                and the id. Empty when the provider has none.
                            model_aliases_only:
                              type: boolean
                              description: When `true`, a model that is not one of `model_aliases` is refused with
                                `MODEL_NOT_OFFERED` (400).
                            require_priced_model:
                              type: boolean
                              description: When `true`, a generation on this provider whose model no price-book row covers is
                                refused with `MODEL_NOT_PRICED` (409) before the provider is called,
                                as the project's `require_priced_model` does for every provider of
                                the project.
                            project_id:
                              x-naturali-ref: projects
                              type: string
                            created_at:
                              type: string
                              format: date-time
                            updated_at:
                              type: string
                              format: date-time
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/ProjectNotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      tags:
        - AI Providers
      summary: Create an AI provider
      description: |
        Creates a new LLM provider configuration.

        A provider's credential is its linked `secret_id`; `config.apiKey` is
        refused with `400 VALIDATION_FAILED`.

        A record with both `base_url` and `secret_id` sends the secret to that
        URL, so creating one also needs `secrets:UseSecret` on the secret, else
        `403`.

        A `bedrock` or `vertex` record must link one. Without it the provider
        SDK signs with the server's own credentials (the AWS default credential
        chain, Google Application Default Credentials), which is refused with
        `400 VALIDATION_FAILED` unless the deployment allows it.
      operationId: createAiProvider
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - provider
                - default_model
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: Provider configuration name
                  example: OpenAI Production
                provider:
                  type: string
                  enum:
                    - openai
                    - anthropic
                    - google
                    - xai
                    - groq
                    - ollama
                    - azure
                    - bedrock
                    - vertex
                    - gateway
                    - custom
                  description: LLM provider
                  example: openai
                default_model:
                  type: string
                  description: Default model to use
                  example: gpt-4
                secret_id:
                  x-naturali-ref: secrets
                  type: string
                  description: Secret ID containing API credentials. Required for `bedrock` and `vertex`.
                  example: sec_V1StGXR8Z5jdHi6B
                base_url:
                  type: string
                  description: Custom base URL for the provider
                config:
                  type: object
                  description: "Additional provider-specific configuration. `apiKey` is refused: the credential goes
                    in the linked secret."
                model_aliases:
                  type: object
                  additionalProperties:
                    $ref: "#/components/schemas/ModelAliasTarget"
                  description: Alias → the model id sent to the vendor, or `{ ai_provider_id, model }` naming another
                    provider of the project that serves it.
                  example:
                    fast: gpt-4o-mini
                model_aliases_only:
                  type: boolean
                  default: false
                  description: When `true`, a model that is not one of `model_aliases` is refused with
                    `MODEL_NOT_OFFERED` (400).
                require_priced_model:
                  type: boolean
                  default: false
                  description: When `true`, a generation on this provider whose model no price-book row covers is
                    refused with `MODEL_NOT_PRICED` (409) before the provider is called, as the
                    project's `require_priced_model` does for every provider of the project.
      responses:
        "201":
          description: AI provider created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  provider:
                    type: string
                  default_model:
                    type: string
                  model_aliases:
                    type: object
                    additionalProperties:
                      $ref: "#/components/schemas/ModelAliasTarget"
                    description: Alias → the model id sent to the vendor, or `{ ai_provider_id, model }` naming another
                      provider of the project that serves it. A model named beside this provider may
                      be an alias; reads, usage, prices and traces answer the alias and this
                      provider, and only the vendor call uses the target and the id. Empty when the
                      provider has none.
                  model_aliases_only:
                    type: boolean
                    description: When `true`, a model that is not one of `model_aliases` is refused with
                      `MODEL_NOT_OFFERED` (400).
                  require_priced_model:
                    type: boolean
                    description: When `true`, a generation on this provider whose model no price-book row covers is
                      refused with `MODEL_NOT_PRICED` (409) before the provider is called, as the
                      project's `require_priced_model` does for every provider of the project.
                  project_id:
                    x-naturali-ref: projects
                    type: string
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
        "400":
          description: Bad request (invalid provider or missing fields)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          $ref: "#/components/responses/ProjectNotFound"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/ai-providers/{ai_provider_id}:
    get:
      tags:
        - AI Providers
      summary: Get an AI provider
      description: >
        Returns a specific AI provider configuration. A credential scoped to a project the provider
        is shared with, through an accepted share, reads its `id`, `name`, `provider`,
        `default_model` and `model_alias_names` only.
      operationId: getAiProvider
      parameters:
        - name: ai_provider_id
          in: path
          required: true
          description: AI Provider ID
          schema:
            type: string
            example: aip_V1StGXR8Z5jdHi6B
      responses:
        "200":
          description: AI provider details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  provider:
                    type: string
                  default_model:
                    type: string
                  project_id:
                    x-naturali-ref: projects
                    type: string
                  secret_id:
                    x-naturali-ref: secrets
                    type: string
                    nullable: true
                  base_url:
                    type: string
                  config:
                    type: object
                    description: Additional provider-specific configuration. Never carries a credential.
                  model_aliases:
                    type: object
                    additionalProperties:
                      $ref: "#/components/schemas/ModelAliasTarget"
                    description: Alias → the model id sent to the vendor, or `{ ai_provider_id, model }` naming another
                      provider of the project that serves it. A model named beside this provider may
                      be an alias; reads, usage, prices and traces answer the alias and this
                      provider, and only the vendor call uses the target and the id. Empty when the
                      provider has none.
                  model_alias_names:
                    type: array
                    items:
                      type: string
                    description: The alias names of `model_aliases`, on a shared projection only.
                  model_aliases_only:
                    type: boolean
                    description: When `true`, a model that is not one of `model_aliases` is refused with
                      `MODEL_NOT_OFFERED` (400).
                  require_priced_model:
                    type: boolean
                    description: When `true`, a generation on this provider whose model no price-book row covers is
                      refused with `MODEL_NOT_PRICED` (409) before the provider is called, as the
                      project's `require_priced_model` does for every provider of the project.
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: AI provider not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    patch:
      tags:
        - AI Providers
      summary: Update an AI provider
      description: Updates an AI provider configuration. Setting `base_url` or `secret_id` so the record
        holds both also needs `secrets:UseSecret` on the secret, else `403`.
      operationId: updateAiProvider
      parameters:
        - name: ai_provider_id
          in: path
          required: true
          description: AI Provider ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                provider:
                  type: string
                  enum:
                    - openai
                    - anthropic
                    - google
                    - xai
                    - groq
                    - ollama
                    - azure
                    - bedrock
                    - vertex
                    - gateway
                    - custom
                  description: LLM provider
                  example: openai
                default_model:
                  type: string
                secret_id:
                  x-naturali-ref: secrets
                  type: string
                  nullable: true
                base_url:
                  type: string
                config:
                  type: object
                  description: "Replaces the whole configuration. `apiKey` is refused: the credential goes in the
                    linked secret."
                model_aliases:
                  type: object
                  nullable: true
                  additionalProperties:
                    $ref: "#/components/schemas/ModelAliasTarget"
                  description: Alias → the model id sent to the vendor, or `{ ai_provider_id, model }` naming another
                    provider of the project that serves it. Replaces the whole map; `null` clears
                    it.
                  example:
                    fast: gpt-4o-mini
                model_aliases_only:
                  type: boolean
                  description: When `true`, a model that is not one of `model_aliases` is refused with
                    `MODEL_NOT_OFFERED` (400).
                require_priced_model:
                  type: boolean
                  description: When `true`, a generation on this provider whose model no price-book row covers is
                    refused with `MODEL_NOT_PRICED` (409) before the provider is called, as the
                    project's `require_priced_model` does for every provider of the project.
      responses:
        "200":
          description: AI provider updated successfully
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: AI provider not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    delete:
      tags:
        - AI Providers
      summary: Delete an AI provider
      description: >
        Deletes an AI provider configuration.


        Live references — the provider project's agents, model routes whose targets name this
        provider, and providers whose `model_aliases` forward to it (`meta.ai_provider_ids`) —
        always block deletion with `409 AI_PROVIDER_HAS_DEPENDENTS`; `force` does not override them,
        so delete or repoint those resources first. Soft dependents — price overrides,
        usage/generation records and shares another project has accepted — also block with `409`
        unless `force=true`, which deletes the provider's price overrides, revokes its shares and
        unlinks its usage history, preserving those rows: each usage event keeps the provider's id
        as its `ai_provider_id`. A grantee project's agents pinned to the provider fall back to that
        project's default route. The `409` body's `error.meta` reports the counts, a sample of
        offending IDs, and a `forcible` flag that is `true` when a `force=true` retry would succeed.
      operationId: deleteAiProvider
      parameters:
        - name: ai_provider_id
          in: path
          required: true
          description: AI Provider ID
          schema:
            type: string
        - name: force
          in: query
          required: false
          description: >
            When `true`, delete the provider's price overrides, revoke its shares and unlink its
            usage history so a provider with only soft dependents can be removed. Has no effect on
            live references (agents, model routes), which always block deletion.
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: AI provider deleted successfully
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: AI provider not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "409":
          description: >
            The AI provider still has dependents. Live references always block; soft dependents
            block unless force=true. See error.meta for counts, offending IDs, and the forcible
            flag.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/ai-providers/{ai_provider_id}/models:
    get:
      tags:
        - AI Providers
      summary: List the models this provider can run
      description: >
        Asks the provider which models it can run, using this provider record's own credentials and
        configuration, and returns provider-native model ids — the same strings `default_model` and
        an agent's `model` carry.

        Which models are reachable is a property of the credential, not of the provider type: a
        Vertex provider sees only the publisher models its Google Cloud project and location serve,
        and a Bedrock provider only the foundation models enabled in its region. Reading the list is
        how a caller avoids pinning a model that fails at generation time.

        Not every provider type can answer. `azure` lists deployments an operator named rather than
        models, and `ollama` lists whatever was pulled onto that host, so both return `400
        MODEL_LISTING_UNSUPPORTED`.

        Listing resolves credentials the same way generation does, so a record that can generate can
        list. The API-key types (`openai`, `groq`, `xai`, `gateway`, `custom`, `anthropic`,
        `google`) use the record's linked secret and cannot list without one. `bedrock` and `vertex`
        use the linked secret — IAM keys or a Bedrock API key, a Google service-account key. A
        record with no `secret_id` would fall back to the server's own credentials (the AWS default
        credential chain, Google Application Default Credentials); it can list only on a deployment
        that allows a record to use them, and returns `400 AI_PROVIDER_MISCONFIGURED` otherwise.

        A Vertex record needs no `config.project` when its secret is a service-account key, since
        the key file names its own project. A Vertex record in express mode (API key) cannot list at
        all: the publisher-model listing rejects API keys and needs a credential that asserts a
        principal, so it returns `400 MODEL_LISTING_UNSUPPORTED`.

        The Vertex answer is the publisher catalogue the record's `config.location` region serves.
        The project behind the credential is billed and quota'd for the call but does not filter the
        result, so a listed model may still be unavailable to that project at generation time.

        The provider answers its whole catalogue in one call; `q`, `limit` and `cursor` narrow and
        page what it returned. A request without `limit` gets the first 50 models.
      operationId: listAiProviderModels
      parameters:
        - name: ai_provider_id
          in: path
          required: true
          description: AI Provider ID
          schema:
            type: string
            example: aip_V1StGXR8Z5jdHi6B
        - name: q
          in: query
          description: >
            Keeps the models whose `id` or `display_name` contains this text, ignoring case. Applied
            before paging.
          schema:
            type: string
            example: sonnet
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: The models this provider can run
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderModelsResponse"
        "400":
          description: >
            The provider type or authentication mode cannot enumerate models (including Vertex
            express mode), or the record is missing configuration the listing needs (a Vertex
            project from either `config.project` or the service-account key file, a Bedrock region,
            or — for the API-key provider types — a linked secret).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: AI provider not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          description: The provider rejected the listing request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
  /v1/projects/{project_id}/ai-providers/{ai_provider_id}/prices:
    get:
      tags:
        - AI Providers
      summary: List per-provider price overrides
      description: >
        Returns the per-provider price overrides for this AI provider instance. An override prices
        this specific provider (e.g. an enterprise-negotiated rate or a gateway with markup) and
        wins over the global default at cost time. Authorized by the caller's access to the
        provider's project — so, unlike the global price book, a project's own overrides are visible
        here.
      operationId: getAiProviderPrices
      parameters:
        - name: ai_provider_id
          in: path
          required: true
          description: AI Provider ID
          schema:
            type: string
            example: aip_V1StGXR8Z5jdHi6B
      responses:
        "200":
          description: The provider's price overrides
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderPricesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: AI provider not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      tags:
        - AI Providers
      summary: Upsert per-provider price overrides
      description: >
        Upserts price overrides for this AI provider instance, keyed on (model, effective_from). The
        provider slug is taken from the AI provider itself, so only the model, rates, and
        effective_from are supplied. Authorized by the caller's access to the provider's project.
        `effective_from` must be in the future once the (model, component) has a price row — past
        prices are immutable, so corrections ship as new future-dated rows. A first price for a
        (model, component) nothing prices yet may be dated now or earlier, so a new provider is
        never live and unpriced.
      operationId: updateAiProviderPrices
      x-naturali-agent-exclude: true
      parameters:
        - name: ai_provider_id
          in: path
          required: true
          description: AI Provider ID
          schema:
            type: string
            example: aip_V1StGXR8Z5jdHi6B
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpsertProviderPricesRequest"
      responses:
        "200":
          description: The upserted price overrides
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderPricesResponse"
        "400":
          description: Bad Request (e.g. non-future effective_from)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: AI provider not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          $ref: "#/components/responses/AdmissionUnavailable"
        4XX:
          $ref: "#/components/responses/AdmissionRefused"
    parameters:
      - $ref: "#/components/parameters/ProjectId"
components:
  schemas:
    ModelAliasTarget:
      description: >
        The model id sent to the vendor, or another provider of the same project and the model id
        sent to its vendor. A forward is one hop: its target forwards nothing, and is never the
        provider holding the alias.
      oneOf:
        - type: string
          minLength: 1
        - type: object
          required:
            - ai_provider_id
            - model
          additionalProperties: false
          properties:
            ai_provider_id:
              x-naturali-ref: ai-providers
              type: string
              description: The provider whose endpoint and credential serve the alias
              example: aip_V1StGXR8Z5jdHi6B
            model:
              type: string
              minLength: 1
              description: The model id sent to that provider's vendor
              example: gpt-4o-mini
    ProviderPrice:
      type: object
      properties:
        id:
          type: string
          description: Public ID of the price row
          example: price_V1StGXR8Z5jdHi6B
        ai_provider_id:
          x-naturali-ref: ai-providers
          type: string
          description: The AI provider instance this override prices
          example: aip_V1StGXR8Z5jdHi6B
        meter_type:
          type: string
          description: Always `llm_tokens` for provider price overrides
        provider:
          type: string
          description: Provider slug (taken from the AI provider instance)
          example: openai
        model:
          type: string
          example: gpt-4o
        component:
          type: string
          description: The token component this row prices (`input_tokens`, `output_tokens`, `cached_tokens`,
            `cache_write_tokens`)
        unit:
          type: string
          description: Always `token` for provider price overrides
        unit_price:
          type: number
          description: USD per token for this component
        effective_from:
          type: string
          format: date-time
          description: The row with the latest effective_from <= now() prices a call
        created_at:
          type: string
          format: date-time
    ProviderPricesResponse:
      type: object
      properties:
        prices:
          type: array
          items:
            $ref: "#/components/schemas/ProviderPrice"
    UpsertProviderPricesRequest:
      type: object
      required:
        - prices
      additionalProperties: false
      properties:
        prices:
          type: array
          items:
            type: object
            required:
              - model
              - component
              - unit
              - unit_price
              - effective_from
            additionalProperties: false
            properties:
              model:
                type: string
                example: gpt-4o
              component:
                type: string
                description: The token component this row prices (`input_tokens`, `output_tokens`, `cached_tokens`,
                  `cache_write_tokens`)
              unit:
                type: string
                description: Always `token` for token pricing
              unit_price:
                type: number
                description: USD per token for this component
              effective_from:
                type: string
                format: date-time
                description: Must be in the future; past prices are immutable
    ProviderModelsResponse:
      allOf:
        - $ref: "#/components/schemas/Page"
        - properties:
            data:
              type: array
              items:
                type: object
                required:
                  - id
                properties:
                  id:
                    type: string
                    description: >
                      The provider-native model id, ready to use as `default_model` or an agent's
                      `model`
                    example: gemini-2.5-flash
                  display_name:
                    type: string
                    description: The provider's own human-readable name, when it reports one
                    example: Gemini 2.5 Flash
                  vendor:
                    type: string
                    description: Who makes the model, when the provider reports it
                    example: google
                  input_modalities:
                    type: array
                    description: Lowercased input modalities, when the provider reports them
                    items:
                      type: string
                    example:
                      - text
                      - image
                  output_modalities:
                    type: array
                    description: Lowercased output modalities, when the provider reports them
                    items:
                      type: string
                    example:
                      - text
                  streaming:
                    type: boolean
                    description: Whether the model supports streaming responses
                  lifecycle:
                    type: string
                    description: >
                      `active`, `legacy` or `deprecated`, as the provider reports it. A model that
                      is not `active` still serves today but should not be pinned by anything new.
                    enum:
                      - active
                      - legacy
                      - deprecated
                  inference_types:
                    type: array
                    description: >
                      Lowercased inference types the model supports, when reported. A Bedrock model
                      offering only `inference_profile` must be invoked through a cross-region
                      profile id rather than the bare model id.
                    items:
                      type: string
                    example:
                      - on_demand
                      - inference_profile
    Page:
      type: object
      description: One page of a list. Rows inserted or removed between two calls neither repeat nor skip
        a row on the next page.
      required:
        - data
        - next_cursor
      properties:
        data:
          type: array
          description: This page's items, in the list's order.
          items: {}
        next_cursor:
          type: string
          nullable: true
          description: Pass as `cursor` to fetch the next page; `null` on the last page.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          description: Structured error. Every error response uses this shape, so `code` can be read without
            first checking the type of `error`.
          required:
            - code
            - message
            - hint
          properties:
            code:
              type: string
              pattern: ^[A-Z][A-Z0-9_]*$
              description: Machine-readable error code, UPPER_SNAKE whether naturali or the runtime raises it.
              example: FORBIDDEN
            message:
              type: string
              description: Human-readable explanation.
              example: Your role in this project does not carry this action.
            hint:
              type: string
              description: What to do about it, naming the routes of this API to call. For people and agents; it
                may change, so branch on `code`.
              example: Use a credential whose scope includes this action, or ask a project `admin` or `owner` to
                act; the caller's role or key excludes it.
            meta:
              type: object
              additionalProperties: true
              description: Structured context, such as the `resource` and `limit` of a `PLAN_LIMIT_REACHED`.
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: Project public ID (proj_ prefix).
      schema:
        type: string
        example: proj_V1StGXR8Z5jdHi6B
    Limit:
      name: limit
      in: query
      required: false
      description: Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1 or not an
        integer it is `400`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      required: false
      description: The previous page's `next_cursor`; omit it for the first page. A cursor this list did
        not issue is `400`.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A naturali API key (nat_sk_…) or a session JWT.
    oauth2:
      type: oauth2
      description: "A connected app's OAuth access token, issued by this API's authorization server
        (discovery: /.well-known/oauth-authorization-server). Its one scope carries every operation,
        confined to the projects the user chose when approving the app."
      flows:
        authorizationCode:
          authorizationUrl: https://api.naturali.ai/authorize
          tokenUrl: https://api.naturali.ai/token
          refreshUrl: https://api.naturali.ai/token
          scopes:
            mcp:access: Every operation this API serves, on the projects the grant covers.
  responses:
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    TooManyRequests:
      description: "`QUOTA_EXCEEDED` — a `requests` quota on the calling API key or its project is spent
        for the window; `Retry-After` says when it reopens"
      headers:
        Retry-After:
          description: Seconds until the quota window admits a request again
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    PayloadTooLarge:
      description: "`REQUEST_REJECTED` — the request body is over the size the body parser accepts"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    AdmissionUnavailable:
      description: The deployment's admission service is asked about this write and did not answer —
        `ADMISSION_UNAVAILABLE`; the write did not happen
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    AdmissionRefused:
      description: The deployment's admission service refused this write — answered under the service's
        own `4xx` status, with its `code` (matching `^[A-Za-z_][A-Za-z0-9_]{0,63}$`, not necessarily
        an `ERROR_CODES` key), `message` and `meta`; the write did not happen. A status this
        operation also declares on its own is documented there
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    InternalError:
      description: Unexpected server error — `INTERNAL_ERROR`, with the raw message never forwarded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ProjectNotFound:
      description: The project does not exist or the caller is not a member of it (`RESOURCE_NOT_FOUND`).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
