From 1131c70d141c039578699c1601064069d02753ca Mon Sep 17 00:00:00 2001 From: Fanis Tharropoulos Date: Thu, 21 Aug 2025 17:35:48 +0300 Subject: [PATCH 1/6] fix: make POST response on conversation model creation a 201 --- openapi.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yml b/openapi.yml index a6a03be..7302ea6 100644 --- a/openapi.yml +++ b/openapi.yml @@ -979,7 +979,7 @@ paths: $ref: '#/components/schemas/ConversationModelCreateSchema' required: true responses: - '200': + '201': content: application/json: schema: From 6b0fdc8f08c43316991984576d29906c6a36bcb3 Mon Sep 17 00:00:00 2001 From: Fanis Tharropoulos Date: Thu, 21 Aug 2025 17:36:16 +0300 Subject: [PATCH 2/6] feat: update version to v30.0 --- openapi.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yml b/openapi.yml index 7302ea6..debdae6 100644 --- a/openapi.yml +++ b/openapi.yml @@ -2,7 +2,7 @@ openapi: 3.0.3 info: title: Typesense API description: "An open source search engine for building delightful search experiences." - version: '28.0' + version: '30.0' license: name: GPL-3.0 url: https://opensource.org/licenses/GPL-3.0 From c3e7141eaa6a8f9ef7355f8bf01fc71d0b7a2789 Mon Sep 17 00:00:00 2001 From: Fanis Tharropoulos Date: Fri, 22 Aug 2025 15:11:10 +0300 Subject: [PATCH 3/6] feat(v30): add synonym sets api --- openapi.yml | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) diff --git a/openapi.yml b/openapi.yml index debdae6..fb4fbe0 100644 --- a/openapi.yml +++ b/openapi.yml @@ -713,6 +713,110 @@ paths: schema: $ref: "#/components/schemas/ApiResponse" + /synonym_sets: + get: + tags: + - synonyms + summary: List all synonym sets + description: Retrieve all synonym sets + operationId: retrieveSynonymSets + responses: + "200": + description: List of all synonym sets + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/SynonymSetSchema" + + /synonym_sets/{synonymSetName}: + get: + tags: + - synonyms + summary: Retrieve a synonym set + description: Retrieve a specific synonym set by its name + operationId: retrieveSynonymSet + parameters: + - name: synonymSetName + in: path + description: The name of the synonym set to retrieve + required: true + schema: + type: string + responses: + "200": + description: Synonym set fetched + content: + application/json: + schema: + $ref: "#/components/schemas/SynonymSetRetrieveSchema" + "404": + description: Synonym set not found + content: + application/json: + schema: + $ref: "#/components/schemas/ApiResponse" + put: + tags: + - synonyms + summary: Create or update a synonym set + description: Create or update a synonym set with the given name + operationId: upsertSynonymSet + parameters: + - name: synonymSetName + in: path + description: The name of the synonym set to create/update + required: true + schema: + type: string + requestBody: + description: The synonym set to be created/updated + content: + application/json: + schema: + $ref: "#/components/schemas/SynonymSetCreateSchema" + required: true + responses: + "200": + description: Synonym set successfully created/updated + content: + application/json: + schema: + $ref: "#/components/schemas/SynonymSetSchema" + "400": + description: Bad request, see error message for details + content: + application/json: + schema: + $ref: "#/components/schemas/ApiResponse" + delete: + tags: + - synonyms + summary: Delete a synonym set + description: Delete a specific synonym set by its name + operationId: deleteSynonymSet + parameters: + - name: synonymSetName + in: path + description: The name of the synonym set to delete + required: true + schema: + type: string + responses: + "200": + description: Synonym set successfully deleted + content: + application/json: + schema: + $ref: "#/components/schemas/SynonymSetDeleteSchema" + "404": + description: Synonym set not found + content: + application/json: + schema: + $ref: "#/components/schemas/ApiResponse" + /collections/{collectionName}/documents/export: get: tags: @@ -2079,6 +2183,12 @@ components: minLength: 1 maxLength: 1 default: [] + synonym_sets: + type: array + description: List of synonym set names to associate with this collection + items: + type: string + example: "synonym_set_1" enable_nested_fields: type: boolean description: @@ -2123,6 +2233,12 @@ components: facet: true items: $ref: "#/components/schemas/Field" + synonym_sets: + type: array + description: List of synonym set names to associate with this collection + items: + type: string + example: "synonym_set_1" metadata: type: object description: > @@ -2997,6 +3113,11 @@ components: a snippet of relevant portion. Default: 30 type: integer + synonym_sets: + type: string + description: List of synonym set names to associate with this search query + example: "synonym_set_1,synonym_set_2" + drop_tokens_threshold: description: > If the number of results found for a specific query is less than @@ -4061,6 +4182,77 @@ components: type: string description: ID of the deleted NL search model + SynonymItemSchema: + type: object + required: + - id + - synonyms + properties: + id: + type: string + description: Unique identifier for the synonym item + synonyms: + type: array + description: Array of words that should be considered as synonyms + items: + type: string + root: + type: string + description: For 1-way synonyms, indicates the root word that words in the synonyms parameter map to + locale: + type: string + description: Locale for the synonym, leave blank to use the standard tokenizer + symbols_to_index: + type: array + description: By default, special characters are dropped from synonyms. Use this attribute to specify which special characters should be indexed as is + items: + type: string + + SynonymSetCreateSchema: + type: object + required: + - items + properties: + items: + type: array + description: Array of synonym items + items: + $ref: "#/components/schemas/SynonymItemSchema" + + SynonymSetSchema: + allOf: + - $ref: "#/components/schemas/SynonymSetCreateSchema" + - type: object + required: + - name + properties: + name: + type: string + description: Name of the synonym set + + SynonymSetsRetrieveSchema: + type: object + required: + - synonym_sets + properties: + synonym_sets: + type: array + description: Array of synonym sets + items: + $ref: "#/components/schemas/SynonymSetSchema" + + SynonymSetRetrieveSchema: + $ref: "#/components/schemas/SynonymSetCreateSchema" + + SynonymSetDeleteSchema: + type: object + required: + - name + properties: + name: + type: string + description: Name of the deleted synonym set + securitySchemes: api_key_header: type: apiKey From 6bf75c22b3f0959b95dd6dedbb050f2eac2d8b5f Mon Sep 17 00:00:00 2001 From: Fanis Tharropoulos Date: Fri, 22 Aug 2025 15:12:05 +0300 Subject: [PATCH 4/6] feat(v30): remove old synoym api --- openapi.yml | 129 ---------------------------------------------------- 1 file changed, 129 deletions(-) diff --git a/openapi.yml b/openapi.yml index fb4fbe0..589ca41 100644 --- a/openapi.yml +++ b/openapi.yml @@ -583,135 +583,6 @@ paths: application/json: schema: $ref: "#/components/schemas/ApiResponse" - /collections/{collectionName}/synonyms: - get: - tags: - - synonyms - summary: List all collection synonyms - operationId: getSearchSynonyms - parameters: - - name: collectionName - in: path - description: The name of the collection - required: true - schema: - type: string - responses: - '200': - description: List of all search synonyms - content: - application/json: - schema: - $ref: "#/components/schemas/SearchSynonymsResponse" - '404': - description: Search synonyms was not found - content: - application/json: - schema: - $ref: "#/components/schemas/ApiResponse" - /collections/{collectionName}/synonyms/{synonymId}: - get: - tags: - - synonyms - summary: Retrieve a single search synonym - description: Retrieve the details of a search synonym, given its id. - operationId: getSearchSynonym - parameters: - - name: collectionName - in: path - description: The name of the collection - required: true - schema: - type: string - - name: synonymId - in: path - description: The id of the search synonym - required: true - schema: - type: string - responses: - '200': - description: Search synonym fetched - content: - application/json: - schema: - $ref: "#/components/schemas/SearchSynonym" - '404': - description: Search synonym was not found - content: - application/json: - schema: - $ref: "#/components/schemas/ApiResponse" - put: - tags: - - synonyms - summary: Create or update a synonym - description: Create or update a synonym to define search terms that should be considered equivalent. - operationId: upsertSearchSynonym - parameters: - - name: collectionName - in: path - description: The name of the collection - required: true - schema: - type: string - - name: synonymId - in: path - description: The ID of the search synonym to create/update - required: true - schema: - type: string - requestBody: - description: The search synonym object to be created/updated - content: - application/json: - schema: - $ref: "#/components/schemas/SearchSynonymSchema" - required: true - responses: - '200': - description: Created/updated search synonym - content: - application/json: - schema: - $ref: "#/components/schemas/SearchSynonym" - '404': - description: Search synonym was not found - content: - application/json: - schema: - $ref: "#/components/schemas/ApiResponse" - delete: - tags: - - synonyms - summary: Delete a synonym associated with a collection - operationId: deleteSearchSynonym - parameters: - - name: collectionName - in: path - description: The name of the collection - required: true - schema: - type: string - - name: synonymId - in: path - description: The ID of the search synonym to delete - required: true - schema: - type: string - responses: - '200': - description: The ID of the deleted search synonym - content: - application/json: - schema: - $ref: "#/components/schemas/SearchSynonymDeleteResponse" - '404': - description: Search synonym not found - content: - application/json: - schema: - $ref: "#/components/schemas/ApiResponse" /synonym_sets: get: From 6c0ef07be5a5a1194ea8327bf4f33e4e14ba0835 Mon Sep 17 00:00:00 2001 From: Harisaran G Date: Mon, 11 Aug 2025 16:09:51 +0530 Subject: [PATCH 5/6] add: analytics spec --- openapi.yml | 287 ++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 200 insertions(+), 87 deletions(-) diff --git a/openapi.yml b/openapi.yml index 589ca41..ed9f902 100644 --- a/openapi.yml +++ b/openapi.yml @@ -1381,17 +1381,17 @@ paths: tags: - analytics summary: Create an analytics event - description: Sending events for analytics e.g rank search results based on popularity. + description: Submit a single analytics event. The event must correspond to an existing analytics rule by name. operationId: createAnalyticsEvent requestBody: - description: The Analytics event to be created + description: The analytics event to be created content: application/json: schema: - $ref: '#/components/schemas/AnalyticsEventCreateSchema' + $ref: '#/components/schemas/AnalyticsEvent' required: true responses: - '201': + '200': description: Analytics event successfully created content: application/json: @@ -1403,28 +1403,105 @@ paths: application/json: schema: $ref: '#/components/schemas/ApiResponse' + get: + tags: + - analytics + summary: Retrieve analytics events + description: Retrieve the most recent events for a user and rule. + operationId: getAnalyticsEvents + parameters: + - name: user_id + in: query + required: true + schema: + type: string + - name: name + in: query + description: Analytics rule name + required: true + schema: + type: string + - name: n + in: query + description: Number of events to return (max 1000) + required: true + schema: + type: integer + responses: + '200': + description: Events fetched + content: + application/json: + schema: + $ref: '#/components/schemas/AnalyticsEventsResponse' + '400': + description: Bad request, see error message for details + content: + application/json: + schema: + $ref: '#/components/schemas/ApiResponse' + /analytics/flush: + post: + tags: + - analytics + summary: Flush in-memory analytics to disk + description: Triggers a flush of analytics data to persistent storage. + operationId: flushAnalytics + responses: + '200': + description: Flush triggered + content: + application/json: + schema: + $ref: '#/components/schemas/AnalyticsEventCreateResponse' + /analytics/status: + get: + tags: + - analytics + summary: Get analytics subsystem status + description: Returns sizes of internal analytics buffers and queues. + operationId: getAnalyticsStatus + responses: + '200': + description: Status fetched + content: + application/json: + schema: + $ref: '#/components/schemas/AnalyticsStatus' /analytics/rules: post: tags: - analytics - summary: Creates an analytics rule - description: - When an analytics rule is created, we give it a name and describe the type, the source collections and the destination collection. + summary: Create analytics rule(s) + description: Create one or more analytics rules. You can send a single rule object or an array of rule objects. operationId: createAnalyticsRule requestBody: - description: The Analytics rule to be created + description: The analytics rule(s) to be created content: application/json: schema: - $ref: "#/components/schemas/AnalyticsRuleSchema" + oneOf: + - $ref: "#/components/schemas/AnalyticsRuleCreate" + - type: array + items: + $ref: "#/components/schemas/AnalyticsRuleCreate" required: true responses: - '201': - description: Analytics rule successfully created + '200': + description: Analytics rule(s) successfully created content: application/json: schema: - $ref: "#/components/schemas/AnalyticsRuleSchema" + oneOf: + - $ref: "#/components/schemas/AnalyticsRule" + - type: array + items: + anyOf: + - $ref: "#/components/schemas/AnalyticsRule" + - type: object + properties: + error: + type: string '400': description: Bad request, see error message for details content: @@ -1434,17 +1511,25 @@ paths: get: tags: - analytics - summary: Retrieves all analytics rules - description: - Retrieve the details of all analytics rules + summary: Retrieve analytics rules + description: Retrieve all analytics rules. Use the optional rule_tag filter to narrow down results. operationId: retrieveAnalyticsRules + parameters: + - in: query + name: rule_tag + schema: + type: string + required: false + description: Filter rules by rule_tag responses: '200': description: Analytics rules fetched content: application/json: schema: - $ref: "#/components/schemas/AnalyticsRulesRetrieveSchema" + type: array + items: + $ref: "#/components/schemas/AnalyticsRule" /analytics/rules/{ruleName}: put: tags: @@ -1465,7 +1550,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/AnalyticsRuleUpsertSchema" + $ref: "#/components/schemas/AnalyticsRuleUpdate" required: true responses: '200': @@ -1473,7 +1558,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/AnalyticsRuleSchema" + $ref: "#/components/schemas/AnalyticsRule" '400': description: Bad request, see error message for details content: @@ -1500,7 +1585,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/AnalyticsRuleSchema" + $ref: "#/components/schemas/AnalyticsRule" '404': description: Analytics rule not found content: @@ -1527,7 +1612,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/AnalyticsRuleDeleteResponse" + $ref: "#/components/schemas/SuccessStatus" '404': description: Analytics rule not found content: @@ -3632,105 +3717,133 @@ components: properties: ok: type: boolean - AnalyticsEventCreateSchema: + AnalyticsEvent: type: object required: - - type - name + - event_type - data properties: - type: - type: string name: type: string + description: Name of the analytics rule this event corresponds to + event_type: + type: string + description: Type of event (e.g., click, conversion, query, visit) data: type: object - AnalyticsRuleUpsertSchema: - type: object - required: - - type - - params - properties: - type: - type: string - enum: - - popular_queries - - nohits_queries - - counter - params: - $ref: "#/components/schemas/AnalyticsRuleParameters" - AnalyticsRuleParameters: - type: object - required: - - source - - destination - properties: - source: - $ref: '#/components/schemas/AnalyticsRuleParametersSource' - destination: - $ref: '#/components/schemas/AnalyticsRuleParametersDestination' - limit: - type: integer - expand_query: - type: boolean - AnalyticsRuleParametersSource: + description: Event payload + properties: + user_id: + type: string + doc_id: + type: string + doc_ids: + type: array + items: + type: string + q: + type: string + analytics_tag: + type: string + AnalyticsEventsResponse: type: object required: - - collections + - events properties: - collections: - type: array - items: - type: string events: type: array items: type: object - required: - - type - - weight - - name properties: - type: - type: string - weight: - type: number - format: float - name: - type: string - AnalyticsRuleParametersDestination: + name: { type: string } + event_type: { type: string } + collection: { type: string } + timestamp: { type: integer, format: int64 } + user_id: { type: string } + doc_id: { type: string } + doc_ids: + type: array + items: { type: string } + query: { type: string } + AnalyticsRuleCreate: type: object required: + - name + - type - collection + - event_type properties: + name: + type: string + type: + type: string + enum: [popular_queries, nohits_queries, counter, log] collection: type: string - counter_field: + event_type: + type: string + rule_tag: type: string - AnalyticsRuleDeleteResponse: + params: + type: object + properties: + destination_collection: + type: string + limit: + type: integer + capture_search_requests: + type: boolean + meta_fields: + type: array + items: { type: string } + expand_query: + type: boolean + counter_field: + type: string + weight: + type: integer + AnalyticsRuleUpdate: type: object - required: - - name + description: Fields allowed to update on an analytics rule properties: name: type: string - AnalyticsRuleSchema: - allOf: - - $ref: '#/components/schemas/AnalyticsRuleUpsertSchema' - - type: object - required: - - name + rule_tag: + type: string + params: + type: object properties: - name: + destination_collection: + type: string + limit: + type: integer + capture_search_requests: + type: boolean + meta_fields: + type: array + items: { type: string } + expand_query: + type: boolean + counter_field: type: string - AnalyticsRulesRetrieveSchema: + weight: + type: integer + AnalyticsRule: + allOf: + - $ref: '#/components/schemas/AnalyticsRuleCreate' + - type: object + AnalyticsStatus: type: object properties: - rules: - type: array - items: - $ref: "#/components/schemas/AnalyticsRuleSchema" - x-go-type: '[]*AnalyticsRuleSchema' + popular_prefix_queries: { type: integer } + nohits_prefix_queries: { type: integer } + log_prefix_queries: { type: integer } + query_log_events: { type: integer } + query_counter_events: { type: integer } + doc_log_events: { type: integer } + doc_counter_events: { type: integer } + APIStatsResponse: type: object properties: From 2ded3b997af321456863bf5302cc71f794cc738d Mon Sep 17 00:00:00 2001 From: Harisaran G Date: Mon, 11 Aug 2025 17:12:33 +0530 Subject: [PATCH 6/6] update: analytics spec for DELETE rule --- openapi.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yml b/openapi.yml index ed9f902..ad0b89e 100644 --- a/openapi.yml +++ b/openapi.yml @@ -1612,7 +1612,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/SuccessStatus" + $ref: "#/components/schemas/AnalyticsRule" '404': description: Analytics rule not found content: