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

# Runtime Chat Completions

> Run an OpenAI-compatible chat completion using an injected runtime capability or a gateway-scoped key.



## OpenAPI

````yaml /openapi.json post /v1/runtime/ai/{gatewayName}/chat/completions
openapi: 3.1.0
info:
  title: Korve API
  version: 0.1.0
  description: >-
    Typed control plane for deploying applications and explicitly provisioning
    their managed infrastructure.
servers:
  - url: https://api.korve.dev
security: []
paths:
  /v1/runtime/ai/{gatewayName}/chat/completions:
    post:
      tags:
        - aiGateways
      summary: Runtime Chat Completions
      description: >-
        Run an OpenAI-compatible chat completion using an injected runtime
        capability or a gateway-scoped key.
      operationId: aiGateways.runtimeChatCompletions
      parameters:
        - name: gatewayName
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        x-korve-max-bytes: 1048576
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  type: string
                  enum:
                    - korve/fast
                    - korve/balanced
                    - korve/reasoning
                messages:
                  type: array
                  minItems: 1
                  maxItems: 256
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        enum:
                          - system
                          - user
                          - assistant
                          - tool
                      content:
                        type: string
                        maxLength: 262144
                    required:
                      - role
                      - content
                    additionalProperties: false
                stream:
                  type: boolean
                max_tokens:
                  type: integer
                  minimum: 1
                  maximum: 65536
                temperature:
                  type: number
                  minimum: 0
                  maximum: 2
              required:
                - model
                - messages
              additionalProperties: false
      responses:
        '200':
          description: >-
            OpenAI-compatible JSON response when stream is false;
            text/event-stream chunks use the same opaque Korve completion id
            when stream is true.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    pattern: ^kvc_[a-f0-9]{32}$
                  object:
                    type: string
                    enum:
                      - chat.completion
                  created:
                    type: integer
                    minimum: 0
                  model:
                    type: string
                    enum:
                      - korve/fast
                      - korve/balanced
                      - korve/reasoning
                  choices:
                    type: array
                    minItems: 1
                    maxItems: 1
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                          enum:
                            - 0
                        message:
                          type: object
                          properties:
                            role:
                              type: string
                              enum:
                                - assistant
                            content:
                              type: string
                          required:
                            - role
                            - content
                          additionalProperties: false
                        finish_reason:
                          type: string
                          enum:
                            - stop
                            - length
                            - tool_calls
                      required:
                        - index
                        - message
                        - finish_reason
                      additionalProperties: false
                  usage:
                    type: object
                    properties:
                      prompt_tokens:
                        type: integer
                        minimum: 0
                      completion_tokens:
                        type: integer
                        minimum: 0
                      total_tokens:
                        type: integer
                        minimum: 0
                    required:
                      - prompt_tokens
                      - completion_tokens
                      - total_tokens
                    additionalProperties: false
                required:
                  - id
                  - object
                  - created
                  - model
                  - choices
                  - usage
                additionalProperties: false
        '403':
          description: The requested model is not allowed.
        '404':
          description: No such gateway in the runtime environment.
        '429':
          description: The monthly gateway budget is exhausted.
        '503':
          description: Model inference is temporarily unavailable.
      security:
        - appService: []
components:
  securitySchemes:
    appService:
      type: http
      scheme: bearer
      bearerFormat: korve_app_service

````