Cortex Analyst API
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.
OpenAPI Specification
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: []