openapi: 3.0.2
info:
  title: Cortex Inference API
  description: OpenAPI 3.0 specification for the Cortex REST API
  version: 0.1.0
  contact:
    name: Snowflake, Inc.
    url: https://snowflake.com
    email: support@snowflake.com
paths:
  /api/v2/cortex/models:
    get:
      summary: Returns the LLMs available for the current session
      tags:
      - cortex-inference
      description: Returns the LLMs available for the current session
      operationId: getModels
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetModelsRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetModelsResponse'
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
  /api/v2/cortex/inference:complete:
    post:
      summary: Perform LLM text completion inference.
      tags:
      - cortex-inference
      description: Perform LLM text completion inference, similar to snowflake.cortex.Complete.
      operationId: cortexLLMInferenceComplete
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteRequest'
      responses:
        '200':
          description: OK
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/StreamingCompleteResponse'
        '400':
          $ref: common.yaml#/components/responses/400BadRequest
        '401':
          $ref: common.yaml#/components/responses/401Unauthorized
        '403':
          $ref: common.yaml#/components/responses/403Forbidden
        '404':
          $ref: common.yaml#/components/responses/404NotFound
        '405':
          $ref: common.yaml#/components/responses/405MethodNotAllowed
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
components:
  schemas:
    GetModelsRequest:
      type: object
      properties:
        models:
          type: array
          items:
            type: string
    GetModelsResponse:
      type: object
      properties:
        models:
          type: array
          items:
            type: string
    CompleteRequest:
      type: object
      description: LLM text completion request.
      properties:
        model:
          description: The model name. See documentation for possible values.
          type: string
        anthropic:
          type: object
          description: Anthropic specific configuration.
          nullable: true
          properties:
            thinking:
              type: object
              description: Thinking configuration.
              nullable: true
              properties:
                budget_tokens:
                  type: integer
                  description: The budget for thinking tokens.
                  example: 2048
              required:
              - budget_tokens
        openai:
          type: object
          description: OpenAI specific configuration.
          nullable: true
          properties:
            reasoning:
              type: object
              description: Reasoning configuration.
              nullable: true
              properties:
                effort:
                  type: string
                  description: The effort level for reasoning.
                  enum:
                  - low
                  - medium
                  - high
        messages:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                description: "Indicates the role of the message, one of 'system',\
                  \ 'user' or 'assistant'.\n\nRules:\n  - A 'user' message must be\
                  \ the last message in the list.\n  - If a 'system' message is specified,\
                  \ it must be the first message.\n  - If a 'assistant' message is\
                  \ specified, it must be immediately before a 'user' message in the\
                  \ list.\n\nMultiple 'assistant' and 'user' messages can be specified,\
                  \ but they must alternate in sequence.\n"
                default: user
              content:
                type: string
                description: The text completion prompt, e.g. 'What is a Large Language
                  Model?'.
              content_list:
                type: array
                description: Contents of text, toolUse, toolResults, or model-specific
                  output
                items:
                  discriminator:
                    propertyName: type
                    mapping:
                      text: '#/components/schemas/TextContent'
                      tool_result: '#/components/schemas/ToolResults'
                      tool_use: '#/components/schemas/ToolUse'
                      image: '#/components/schemas/Image'
                      anthropic: '#/components/schemas/AnthropicOutput'
                      openai: '#/components/schemas/OpenAIOutput'
          minItems: 1
        temperature:
          description: Temperature controls the amount of randomness used in response
            generation. A higher temperature corresponds to more randomness.
          type: number
          nullable: true
          minimum: 0.0
        top_p:
          description: Threshold probability for nucleus sampling. A higher top-p
            value increases the diversity of tokens that the model considers, while
            a lower value results in more predictable output.
          type: number
          default: 1.0
          minimum: 0.0
          maximum: 1.0
        max_tokens:
          description: The maximum number of output tokens to produce. The default
            value is model-dependent.
          type: integer
          default: 4096
          minimum: 0
        max_output_tokens:
          deprecated: true
          description: Deprecated in favor of "max_tokens", which has identical behavior.
          type: integer
          nullable: true
        response_format:
          type: object
          nullable: true
          description: An object describing response format config for structured-output
            mode.
          properties:
            type:
              type: string
              enum:
              - json
              description: The response format type (e.g., "json").
            schema:
              type: object
              description: The schema defining the structure of the response. If the
                `type` is "json", the `schema` field should contain a valid JSON schema.
        guardrails:
          $ref: '#/components/schemas/GuardrailsConfig'
        tools:
          description: List of tools to be used during tool calling
          type: array
          items:
            $ref: '#/components/schemas/Tool'
        tool_choice:
          $ref: '#/components/schemas/ToolChoice'
        provisioned_throughput_id:
          type: string
          description: The provisioned throughput ID to be used with the request.
          nullable: true
        sf-ml-xp-inflight-prompt-action:
          type: string
          description: Reserved
        sf-ml-xp-inflight-prompt-client-id:
          type: string
          description: Reserved
        sf-ml-xp-inflight-prompt-public-key:
          type: string
          description: Reserved
        stream:
          type: boolean
          default: true
          nullable: true
          description: Reserved
      required:
      - model
      - messages
    GuardrailsConfig:
      type: object
      title: GuardrailsConfig
      description: Guardrails configuration
      nullable: true
      properties:
        enabled:
          type: boolean
          description: Controls whether guardrails are enabled
        response_when_unsafe:
          type: string
          description: The response when the guardrails model marks the completion
            as unsafe
          example: Response filtered by Cortex Guard
    Image:
      type: object
      description: reserved
      properties:
        type:
          type: string
          enum:
          - image
        details:
          $ref: '#/components/schemas/ImageDetails'
        cache_control:
          $ref: '#/components/schemas/CacheControl'
    ImageDetails:
      type: object
      description: reserved
      properties:
        type:
          type: string
          description: Whether the image content is base64.
          enum:
          - base64
        content:
          type: string
          description: base64 encoded image.
        content_type:
          type: string
          description: Type of image.
          enum:
          - image/jpeg
          - image/jpg
          - image/png
          - image/gif
          - image/webp
          - image/heic
          - image/heif
        detail:
          type: string
          description: Level of detail to process the image. Only applicable for OpenAI
            models
          enum:
          - auto
          - low
          - high
    CacheControl:
      description: reserved
      type: object
      nullable: true
      properties:
        type:
          type: string
          description: "Identifies the type of cache control.\n\u201Cephemeral\u201D\
            \ is the only supported cache type currently, which has a 5-minute lifetime.\n"
          enum:
          - ephemeral
    ToolChoice:
      type: object
      nullable: true
      description: 'Configures how tools should be selected and used during the interaction.

        Controls whether tool use is automatic, required, or specific tools should
        be used.'
      required:
      - type
      properties:
        type:
          type: string
          description: 'Determines how tools are selected:

            * auto - Automatic tool selection (default)

            * required - Must use at least one tool

            * tool - Use specific named tools'
          example: required
        name:
          type: array
          description: List of specific tool names to use when type is 'tool'
          example:
          - Analyst1
          - Search1
          items:
            type: string
    TextContent:
      type: object
      description: 'Represents plain text content in a message.

        Used for simple text exchanges and natural language responses.'
      required:
      - type
      - text
      properties:
        type:
          type: string
          description: Identifies this as text content.
          enum:
          - text
        text:
          type: string
          description: The actual text content of the message.
          example: Based on the analysis, our top three customers by revenue are Acme
            Corp ($1.2M), TechGiant ($980K), and MegaCorp ($875K).
        cache_control:
          $ref: '#/components/schemas/CacheControl'
    StreamingTextContent:
      type: object
      description: 'Represents plain text content in a message.

        Used for simple text exchanges and natural language responses.'
      properties:
        type:
          type: string
          description: Identifies this as text content.
          enum:
          - text
        content:
          type: string
          description: The actual text content of the message.
          example: Based on the analysis, our top three customers by revenue are Acme
            Corp ($1.2M), TechGiant ($980K), and MegaCorp ($875K).
    JSONContent:
      type: object
      description: Represents structured JSON data in a message
      required:
      - type
      - json
      properties:
        type:
          type: string
          description: Identifies this as JSON content
          enum:
          - json
        json:
          type: object
          description: Arbitrary JSON data structure
          example:
            key: value
            numbers:
            - 1
            - 2
            - 3
          additionalProperties: true
    ToolResults:
      type: object
      description: 'Represents the results of a tool execution. Contains both the
        input parameters

        and output results from the tool execution.'
      required:
      - type
      - tool_results
      properties:
        type:
          type: string
          description: Identifies this as tool results content
          enum:
          - tool_results
        tool_results:
          type: object
          description: Container for tool execution results and metadata
          required:
          - tool_use_id
          - name
          - content
          properties:
            tool_use_id:
              type: string
              description: Unique identifier linking this result to its corresponding
                tool use request
              example: tool_123456
            name:
              type: string
              description: Name of the tool that was executed. Must match a tool name
                from the tools array
              example: Analyst1
            content:
              type: array
              description: Array of content elements produced by the tool execution
              example:
              - type: json
                json:
                  sql_query: SELECT * FROM sales LIMIT 10
              - type: text
                text: Query generated successfully
              items:
                discriminator:
                  propertyName: type
                  mapping:
                    json: '#/components/schemas/JSONContent'
                    text: '#/components/schemas/TextContent'
            status:
              type: string
              description: status indicators for the tool execution
              example: success
            result:
              type: object
              description: Additional result data in an arbitrary structure
              example:
                query_id: abc123
                row_count: 150
              additionalProperties: true
        cache_control:
          $ref: '#/components/schemas/CacheControl'
    ToolUse:
      type: object
      description: 'Represents a request to use a specific tool. Contains the tool
        identifier

        and input parameters for the execution.'
      required:
      - type
      - tool_use
      properties:
        type:
          type: string
          description: Identifies this as a tool use request
          enum:
          - tool_use
        tool_use:
          type: object
          description: Container for tool use request details
          required:
          - tool_use_id
          - name
          - input
          properties:
            tool_use_id:
              type: string
              description: Unique identifier for this tool use request
              example: tool_001
            name:
              type: string
              description: Name of the tool to execute. Must match a tool name from
                the tools array
              example: Analyst1
            input:
              type: object
              description: Input parameters for the tool execution
              example:
                query: What are the top selling products?
                limit: 5
              additionalProperties: true
        cache_control:
          $ref: '#/components/schemas/CacheControl'
    StreamingToolUse:
      type: object
      description: 'Represents a request to use a specific tool. Contains the tool
        identifier

        and input parameters for the execution.'
      properties:
        tool_use_id:
          type: string
          description: Unique identifier for this tool use request
        name:
          type: string
          description: Name of the tool to execute. Must match a tool name from the
            tools array
        input:
          type: string
    Tool:
      type: object
      description: 'Defines a tool that can be used by the agent.

        Tools provide specific capabilities like data analysis, search, or generic
        functions.'
      required:
      - tool_spec
      properties:
        tool_spec:
          type: object
          description: Specification of the tool's type, configuration, and input
            requirements
          required:
          - type
          - name
          properties:
            type:
              type: string
              description: 'The type of tool capability. Can be specialized types
                like

                ''cortex_analyst_text_to_sql'' or ''generic'' for general-purpose
                tools.'
              example: generic
            name:
              type: string
              description: 'Unique identifier for referencing this tool instance.

                Used to match with configuration in tool_resources.'
              example: get_weather
            description:
              type: string
              description: Description of the tool to be considered for tool use
            input_schema:
              type: object
              description: 'JSON Schema definition of the expected input parameters
                for this tool.

                Required for generic tools to specify their input requirements.'
              properties:
                type:
                  type: string
                  description: The type of the input schema object
                  example: object
                properties:
                  type: object
                  description: Definitions of each input parameter
                required:
                  type: array
                  description: List of required input parameter names
                  items:
                    type: string
              additionalProperties: true
              example:
                type: object
                properties:
                  location:
                    type: string
                    description: The city and state, e.g. San Francisco, CA
                required:
                - location
        cache_control:
          $ref: '#/components/schemas/CacheControl'
    OpenAIOutput:
      type: object
      description: OpenAI specific output.
      properties:
        reasoning:
          $ref: '#/components/schemas/OpenAIReasoning'
    OpenAIReasoning:
      type: object
      nullable: true
      description: OpenAI reasoning output.
      properties:
        summary:
          type: string
          description: 'Reasoning summary tokens generated during the model response.'
        encrypted_content:
          type: string
          description: 'The encrypted_content field is an opaque field and should
            not be interpreted or parsed.

            It should only be used for verifying that the reasoning blocks were generated
            by that specific model.'
      required:
      - summary
      - encrypted_content
    AnthropicOutput:
      type: object
      description: Anthropic specific output.
      properties:
        thinking:
          $ref: '#/components/schemas/AnthropicThinking'
    AnthropicThinking:
      type: object
      nullable: true
      description: Anthropic thinking output.
      properties:
        thinking:
          type: string
          description: 'Thinking tokens generated during the model response.

            This field can also be used in the follow-up requests to continue the
            conversation.'
        signature:
          type: string
          description: 'The signature field is an opaque field and should not be interpreted
            or parsed.

            It should only be used for verifying that the thinking blocks were generated
            by that specific model.'
      required:
      - thinking
      - signature
    StreamingOpenAIOutput:
      type: object
      description: OpenAI reasoning output.
      properties:
        reasoning:
          $ref: '#/components/schemas/StreamingOpenAIReasoning'
    StreamingOpenAIReasoning:
      type: object
      nullable: true
      description: OpenAI reasoning output.
      properties:
        summary:
          type: string
          description: 'Reasoning summary tokens generated during the model response.'
          nullable: true
        encrypted_content:
          type: string
          description: 'The encrypted_content field is an opaque field and should
            not be interpreted or parsed.

            It should only be used for verifying that the reasoning blocks were generated
            by that specific model.'
          nullable: true
    StreamingAnthropicOutput:
      type: object
      description: 'Represents the thinking response from model. Contains either the
        thinking tokens or signature.'
      properties:
        thinking:
          $ref: '#/components/schemas/StreamingAnthropicThinking'
    StreamingAnthropicThinking:
      type: object
      nullable: true
      description: Anthropic thinking output.
      properties:
        thinking:
          type: string
          description: 'Thinking tokens generated during the model response.

            This field can also be used in the follow-up requests to continue the
            conversation.'
          nullable: true
        signature:
          type: string
          description: 'The signature field is an opaque field and should not be interpreted
            or parsed.

            It should only be used for verifying that the thinking blocks were generated
            by that specific model.'
          nullable: true
    NonStreamingCompleteResponse:
      type: object
      description: Text-completion response for non-streaming request.
      properties:
        choices:
          type: array
          items:
            type: object
            properties:
              message:
                type: object
                properties:
                  content:
                    type: string
                    description: The text completion response.
                  content_list:
                    type: array
                    description: Contents of text and toolUse response.
                    items:
                      discriminator:
                        propertyName: type
                        mapping:
                          text: '#/components/schemas/TextContent'
                          tool_use: '#/components/schemas/ToolUse'
                          anthropic: '#/components/schemas/AnthropicOutput'
                          openai: '#/components/schemas/OpenAIOutput'
        finish_reason:
          type: string
          nullable: true
          description: The reason the request was finished.
          enum:
          - stop
          - content_filter
          - tool_calls
          - length
        usage:
          type: object
          title: Usage
          properties:
            prompt_tokens:
              type: integer
              description: Input token count.
            completion_tokens:
              type: integer
              description: Output token count.
            guard_tokens:
              type: integer
              description: Tokens used by cortex guard.
            total_tokens:
              type: integer
              description: Sum of all tokens.
            cache_read_input_tokens:
              type: integer
              description: reserved
              nullable: true
              minimum: 0
            cache_write_input_tokens:
              type: integer
              description: reserved
              nullable: true
              minimum: 0
    StreamingCompleteResponse:
      type: object
      description: Server-sent events for streaming text-completion updates.
      x-events:
        data:
          $ref: '#/components/schemas/StreamingCompleteResponseDataEvent'
    StreamingCompleteResponseDataEvent:
      type: object
      description: Streaming text-completion response event.
      properties:
        choices:
          type: array
          items:
            type: object
            properties:
              delta:
                $ref: '#/components/schemas/StreamingCompleteResponseDelta'
    StreamingCompleteResponseDelta:
      type: object
      required:
      - type
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/StreamingTextContent'
          tool_use: '#/components/schemas/StreamingToolUse'
          anthropic: '#/components/schemas/StreamingAnthropicOutput'
          openai: '#/components/schemas/StreamingOpenAIOutput'
  securitySchemes:
    KeyPair:
      $ref: common.yaml#/components/securitySchemes/KeyPair
    ExternalOAuth:
      $ref: common.yaml#/components/securitySchemes/ExternalOAuth
    SnowflakeOAuth:
      $ref: common.yaml#/components/securitySchemes/SnowflakeOAuth
    ProgrammaticAccessToken:
      $ref: common.yaml#/components/securitySchemes/ProgrammaticAccessToken
security:
- KeyPair: []
- ExternalOAuth: []
- SnowflakeOAuth: []
- ProgrammaticAccessToken: []