openapi: 3.0.0
servers:
- description: Snowflake API
  url: https://org-account.snowflakecomputing.com
info:
  version: 0.0.1
  title: Cortex Analyst API
  description: The Snowflake Cortex Analyst API is a REST API that allows end user to chat with their data leveraging semantic models to generate SQL queries.
  contact:
    name: Snowflake, Inc.
    url: https://snowflake.com
    email: support@snowflake.com
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:
    TokenInfo:
      type: object
      properties:
        token:
          type: string
          example: example_value
        expiration_seconds:
          type: integer
          example: 10
    StatusUpdate:
      type: object
      properties:
        status:
          description: The latest status for processing the request
          type: string
          example: example_value
        status_message:
          description: A human readable description on the current request processing status
          type: string
          example: example_value
        request_id:
          type: string
          description: Unique request ID.
          example: '500123'
      required:
      - status
    SemanticModelSelection:
      type: object
      properties:
        index:
          description: The index of the selected semantic model
          type: integer
          format: int32
          example: 10
        identifier:
          $ref: '#/components/schemas/SemanticModelObject'
    MessageContentDelta:
      type: object
      properties:
        type:
          type: string
          example: example_value
        index:
          type: integer
          description: The index of the content array this delta object represents
          example: 10
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/MessageContentDeltaTextObject'
          sql: '#/components/schemas/MessageContentDeltaSqlObject'
          suggestions: '#/components/schemas/MessageContentDeltaSuggestionsObject'
          chart: '#/components/schemas/MessageContentChartObject'
    MessageContentDeltaTextObject:
      allOf:
      - $ref: '#/components/schemas/MessageContentDelta'
      - title: Text
        type: object
        description: The text content that is part of a message.
        properties:
          text_delta:
            type: string
            description: The delta of the text content, clients should concatenate all deltas for the same index
            example: To answer the question "What is the profit per store?" we must aggregate sales at the store level
        required:
        - text_delta
    MessageContentDeltaSqlObject:
      allOf:
      - $ref: '#/components/schemas/MessageContentDelta'
      - title: SQL
        type: object
        description: The SQL content that is part of a message.
        properties:
          statement_delta:
            type: string
            description: The delta of the sql statement, clients should concatenate all deltas for the same index
            example: SELECT store, SUM(profit) FROM sales GROUP BY store
          confidence:
            $ref: '#/components/schemas/Confidence'
        required:
        - statement_delta
    MessageContentDeltaSuggestionsObject:
      allOf:
      - $ref: '#/components/schemas/MessageContentDelta'
      - title: Suggested Questions
        type: object
        description: If SQL cannot be generated, a list of questions the semantic model can generate SQL for.
        properties:
          suggestions_delta:
            $ref: '#/components/schemas/SuggestionDelta'
        required:
        - suggestions_delta
    SuggestionDelta:
      type: object
      properties:
        index:
          type: integer
          description: The index of the suggestions array this delta object represents
          example: 10
        suggestion_delta:
          type: string
          description: The delta of a suggestion text, clients should concatenate all deltas for the same index
          example: example_value
    StreamingError:
      type: object
      properties:
        message:
          type: string
          description: A description of the error
          example: example_value
        code:
          type: string
          description: The Snowflake error code categorizing the error
          example: example_value
        request_id:
          type: string
          description: Unique request ID
          example: '500123'
    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
    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
    Warnings:
      type: object
      description: Represents a wrapper schema around Warning for streaming case
      properties:
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/Warning'
          example: []
    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...'
    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
    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'
    MessageContentTextObject:
      allOf:
      - $ref: '#/components/schemas/MessageContent'
      - title: Text
        type: object
        description: The text content that is part of a message.
        properties:
          text:
            type: string
            example: To answer the question "What is the profit per store?" we must aggregate sales at the store level
        required:
        - text
    MessageContentSqlObject:
      allOf:
      - $ref: '#/components/schemas/MessageContent'
      - title: SQL
        type: object
        description: The SQL content that is part of a message.
        properties:
          statement:
            type: string
            description: The executable SQL statement
            example: SELECT store, SUM(profit) FROM sales GROUP BY store
          confidence:
            $ref: '#/components/schemas/Confidence'
        required:
        - statement
    MessageContentSuggestionsObject:
      allOf:
      - $ref: '#/components/schemas/MessageContent'
      - title: Suggested Questions
        type: object
        description: If SQL cannot be generated, a list of questions the semantic model can generate SQL for.
        properties:
          suggestions:
            type: array
            items:
              type: string
              example: What is the lifetime revenue for the top 5 clients?
        required:
        - suggestions
    MessageContentResultsObject:
      allOf:
      - $ref: '#/components/schemas/MessageContent'
      - title: Results
        type: object
        description: Query ID of the executed query
        properties:
          query_id:
            type: string
        required:
        - query_id
    MessageContentChartObject:
      allOf:
      - $ref: '#/components/schemas/MessageContent'
      - title: Chart
        type: object
        description: The chart specification that is part of a message.
        properties:
          chart_spec:
            type: string
        required:
        - chart_spec
    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
    Confidence:
      type: object
      description: The verified query the response is based on
      properties:
        verified_query_used:
          $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
    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
    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: []
    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'
  securitySchemes:
    KeyPair:
      $ref: common.yaml#/components/securitySchemes/KeyPair
    ExternalOAuth:
      $ref: common.yaml#/components/securitySchemes/ExternalOAuth
    SnowflakeOAuth:
      $ref: common.yaml#/components/securitySchemes/SnowflakeOAuth
security:
- KeyPair: []
- ExternalOAuth: []
- SnowflakeOAuth: []