openapi: 3.0.1 info: title: Cortex Search REST API description: OpenAPI 3.0 specification for the Cortex Search REST API version: 0.1.0 contact: name: Snowflake, Inc. url: https://snowflake.com email: support@snowflake.com paths: /api/v2/databases/{database}/schemas/{schema}/cortex-search-services: get: operationId: listCortexSearchServices summary: List Cortex Search Services description: Lists the cortex search services under the database and schema. tags: - cortex-search-service parameters: - $ref: common.yaml#/components/parameters/database - $ref: common.yaml#/components/parameters/schema - $ref: common.yaml#/components/parameters/like - $ref: common.yaml#/components/parameters/fromName - $ref: common.yaml#/components/parameters/showLimit responses: '200': description: successful headers: X-Snowflake-Request-ID: $ref: common.yaml#/components/headers/X-Snowflake-Request-ID Link: $ref: common.yaml#/components/headers/Link content: application/json: schema: type: array items: $ref: '#/components/schemas/CortexSearchService' examples: Listcortexsearchservices200Example: summary: Default listCortexSearchServices 200 response x-microcks-default: true value: - name: Example Title search_column: example_value columns: - example_value attribute_columns: - example_value target_lag: {} warehouse: example_value definition: example_value comment: example_value created_on: '2026-01-15T10:30:00Z' database_name: example_value schema_name: example_value source_data_num_rows: 10 data_timestamp: '2026-01-15T10:30:00Z' indexing_state: ACTIVE serving_state: ACTIVE indexing_error: example_value serving_data_bytes: 10 '202': $ref: common.yaml#/components/responses/202SuccessAcceptedResponse '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 '408': $ref: common.yaml#/components/responses/408RequestTimeout '409': $ref: common.yaml#/components/responses/409Conflict '410': $ref: common.yaml#/components/responses/410Gone '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 post: operationId: createCortexSearchService summary: Create a Cortex Search Service description: Create a cortex search service, with standard create modifiers as query parameters. See the Cortex Search Service component definition for what is required to be provided in the request body. tags: - cortex-search-service parameters: - $ref: common.yaml#/components/parameters/database - $ref: common.yaml#/components/parameters/schema - $ref: common.yaml#/components/parameters/createMode requestBody: required: true content: application/json: schema: type: object allOf: - $ref: '#/components/schemas/CortexSearchService' - type: object - required: - name - search_column - target_lag - warehouse - definition examples: CreatecortexsearchserviceRequestExample: summary: Default createCortexSearchService request x-microcks-default: true value: {} responses: '200': $ref: common.yaml#/components/responses/200SuccessResponse '202': $ref: common.yaml#/components/responses/202SuccessAcceptedResponse '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 '408': $ref: common.yaml#/components/responses/408RequestTimeout '409': $ref: common.yaml#/components/responses/409Conflict '410': $ref: common.yaml#/components/responses/410Gone '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/databases/{database}/schemas/{schema}/cortex-search-services/{name}: get: operationId: fetchCortexSearchService summary: Fetch a Cortex Search Service. description: Fetch a Cortex Search Service. tags: - cortex-search-service parameters: - $ref: common.yaml#/components/parameters/database - $ref: common.yaml#/components/parameters/schema - $ref: common.yaml#/components/parameters/name responses: '200': description: successful headers: X-Snowflake-Request-ID: $ref: common.yaml#/components/headers/X-Snowflake-Request-ID Link: $ref: common.yaml#/components/headers/Link content: application/json: schema: $ref: '#/components/schemas/CortexSearchService' examples: Fetchcortexsearchservice200Example: summary: Default fetchCortexSearchService 200 response x-microcks-default: true value: name: Example Title search_column: example_value columns: - example_value attribute_columns: - example_value target_lag: {} warehouse: example_value definition: example_value comment: example_value created_on: '2026-01-15T10:30:00Z' database_name: example_value schema_name: example_value source_data_num_rows: 10 data_timestamp: '2026-01-15T10:30:00Z' indexing_state: ACTIVE serving_state: ACTIVE indexing_error: example_value serving_data_bytes: 10 '202': $ref: common.yaml#/components/responses/202SuccessAcceptedResponse '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 '408': $ref: common.yaml#/components/responses/408RequestTimeout '409': $ref: common.yaml#/components/responses/409Conflict '410': $ref: common.yaml#/components/responses/410Gone '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 delete: operationId: deleteCortexSearchService summary: Delete a Cortex Search Service description: Delete a cortex search service with the given name. If ifExists is used, the operation will succeed even if the object does not exist. Otherwise, there will be a failure if the drop is unsuccessful. tags: - cortex search service parameters: - $ref: common.yaml#/components/parameters/database - $ref: common.yaml#/components/parameters/schema - $ref: common.yaml#/components/parameters/name - $ref: common.yaml#/components/parameters/ifExists responses: '200': $ref: common.yaml#/components/responses/200SuccessResponse '202': $ref: common.yaml#/components/responses/202SuccessAcceptedResponse '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 '408': $ref: common.yaml#/components/responses/408RequestTimeout '409': $ref: common.yaml#/components/responses/409Conflict '410': $ref: common.yaml#/components/responses/410Gone '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/databases/{database}/schemas/{schema}/cortex-search-services/{service_name}:query: post: operationId: queryCortexSearchService summary: Query a Cortex Search Service. description: Query a Cortex Search Service to get search results. tags: - cortex-search-service parameters: - $ref: common.yaml#/components/parameters/database - $ref: common.yaml#/components/parameters/schema - in: path name: service_name required: true schema: type: string description: The name of the Cortex Search Service. example: example_value requestBody: content: application/json: schema: $ref: '#/components/schemas/QueryRequest' examples: QuerycortexsearchserviceRequestExample: summary: Default queryCortexSearchService request x-microcks-default: true value: query: example_value multi_index_query: example_value columns: - example_value filter: example_value limit: 10 scoring_config: {} experimental: example_value responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/QueryResponse' examples: Querycortexsearchservice200Example: summary: Default queryCortexSearchService 200 response x-microcks-default: true value: results: - {} request_id: '500123' '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 '408': $ref: common.yaml#/components/responses/408RequestTimeout '409': $ref: common.yaml#/components/responses/409Conflict '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/databases/{database}/schemas/{schema}/cortex-search-services/{name}:suspend: post: operationId: suspendCortexSearchService summary: Suspend a Cortex Search Service. description: Suspends one or both of the indexing or serving targets of a cortex search service. tags: - cortex-search-service parameters: - $ref: common.yaml#/components/parameters/database - $ref: common.yaml#/components/parameters/schema - $ref: common.yaml#/components/parameters/name - $ref: common.yaml#/components/parameters/ifExists - $ref: '#/components/parameters/suspendResumeTarget' responses: '200': $ref: common.yaml#/components/responses/200SuccessResponse '202': $ref: common.yaml#/components/responses/202SuccessAcceptedResponse '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 '408': $ref: common.yaml#/components/responses/408RequestTimeout '409': $ref: common.yaml#/components/responses/409Conflict '410': $ref: common.yaml#/components/responses/410Gone '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/databases/{database}/schemas/{schema}/cortex-search-services/{name}:resume: post: operationId: resumeCortexSearchService description: Resume the cortex search service summary: Resume the Cortex Search Service tags: - cortex-search-service parameters: - $ref: common.yaml#/components/parameters/database - $ref: common.yaml#/components/parameters/schema - $ref: common.yaml#/components/parameters/name - $ref: common.yaml#/components/parameters/ifExists - $ref: '#/components/parameters/suspendResumeTarget' responses: '200': $ref: common.yaml#/components/responses/200SuccessResponse '202': $ref: common.yaml#/components/responses/202SuccessAcceptedResponse '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 '408': $ref: common.yaml#/components/responses/408RequestTimeout '409': $ref: common.yaml#/components/responses/409Conflict '410': $ref: common.yaml#/components/responses/410Gone '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: parameters: suspendResumeTarget: name: target description: Query parameter that identifies the target to which suspension or resumption of the cortex search service should be applied. in: query schema: type: string enum: - indexing - INDEXING - serving - SERVING example: indexing schemas: QueryRequest: type: object description: A search query and additional parameters for search. properties: query: description: Unstructured text query. Exactly one of 'query' or 'multi_index_query' must be specified. type: string example: example_value multi_index_query: description: A search query expressed as a collection of multiple column-level queries. Exactly one of 'query' or 'multi_index_query' must be specified. A column/index can be queried with multiple queries. type: object additionalProperties: true example: example_value columns: description: List of columns to return. type: array items: type: string example: [] filter: description: Filter query. type: object example: example_value limit: description: Max number of results to return. type: integer default: 10 example: 10 scoring_config: $ref: '#/components/schemas/ScoringConfig' experimental: description: reserved type: object additionalProperties: true example: example_value required: - columns ScoringConfig: type: object description: reserved properties: functions: $ref: '#/components/schemas/Functions' reranker: $ref: '#/components/schemas/Reranker' weights: $ref: '#/components/schemas/Weights' Weights: type: object description: Weights to apply to each scoring component. properties: texts: description: Weight to apply to all text-specific columns. type: number example: 0.5 vectors: description: Weight to apply to all vector-specific columns. type: number example: 0.5 reranker: description: Weight to apply to reranker-specific scoring component. type: number example: 0.5 Functions: type: object description: Functions to apply for scoring this request. properties: numeric_boosts: type: array items: $ref: '#/components/schemas/NumericBoost' example: [] time_decays: type: array items: $ref: '#/components/schemas/TimeDecay' example: [] text_boosts: type: array items: $ref: '#/components/schemas/TextBoost' example: [] vector_boosts: type: array items: $ref: '#/components/schemas/VectorBoost' example: [] query_similarity_boosts: type: array items: $ref: '#/components/schemas/QuerySimilarityBoost' example: [] Column: type: string description: Column to apply this function to. NumericBoost: type: object properties: column: $ref: '#/components/schemas/Column' weight: type: number description: Weight to apply for boosting this numerical column. It will be normalized across all scored columns specified in the scoring config so that all weights sum to 1. If a weight is not provided, the weight defaults to 1 pre-normalization. example: 0.5 required: - column TimeDecay: type: object properties: column: $ref: '#/components/schemas/Column' weight: type: number description: Weight to apply for decaying this timestamp column. Normalized across all scored columns in the scoring config so that all weights sum to 1. If a weight is not provided, the weight defaults to 1 pre-normalization. example: 0.5 limit_hours: type: number description: Optional limit in hours after which the decay does not apply. example: 24 now: type: string format: date-time description: Optional reference timestamp to calculate decay from. example: '2022-01-01T00:00:00Z' required: - column TextBoost: type: object properties: column: $ref: '#/components/schemas/Column' weight: description: Weight to apply for boosting this text column. type: number example: 0.5 VectorBoost: type: object properties: column: $ref: '#/components/schemas/Column' weight: description: Weight to apply for boosting this vector column. type: number example: 0.5 QuerySimilarityBoost: type: object properties: cortex_search_service: description: Fully-qualified name of a Cortex Search Service through which to find similar previous queries. type: string example: MY_DB.MY_SCHEMA.MY_SEARCH_SERVICE previous_query_column: description: Name of a TEXT column indexed in the specified previous queries search service that contains the previous query strings. type: string example: example_value documents_column: description: Name of an ARRAY column indexed in the specified previous queries search service that contains a list of documents that matched the corresponding previous query. Each document is represented as an OBJECT mapping all primary key columns to their corresponding values. type: string example: example_value Reranker: type: string description: Model to use for the reranker, or "none" if the reranker should be turned off. If excluded or null, the default reranker is used. example: none ColumnQuery: description: Query specification of a given column. Exactly one of 'text' or 'vector' must be specified. type: object properties: text: description: Unstructured text query for querying a text index. type: string example: example_value vector: description: Query embedding vector. Must be computed using the same model as used for embedding the column being queried. type: array items: type: number format: float example: [] QueryResponse: type: object description: Search results. properties: results: type: array description: List of result rows. items: type: object additionalProperties: true description: Map of column names to bytes. example: [] request_id: type: string description: ID of the request. example: '500123' required: - results - request_id CortexSearchService: type: object description: A Snowflake cortex search service object. properties: name: type: string description: Specifies the name for the cortex search service, must be unique for the schema in which the cortex search service is created example: Example Title search_column: type: string description: Specifies the name of the search column for the cortex search service. example: example_value columns: type: array items: type: string description: Specifies all columns included in the cortex search service and that can be returned in search queries. example: [] attribute_columns: type: array items: type: string description: Specifies the attribute columns, which can be referenced in filters in search queries to the cortex search service. example: [] target_lag: $ref: common.yaml#/components/schemas/TargetLag description: Specifies the schedule for periodically refreshing the cortex search service. warehouse: type: string description: Specifies the name of the warehouse that provides the compute resources for refreshing the cortex search service example: test_wh definition: type: string description: Specifies the definition (source query) used to create the cortex search service example: SELECT col1, col2 FROM foo comment: type: string description: Specifies a comment for the cortex search service example: example_value created_on: type: string format: date-time readOnly: true description: Date and time when the cortex search service was created. example: '2026-01-15T10:30:00Z' database_name: type: string readOnly: true description: Database in which the cortex search service is stored example: example_value schema_name: type: string readOnly: true description: Schema in which the cortex search service is stored example: example_value source_data_num_rows: type: integer format: int64 readOnly: true description: Number of rows in the materialized source data feeding into the cortex search service. example: 10 data_timestamp: type: string format: date-time readOnly: true description: Date and time as of which data existent in base tables is now serving. example: '2026-01-15T10:30:00Z' indexing_state: $ref: '#/components/schemas/SchedulingState' description: Current state of the indexing pipeline for the cortex search service; one of 'SUSPENDED' or 'ACTIVE'. serving_state: $ref: '#/components/schemas/SchedulingState' description: Whether the cortex search service is currently actively serving; one of 'SUSPENDED' or 'ACTIVE'. indexing_error: type: string readOnly: true description: Error encountered during the latest indexing pipeline of the cortex search service, if any. example: example_value serving_data_bytes: type: integer format: int64 readOnly: true description: Size of the serving index, in bytes. example: 10 SchedulingState: type: string enum: - ACTIVE - SUSPENDED - INITIALIZING 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: []