openapi: 3.0.0
info:
  version: 0.0.1
  title: Snowflake account cortex-analyst API
  description: The Snowflake Account API is a REST API that you can use to access, update, and perform certain actions on Account resource in Snowflake.
  contact:
    name: Snowflake, Inc.
    url: https://snowflake.com
    email: support@snowflake.com
servers:
- description: Snowflake Account API
  url: https://org-account.snowflakecomputing.com
security:
- KeyPair: []
- ExternalOAuth: []
- SnowflakeOAuth: []
tags:
- name: cortex-analyst
paths:
  /api/v2/cortex/analyst/feedback:
    post:
      operationId: sendFeedback
      tags:
      - cortex-analyst
      description: Send a user feedback of Cortex Analyst response
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendFeedbackRequest'
            examples:
              SendfeedbackRequestExample:
                summary: Default sendFeedback request
                x-microcks-default: true
                value:
                  request_id: '500123'
                  positive: true
                  feedback_message: example_value
      responses:
        '200':
          $ref: common.yaml#/components/responses/200SuccessResponse
        '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
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/cortex/analyst/message:
    post:
      operationId: sendMessage
      tags:
      - cortex-analyst
      summary: Send a Data Question to the Cortex Analyst
      description: Send a data question to the Cortex Analyst
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
            examples:
              SendmessageRequestExample:
                summary: Default sendMessage request
                x-microcks-default: true
                value:
                  semantic_model_file: example_value
                  semantic_model: example_value
                  semantic_view: example_value
                  semantic_models:
                  - semantic_model_file: example_value
                    semantic_view: example_value
                    inline_semantic_model: example_value
                  stream: true
                  operation: sql_generation
                  warehouse: example_value
                  messages:
                  - role: user
                    content: {}
                  source: example_value
                  experimental: example_value
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
              examples:
                Sendmessage200Example:
                  summary: Default sendMessage 200 response
                  x-microcks-default: true
                  value:
                    message:
                      role: user
                      content:
                      - {}
                    request_id: '500123'
                    warnings:
                    - message: example_value
                    semantic_model_selection:
                      index: 10
                    response_metadata: example_value
            text/event-stream:
              schema:
                type: string
              examples:
                Sendmessage200Example:
                  summary: Default sendMessage 200 response
                  x-microcks-default: true
                  value: example_value
        '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
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/cortex/analyst/verified-query-suggestions:
    post:
      operationId: generateVerifiedQuerySuggestions
      tags:
      - cortex-analyst
      summary: Generate Vq Suggestions for a Semantic Model
      description: Generate VQ suggestions for a semantic model
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateVerifiedQuerySuggestionsRequest'
            examples:
              GenerateverifiedquerysuggestionsRequestExample:
                summary: Default generateVerifiedQuerySuggestions request
                x-microcks-default: true
                value:
                  semantic_model:
                    semantic_model_file: example_value
                    semantic_view: example_value
                    inline_semantic_model: example_value
                  warehouse: example_value
                  experimental: example_value
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateVerifiedQuerySuggestionsResponse'
              examples:
                Generateverifiedquerysuggestions200Example:
                  summary: Default generateVerifiedQuerySuggestions 200 response
                  x-microcks-default: true
                  value:
                    request_id: '500123'
                    vq_suggestions:
                    - score: 42.5
                    warnings:
                    - message: example_value
        '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
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v2/cortex/analyst/token:
    get:
      operationId: getScopedToken
      summary: Internal Endpoint to Exchange a Cortex Analyst Oauth Token
      description: Internal endpoint to exchange a Cortex Analyst Oauth token
      tags:
      - cortex-analyst
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenInfo'
              examples:
                Getscopedtoken200Example:
                  summary: Default getScopedToken 200 response
                  x-microcks-default: true
                  value:
                    token: example_value
                    expiration_seconds: 10
        '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
        '429':
          $ref: common.yaml#/components/responses/429LimitExceeded
        '500':
          $ref: common.yaml#/components/responses/500InternalServerError
        '503':
          $ref: common.yaml#/components/responses/503ServiceUnavailable
        '504':
          $ref: common.yaml#/components/responses/504GatewayTimeout
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    MessageObject:
      type: object
      title: The message object
      description: Represents a message within a chat.
      properties:
        role:
          description: The entity that produced the message. One of `user` or `analyst`.
          type: string
          enum:
          - user
          - analyst
          example: user
        content:
          description: The content of the message in array of text or SQL.
          type: array
          items:
            $ref: '#/components/schemas/MessageContent'
          example: []
      required:
      - content
    SendMessageResponse:
      type: object
      description: The non-streaming response object for the sendMessage
      properties:
        message:
          $ref: '#/components/schemas/MessageObject'
        request_id:
          type: string
          description: Unique request ID
          example: '500123'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/Warning'
          example: []
        semantic_model_selection:
          $ref: '#/components/schemas/SemanticModelSelection'
        response_metadata:
          type: object
          additionalProperties: true
          example: example_value
      required:
      - message
    TokenInfo:
      type: object
      properties:
        token:
          type: string
          example: example_value
        expiration_seconds:
          type: integer
          example: 10
    SemanticModelSelection:
      type: object
      properties:
        index:
          description: The index of the selected semantic model
          type: integer
          format: int32
          example: 10
        identifier:
          $ref: '#/components/schemas/SemanticModelObject'
    SendFeedbackRequest:
      type: object
      description: The request object for sending user feedback on Cortex Analyst responses
      properties:
        request_id:
          type: string
          description: Request id associated with the feedback
          example: '500123'
        positive:
          type: boolean
          description: Whether the response was good (true) or bad (false)
          example: true
        feedback_message:
          type: string
          description: The text for the detailed feedback message
          example: example_value
      required:
      - request_id
      - positive
    SemanticModelObject:
      type: object
      title: the semantic model object
      description: Represents a semantic model object
      properties:
        semantic_model_file:
          description: The path to a file stored in a Snowflake Stage holding the semantic model yaml. Must be a fully qualified stage url
          type: string
          example: '@db.schema.stage/path/to/file.yaml'
        semantic_view:
          description: The name of the Snowflake native semantic model object
          type: string
          example: db.schema.semantic_view
        inline_semantic_model:
          description: A string containing the entire semantic model yaml
          type: string
          example: 'name: my_semantic_model\ntables:\n  - name: orders\n...'
    VerifiedQuerySuggestion:
      type: object
      description: A suggestion to add or remove or replace a Verified Query to a semantic model.
      properties:
        score:
          type: number
          description: Score of the suggestion, higher is better.
          format: float
          example: 42.5
        vq_to_add:
          $ref: '#/components/schemas/VerifiedQuery'
        vq_to_remove:
          $ref: '#/components/schemas/VerifiedQuery'
    VerifiedQuery:
      type: object
      description: VerifiedQuery represents a (question, sql) pair that has been manually verified (e.g. by an analyst) to be correct.
      properties:
        name:
          type: string
          description: A name for this verified query. Mainly used for display purposes.
          example: Example Title
        question:
          type: string
          description: The question being answered.
          example: example_value
        sql:
          type: string
          description: The correct SQL query for answering the question.
          example: example_value
        verified_at:
          type: integer
          format: int64
          description: Timestamp at which the query was last verified - measures in seconds since epoch, in UTC.
          example: '2026-01-15T10:30:00Z'
        verified_by:
          type: string
          description: Name of the person who verified this query.
          example: example_value
    MessageContent:
      type: object
      properties:
        type:
          type: string
          enum:
          - text
          - sql
          - suggestions
          - results
          - chart
          example: text
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/MessageContentTextObject'
          sql: '#/components/schemas/MessageContentSqlObject'
          suggestions: '#/components/schemas/MessageContentSuggestionsObject'
          results: '#/components/schemas/MessageContentResultsObject'
          chart: '#/components/schemas/MessageContentChartObject'
    GenerateVerifiedQuerySuggestionsRequest:
      type: object
      description: The request object for getting VQ suggestions
      properties:
        semantic_model:
          $ref: '#/components/schemas/SemanticModelObject'
        warehouse:
          type: string
          description: Warehouse name to use for processing suggestions.
          example: example_value
        experimental:
          type: string
          description: JSON serialized string of experimental API fields (undocumented).
          example: example_value
      required:
      - semantic_model
    GenerateVerifiedQuerySuggestionsResponse:
      type: object
      description: The non-streaming response object for the VQ Suggestions request
      properties:
        request_id:
          type: string
          description: Unique request ID
          example: '500123'
        vq_suggestions:
          type: array
          items:
            $ref: '#/components/schemas/VerifiedQuerySuggestion'
          example: []
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/Warning'
          example: []
    Warning:
      type: object
      title: The warning object
      description: Represents a warning within a chat.
      properties:
        message:
          type: string
          description: A human-readable message describing the warning
          example: example_value
    SendMessageRequest:
      type: object
      description: The request object for sendMessage requests
      properties:
        semantic_model_file:
          type: string
          description: The path to a file stored in a Snowflake Stage holding the semantic model yaml. Must be a fully qualified stage url
          example: '@db.schema.stage/path/to/file.yaml'
        semantic_model:
          type: string
          description: A string containing the entire semantic model yaml
          example: 'name: my_semantic_model\ntables:\n  - name: orders\n...'
        semantic_view:
          type: string
          description: The name of the Snowflake native semantic model object
          example: db.schema.semantic_view
        semantic_models:
          type: array
          description: A list of semantic model objects. If set, other semantic model properties are ignored
          items:
            $ref: '#/components/schemas/SemanticModelObject'
          example: []
        stream:
          type: boolean
          description: Whether to stream the response or not
          default: false
          example: true
        operation:
          type: string
          enum:
          - sql_generation
          - answer_generation
          description: Whether to response with SQL or natural language. One of 'sql_generation' or 'answer_generation'
          default: sql_generation
          example: sql_generation
        warehouse:
          type: string
          description: Warehouse name to use for result set handling. Only used when 'operation' is 'answer_generation'
          example: example_value
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageObject'
          example: []
        source:
          type: string
          description: an optional field to specify the source of the request. e.g "eval", "prod"
          example: example_value
        experimental:
          type: string
          description: JSON serialized string of experimental API fields (undocumented).
          example: example_value
      required:
      - messages
  securitySchemes:
    KeyPair:
      $ref: common.yaml#/components/securitySchemes/KeyPair
    ExternalOAuth:
      $ref: common.yaml#/components/securitySchemes/ExternalOAuth
    SnowflakeOAuth:
      $ref: common.yaml#/components/securitySchemes/SnowflakeOAuth