openapi: 3.0.1
info:
  title: AI Gateway API
  version: '1.0'
  description: 'API for registering and managing LLM models in LangDB'
servers:
  - url: https://api.xxx.langdb.ai
    description: 'Enterprise API server'

paths:
  /admin/models:
    post:
      tags:
        - Models
        - Admin
      summary: 'Create a new model'
      description: 'Register and configure a new LLM under your LangDB project'
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/XAdminKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModelCreateRequest'
      responses:
        '200':
          description: 'Created'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'

  /projects/{project_id}/custom_prices:
    post:
      tags:
        - Models
        - Pricing
      summary: 'Set custom prices for imported models'
      description: 'Set custom pricing for models imported from providers like Bedrock, Azure, Vertex that do not have built-in pricing'
      security:
        - bearerAuth: []
      parameters:
        - name: project_id
          in: path
          required: true
          description: 'UUID of the project'
          schema:
            type: string
            format: uuid
          example: 25a0b7d9-86cf-448d-8395-66e9073d876f
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomPricesRequest'
      responses:
        '200':
          description: 'Custom prices set successfully'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomPricesResponse'
        '400':
          description: 'Bad request - invalid pricing data'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'Unauthorized - invalid or missing authentication'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'Project not found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  parameters:
    XAdminKey:
      name: X-Admin-Key
      in: header
      description: "LangDB Admin key"
      required: true
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    ModelCreateRequest:
      type: object
      required:
        - model_name
        - description
        - provider_info_id
        - project_id
        - model_type
        - owner_name
        - priority
      properties:
        model_name:
          type: string
          description: 'Display name for the model'
          example: my-model
        description:
          type: string
          description: 'Detailed description of the model’s capabilities and use cases'
          example: 'A custom completions model for text and image inputs'
        provider_info_id:
          type: string
          format: uuid
          description: 'UUID of the provider that offers this model'
          example: e2e9129b-6661-4eeb-80a2-0c86964974c9
        project_id:
          type: string
          description: 'UUID of the project to which this model belongs'
          example: 55f4a12b-74c8-4294-8e4b-537f13fc3861
        public:
          type: boolean
          description: 'Whether the model is publicly accessible'
          example: false
        request_response_mapping:
          type: string
          description: 'Mapping strategy, e.g., openai-compatible'
          example: openai-compatible
        model_type:
          type: string
          description: 'Type of model, e.g., completions'
          example: completions
        input_token_price:
          type: number
          format: float
          nullable: true
          description: 'Price per input token'
          example: 0.00001
        output_token_price:
          type: number
          format: float
          nullable: true
          description: 'Price per output token'
          example: 0.00003
        context_size:
          type: integer
          nullable: true
          description: 'Maximum context window size in tokens'
          example: 128000
        capabilities:
          type: array
          items:
            type: string
          description: 'Model capabilities, e.g., tools'
          example:
            - tools
        input_types:
          type: array
          items:
            type: string
          description: 'Supported input formats'
          example:
            - text
            - image
        output_types:
          type: array
          items:
            type: string
          description: 'Supported output formats'
          example:
            - text
            - image
        tags:
          type: array
          items:
            type: string
          description: 'Classification tags for the model'
          example: []
        type_prices:
          type: object
          nullable: true
          additionalProperties:
            type: number
          description: 'Map of usage-type to price (image-generation models)'
          example:
            text_generation: 0.00002
        mp_price:
          type: number
          format: float
          nullable: true
          description: 'Price per megapixel (image-generation models)'
          example: null
        owner_name:
          type: string
          description: "Name of the model's owner or creator"
          example: openai
        priority:
          type: integer
          description: 'Priority level for the model in listings'
          example: 0
        model_name_in_provider:
          type: string
          description: "Identifier of the model in the provider's system"
          example: my-model-v1.2
        parameters:
          type: object
          description: 'Additional configuration parameters as JSON'
          additionalProperties:
            $ref: '#/components/schemas/ParameterDefinition'
          example:
            top_k:
              default: 0
              description: 'Limits the token sampling to only the top K tokens.'
              min: 0
              required: false
              step: 1
              type: int
            top_p:
              default: 1
              description: 'Nucleus sampling alternative.'
              max: 1
              min: 0
              required: false
              step: 0.05
              type: float

    Model:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: 'Unique identifier for the model'
        model_name:
          type: string
        description:
          type: string
        provider_info_id:
          type: string
          format: uuid
        model_type:
          type: string
        input_token_price:
          type: string
        output_token_price:
          type: string
        context_size:
          type: integer
        capabilities:
          type: array
          items:
            type: string
        input_types:
          type: array
          items:
            type: string
        output_types:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        type_prices:
          type: object
          nullable: true
          additionalProperties:
            type: number
        mp_price:
          type: number
          format: float
          nullable: true
        model_name_in_provider:
          type: string
        owner_name:
          type: string
        priority:
          type: integer
        parameters:
          type: object
          example:
           top_k:
            default: 0
            description: 'Limits the token sampling to only the top K tokens. A value of 0 disables this setting, allowing the model to consider all tokens.'
            min: 0
            required: false
            step: 1
            type: int
          top_p:
            default: 1
            description: 'An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.'
            max: 1
            min: 0
            required: false
            step: 0.05
            type: float
      example:
        id: 55f4a12b-74c8-4294-8e4b-537f13fc3861
        model_name: my-model
        description: 'A custom completions model for text and image inputs'
        provider_info_id: e2e9129b-6661-4eeb-80a2-0c86964974c9
        model_type: completions
        input_token_price: '0.00001'
        output_token_price: '0.00003'
        context_size: 128000
        capabilities:
          - tools
        input_types:
          - text
          - image
        output_types:
          - text
          - image
        tags: []
        type_prices: null
        mp_price: null
        model_name_in_provider: my-model-v1.2
        owner_name: openai
        priority: 0
        parameters:
          top_k:
            default: 0
            description: 'Limits the token sampling to only the top K tokens. A value of 0 disables this setting, allowing the model to consider all tokens.'
            min: 0
            required: false
            step: 1
            type: int
          top_p:
            default: 1
            description: 'An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.'
            max: 1
            min: 0
            required: false
            step: 0.05
            type: float

    ParameterDefinition:
      type: object
      properties:
        default:
          type: number
        description:
          type: string
        min:
          type: number
        max:
          type: number
          nullable: true
        step:
          type: number
        type:
          type: string
        required:
          type: boolean

    CustomPricesRequest:
      type: object
      description: 'Request body for setting custom prices on imported models'
      additionalProperties:
        $ref: '#/components/schemas/ModelPricing'
      example:
        "bedrock/twelvelabs.pegasus-1-2-v1:0":
          per_input_token: 1.23
          per_output_token: 2.12

    ModelPricing:
      type: object
      required:
        - per_input_token
        - per_output_token
      properties:
        per_input_token:
          type: number
          format: float
          description: 'Price per input token'
          example: 1.23
        per_output_token:
          type: number
          format: float
          description: 'Price per output token'
          example: 2.12

    CustomPricesResponse:
      type: object
      properties:
        success:
          type: boolean
          description: 'Whether the custom prices were set successfully'
          example: true
        message:
          type: string
          description: 'Success message'
          example: 'Custom prices updated successfully'
        updated_models:
          type: array
          items:
            type: string
          description: 'List of model identifiers that were updated'
          example:
            - "bedrock/twelvelabs.pegasus-1-2-v1:0"

    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string