From 909c958fc72c767ba59a44b7f434aaf13acacfe0 Mon Sep 17 00:00:00 2001 From: Dave Sirockin Date: Fri, 27 Mar 2026 14:47:02 +0100 Subject: [PATCH 01/14] feat(specs): add draft schema for Agentic Analytics Co-Authored-By: Claude Opus 4.6 --- .../common/schemas/EventAttributes.yml | 80 ++++++++++++++----- specs/insights/common/schemas/EventsItems.yml | 25 +++--- .../insights/common/schemas/InstantSearch.yml | 43 ++++++++++ .../common/schemas/InstantSearchEvent.yml | 2 + 4 files changed, 119 insertions(+), 31 deletions(-) create mode 100644 specs/insights/common/schemas/InstantSearch.yml create mode 100644 specs/insights/common/schemas/InstantSearchEvent.yml diff --git a/specs/insights/common/schemas/EventAttributes.yml b/specs/insights/common/schemas/EventAttributes.yml index c9c786806f8..5158db90129 100644 --- a/specs/insights/common/schemas/EventAttributes.yml +++ b/specs/insights/common/schemas/EventAttributes.yml @@ -68,7 +68,7 @@ objectIDs: type: string minItems: 1 maxItems: 20 - example: ['object-1', 'object-2', 'object-3'] + example: [ 'object-1', 'object-2', 'object-3' ] filters: type: array @@ -81,8 +81,39 @@ filters: type: string minItems: 1 maxItems: 20 - example: ['brand:apple'] + example: [ 'brand:apple' ] +instantSearch: + description: a set of fields for matching events to instant-search responses + type: object + properties: + messageID: + description: the ID of the instant-search message to which this event is related + type: string + minLength: 1 + maxLength: 256 + toolCallID: + description: the ID of the instant-search tool to which this event is related + type: string + minLength: 1 + maxLength: 256 + conversationID: + description: the ID of the instant-search conversation to which this event is related + type: string + minLength: 1 + maxLength: 256 + agentID: + description: the ID of instant-search agent to which this event is related + type: string + minLength: 1 + maxLength: 256 + required: + # Although all these fields are specified as optional in the Agentic Analytics document, now that they are grouped, it may + # make sense to make the parent property optional but require all sub properties to be supplied together, as here + - messageID + - toolCallID + - conversationID + - agentID positions: type: array items: @@ -94,25 +125,25 @@ positions: Position of the clicked item the search results. You must provide 1 `position` for each `objectID`. - example: [1, 2, 5] + example: [ 1, 2, 5 ] price: description: Final price of a single product, including any discounts, in units of `currency`. oneOf: - - type: number - format: double - example: 9.99 - - type: string - example: '9.99' + - type: number + format: double + example: 9.99 + - type: string + example: '9.99' discount: description: Absolute value of the discount for this product, in units of `currency`. oneOf: - - type: number - format: double - example: 20 - - type: string - example: '20' + - type: number + format: double + example: 20 + - type: string + example: '20' quantity: type: integer @@ -181,14 +212,25 @@ currency: description: Three-letter [currency code](https://www.iso.org/iso-4217-currency-codes.html). example: EUR +sessionID: + type: string + # We don't necessarily need to be this restrictive: + pattern: '[0-9a-f]{32}' + minLength: 32 + maxLength: 32 + description: | + Unique identifier for a session + [TODO]: Document here where this is derived and how it is used + example: 3e48cd0616e466948dd85abf5c3fbbe2 + value: description: | Total monetary value of this event in units of `currency`. This should be equal to the sum of `price` times `quantity`. oneOf: - - type: number - format: double - example: 1000.00 - - type: string - maxLength: 16 - example: '1000.00' + - type: number + format: double + example: 1000.00 + - type: string + maxLength: 16 + example: '1000.00' diff --git a/specs/insights/common/schemas/EventsItems.yml b/specs/insights/common/schemas/EventsItems.yml index dff4c0eea07..1b96873155e 100644 --- a/specs/insights/common/schemas/EventsItems.yml +++ b/specs/insights/common/schemas/EventsItems.yml @@ -1,13 +1,14 @@ oneOf: - - $ref: './ClickedObjectIDsAfterSearch.yml' - - $ref: './AddedToCartObjectIDsAfterSearch.yml' - - $ref: './PurchasedObjectIDsAfterSearch.yml' - - $ref: './ConvertedObjectIDsAfterSearch.yml' - - $ref: './ClickedObjectIDs.yml' - - $ref: './PurchasedObjectIDs.yml' - - $ref: './AddedToCartObjectIDs.yml' - - $ref: './ConvertedObjectIDs.yml' - - $ref: './ClickedFilters.yml' - - $ref: './ConvertedFilters.yml' - - $ref: './ViewedObjectIDs.yml' - - $ref: './ViewedFilters.yml' +- $ref: './ClickedObjectIDsAfterSearch.yml' +- $ref: './AddedToCartObjectIDsAfterSearch.yml' +- $ref: './PurchasedObjectIDsAfterSearch.yml' +- $ref: './ConvertedObjectIDsAfterSearch.yml' +- $ref: './ClickedObjectIDs.yml' +- $ref: './PurchasedObjectIDs.yml' +- $ref: './AddedToCartObjectIDs.yml' +- $ref: './ConvertedObjectIDs.yml' +- $ref: './ClickedFilters.yml' +- $ref: './ConvertedFilters.yml' +- $ref: './ViewedObjectIDs.yml' +- $ref: './ViewedFilters.yml' +- $ref: './InstantSearch.yml' diff --git a/specs/insights/common/schemas/InstantSearch.yml b/specs/insights/common/schemas/InstantSearch.yml new file mode 100644 index 00000000000..a7e2f9d7dd6 --- /dev/null +++ b/specs/insights/common/schemas/InstantSearch.yml @@ -0,0 +1,43 @@ +type: object +title: Instant Search +description: | + Tracks an initial user interaction with the Agentic Analytics API +properties: + eventType: + $ref: './InstantSearchEvent.yml' + eventName: + $ref: './EventAttributes.yml#/eventName' + sessionID: + $ref: './EventAttributes.yml#/sessionID' + # Index and userToken are not specified in the Agentic Analytics document + ## but are required by all other event schemas. + # Is there any case where we would not be able to provide either of these? + index: + $ref: './EventAttributes.yml#/index' + userToken: + $ref: './EventAttributes.yml#/userToken' + # This is not specified in the Agentic Analytics document but is optional in all other schemas + # Can we keep it here for consistency? + authenticatedUserToken: + $ref: './EventAttributes.yml#/authenticatedUserToken' + # This is stated as required by Agentic Analytics but we recommend leaving as optional for consistency + # with other schemas (it can be inferred if ommitted) + timestamp: + $ref: './EventAttributes.yml#/timestamp' + performance: + description: free form object for performance data + type: object + widgets: + description: free form object for widget information + type: object + + # The library and version are requested by Agent Analytics as optional parameters. + # I suggest ommiting them if they can be retrieved from the X-Algolia-Agent header +required: +- eventName +- sessionID +- eventType +- index +- userToken +x-discriminator-fields: +- eventType diff --git a/specs/insights/common/schemas/InstantSearchEvent.yml b/specs/insights/common/schemas/InstantSearchEvent.yml new file mode 100644 index 00000000000..57e39cf7af4 --- /dev/null +++ b/specs/insights/common/schemas/InstantSearchEvent.yml @@ -0,0 +1,2 @@ +type: string +enum: [instant-search] From 6a9ae714c2d7b8c9d0908c9d65072eac02ac3a9b Mon Sep 17 00:00:00 2001 From: Dave Sirockin Date: Fri, 27 Mar 2026 14:50:57 +0100 Subject: [PATCH 02/14] chore: run bundler --- package.json | 3 +- specs/bundled/insights.yml | 409 +++++++++++++------------------------ 2 files changed, 143 insertions(+), 269 deletions(-) diff --git a/package.json b/package.json index a673b99a9b1..eef840f9899 100644 --- a/package.json +++ b/package.json @@ -48,5 +48,6 @@ "engines": { "node": "^24.0.0", "yarn": "^4.0.0" - } + }, + "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e" } diff --git a/specs/bundled/insights.yml b/specs/bundled/insights.yml index 72f04a822ff..88e4c7d5a55 100644 --- a/specs/bundled/insights.yml +++ b/specs/bundled/insights.yml @@ -1,100 +1,57 @@ openapi: 3.0.2 info: title: Insights API - summary: >- - The Insights API lets you collect events related to your search and - discovery experience - description: > + summary: The Insights API lets you collect events related to your search and discovery experience + description: | Events represent user interactions with your app or website. - - They unlock powerful features, such as recommendations, personalization, - smarter search results, - + They unlock powerful features, such as recommendations, personalization, smarter search results, and analytics that help you optimize your user experience. - ## Client libraries - - Use Algolia's API clients, libraries, and integrations to collect events - from your UI and send them to the Insights API. - - For more information, see [Algolia's - ecosystem](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem). - + Use Algolia's API clients, libraries, and integrations to collect events from your UI and send them to the Insights API. + For more information, see [Algolia's ecosystem](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem). ## Base URLs - The base URLs for making requests to the Insights API are: - - `https://insights.us.algolia.io` - - `https://insights.de.algolia.io` - - - `https//insights.algolia.io` (routes requests to the closest of the above - servers, based on your geographical location) - + - `https//insights.algolia.io` (routes requests to the closest of the above servers, based on your geographical location) **All requests must use HTTPS.** - ## Authentication - Add these headers to authenticate requests: - - `x-algolia-application-id`. Your Algolia application ID. - - - `x-algolia-api-key`. An API key with the necessary permissions to make the - request. + - `x-algolia-api-key`. An API key with the necessary permissions to make the request. The required access control list (ACL) to make a request is listed in each endpoint's reference. - You can find your application ID and API key in the [Algolia - dashboard](https://dashboard.algolia.com/account/api-keys). - + You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys). ## Request format - Request bodies must be JSON objects. - ## Response status and errors - Response bodies are JSON objects. + Deleting a user token returns an empty response body with rate-limiting information as headers. - Deleting a user token returns an empty response body with rate-limiting - information as headers. - - - Successful responses return `2xx` statuses. Client errors return `4xx` - statuses. Server errors return `5xx` statuses. - + Successful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses. Error responses have a `message` property with more information. - - The Insights API doesn't validate if the event parameters such as - `indexName`, `objectIDs`, or `userToken`, - - correspond to anything in the Search API. It just checks if they're - formatted correctly. - - Check the [Events](https://dashboard.algolia.com/events/health) health - section, - - whether your events can be used for Algolia features such as Analytics, or - Dynamic Re-Ranking. - + The Insights API doesn't validate if the event parameters such as `indexName`, `objectIDs`, or `userToken`, + correspond to anything in the Search API. It just checks if they're formatted correctly. + Check the [Events](https://dashboard.algolia.com/events/health) health section, + whether your events can be used for Algolia features such as Analytics, or Dynamic Re-Ranking. ## Version - - The current version of the Insights API is version 1, indicated by the `/1/` - in each endpoint's URL. + The current version of the Insights API is version 1, indicated by the `/1/` in each endpoint's URL. version: 1.0.0 servers: - url: https://insights.{region}.algolia.io @@ -112,9 +69,7 @@ security: tags: - name: events x-displayName: Events - description: >- - Events represent user interactions with your website or app. They include - details like the event's name, type, a timestamp, or a user token. + description: Events represent user interactions with your website or app. They include details like the event's name, type, a timestamp, or a user token. - name: usertokens x-displayName: User tokens description: | @@ -146,8 +101,6 @@ paths: $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' - tags: - - insights post: operationId: customPost requestBody: @@ -176,8 +129,6 @@ paths: $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' - tags: - - insights put: operationId: customPut requestBody: @@ -206,8 +157,6 @@ paths: $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' - tags: - - insights delete: operationId: customDelete summary: Send requests to the Algolia REST API @@ -230,12 +179,10 @@ paths: $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' - tags: - - insights /1/events: post: tags: - - insights + - events operationId: pushEvents summary: Send events x-acl: @@ -257,12 +204,10 @@ paths: properties: events: type: array - description: > + description: | Click and conversion events. - - **All** events must be valid, otherwise the API returns an - error. + **All** events must be valid, otherwise the API returns an error. minItems: 1 maxItems: 1000 items: @@ -447,13 +392,7 @@ paths: examples: Success: summary: Events successfully sent to the Insights API - description: >- - Success indicates that the Insights API received the events - correctly, and that event properties are formatted - correctly. Success doesn't imply that the event can be used - by any Algolia feature. For example, the Insights API - doesn't check if the index name you provided exists, or if - the object IDs exist in your index. + description: Success indicates that the Insights API received the events correctly, and that event properties are formatted correctly. Success doesn't imply that the event can be used by any Algolia feature. For example, the Insights API doesn't check if the index name you provided exists, or if the object IDs exist in your index. value: status: 200 message: OK @@ -468,9 +407,7 @@ paths: BadRequest: summary: Bad request description: This error doesn't return a JSON object, but HTML. - value: >- - Error: Bad Request. Your client has issued a malformed or - illegal request. + value: 'Error: Bad Request. Your client has issued a malformed or illegal request.' '401': description: Unauthorized content: @@ -480,10 +417,7 @@ paths: examples: Unauthorized: summary: Invalid credentials - description: >- - You need to provide your application ID using the - `X-Algolia-Application-ID` header and your (search) API key - with the `X-Algolia-API-Key` header. + description: You need to provide your application ID using the `X-Algolia-Application-ID` header and your (search) API key with the `X-Algolia-API-Key` header. value: status: 401 message: Invalid credentials @@ -499,11 +433,7 @@ paths: description: Check that you're using the correct URL. value: status: 404 - message: >- - Path not supported by Insights REST API. Please have a - look at - [https://www.algolia.com/doc/rest-api/insights/](https://www.algolia.com/doc/rest-api/insights) - for the list of valid commands. + message: Path not supported by Insights REST API. Please have a look at [https://www.algolia.com/doc/rest-api/insights/](https://www.algolia.com/doc/rest-api/insights) for the list of valid commands. '405': description: Method Not Allowed. content: @@ -543,23 +473,16 @@ paths: message: Invalid payload NoEvents: summary: No events - description: >- - This can happen if you're sending an empty `events` array, - or if you try to send a single event object instead of the - `events` array. + description: This can happen if you're sending an empty `events` array, or if you try to send a single event object instead of the `events` array. value: status: 422 message: No events to process NoEventsField: summary: Missing events attribute - description: >- - This can happen if you try to send an array of events - directly instead of using the `events` attribute. + description: This can happen if you try to send an array of events directly instead of using the `events` attribute. value: status: 422 - message: >- - Invalid type for field : expected - insights.PublicEventsBatch, got array + message: 'Invalid type for field : expected insights.PublicEventsBatch, got array' EventNameRequired: summary: Missing eventName attribute value: @@ -569,9 +492,7 @@ paths: summary: Event name too long or wrong characters value: status: 422 - message: >- - EventName must contain only visible ASCII characters, and - be between 1 and 64 characters long + message: EventName must contain only visible ASCII characters, and be between 1 and 64 characters long EventTypeRequired: summary: Missing eventType attribute value: @@ -596,15 +517,10 @@ paths: summary: Malformed user token value: status: 422 - message: >- - UserToken must contain only alphanumeric, equal, plus, - slash, hyphen, or underscore characters, and be between 1 - and 128 characters long + message: UserToken must contain only alphanumeric, equal, plus, slash, hyphen, or underscore characters, and be between 1 and 128 characters long NoObjectIDsOrFilters: summary: Missing objectIDs or filters attribute - description: >- - Each event must include either the `objectIDs` or `filters` - attribute. + description: Each event must include either the `objectIDs` or `filters` attribute. value: status: 422 message: Event should specify either some ObjectIDs or some Filters @@ -617,50 +533,33 @@ paths: summary: Wrong combination of positions and eventType attributes value: status: 422 - message: >- - Only event of type click should specify the positions - attribute + message: Only event of type click should specify the positions attribute PositionsWithoutQueryID: summary: Positions attribute without queryID - description: >- - Click events with the `positions` attribute require the - `queryID` attribute. + description: Click events with the `positions` attribute require the `queryID` attribute. value: status: 422 - message: >- - Event of type click with positions should specify a - queryID + message: Event of type click with positions should specify a queryID WrongPositionsValue: summary: Wrong value in positions array description: Any value in the `positions` array must be greater than 0. value: status: 422 - message: >- - Event of type click may only have strictly positive - positions + message: Event of type click may only have strictly positive positions WrongPositionsItems: summary: Wrong number of items in positions array - description: >- - For click events with the `queryID` and `objectIDs` - attributes, you must include the `positions` attribute with - the same number of items as the `objectIDs` attribute. + description: For click events with the `queryID` and `objectIDs` attributes, you must include the `positions` attribute with the same number of items as the `objectIDs` attribute. value: status: 422 - message: >- - Event of type click should have the same number of - ObjectIDs and Positions + message: Event of type click should have the same number of ObjectIDs and Positions WrongQueryID: summary: Malformed query ID value: status: 422 - message: >- - Query ID must be a search query ID (32 characters - hexadecimal string) + message: Query ID must be a search query ID (32 characters hexadecimal string) InvalidDataType: summary: Wrong data type - description: >- - This can happen if one or more attribute is a number instead - of a string. + description: This can happen if one or more attribute is a number instead of a string. value: status: 422 message: 'Invalid type for field events: expected string, got number' @@ -678,17 +577,13 @@ paths: /1/usertokens/{userToken}: delete: tags: - - insights + - usertokens operationId: deleteUserToken summary: Delete user token - description: > - Deletes all events related to the specified user token from events - metrics and analytics. - + description: | + Deletes all events related to the specified user token from events metrics and analytics. The deletion is asynchronous, and processed within 48 hours. - - To delete a personalization user profile, see `Delete a user profile` in - the Personalization API. + To delete a personalization user profile, see `Delete a user profile` in the Personalization API. x-acl: - deleteObject parameters: @@ -715,9 +610,8 @@ paths: schema: $ref: '#/components/schemas/EventsResponse' '429': - description: > - Too Many Requests. This operation is rate-limited. Check the - `x-ratelimit-limit` and `x-ratelimit-reset` headers of the response. + description: | + Too Many Requests. This operation is rate-limited. Check the `x-ratelimit-limit` and `x-ratelimit-reset` headers of the response. content: application/json: schema: @@ -728,7 +622,7 @@ paths: x-asynchronous-helper: false x-acl: [] tags: - - insights + - Api Key operationId: setClientApiKey summary: Switch the API key used to authenticate requests description: | @@ -754,14 +648,10 @@ components: type: apiKey in: header name: x-algolia-api-key - description: > + description: | Your Algolia API key with the necessary permissions to make the request. - - Permissions are controlled through access control lists (ACL) and access - restrictions. - - The required ACL to make a request is listed in each endpoint's - reference. + Permissions are controlled through access control lists (ACL) and access restrictions. + The required ACL to make a request is listed in each endpoint's reference. parameters: PathInPath: name: path @@ -793,14 +683,11 @@ components: minLength: 1 maxLength: 64 pattern: '[\x20-\x7E]{1,64}' - description: > + description: | Event name, up to 64 ASCII characters. - Consider naming events consistently—for example, by adopting Segment's - [object-action](https://segment.com/academy/collecting-data/naming-conventions-for-clean-data/#the-object-action-framework) - framework. ClickEvent: type: string @@ -841,57 +728,41 @@ components: pattern: '[0-9a-f]{32}' minLength: 32 maxLength: 32 - description: > + description: | Unique identifier for a search query. - - The query ID is required for events related to search or browse - requests. - - If you add `clickAnalytics: true` as a search request parameter, the - query ID is included in the API response. + The query ID is required for events related to search or browse requests. + If you add `clickAnalytics: true` as a search request parameter, the query ID is included in the API response. example: 3e48cd0616e466948dd85abf5c3fbbe2 userToken: type: string minLength: 1 maxLength: 129 pattern: '[a-zA-Z0-9_=/+-]{1,129}' - description: > + description: | Anonymous or pseudonymous user identifier. - Don't use personally identifiable information in user tokens. - - For more information, see [User - token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken). + For more information, see [User token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken). example: test-user-1 authenticatedUserToken: type: string minLength: 1 maxLength: 129 pattern: '[a-zA-Z0-9_=/+-]{1,129}' - description: > + description: | Identifier for authenticated users. - - When the user signs in, you can get an identifier from your system and - send it as `authenticatedUserToken`. - - This lets you keep using the `userToken` from before the user signed in, - while providing a reliable way to identify users across sessions. - + When the user signs in, you can get an identifier from your system and send it as `authenticatedUserToken`. + This lets you keep using the `userToken` from before the user signed in, while providing a reliable way to identify users across sessions. Don't use personally identifiable information in user tokens. - - For more information, see [User - token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken). + For more information, see [User token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken). example: c6a52c02-d0c7-4b53-8ce3-2b8fd202f3f9 timestamp: type: integer format: int64 - description: > - Timestamp of the event, measured in milliseconds since the Unix epoch. - Must be no older than 30 days. - + description: | + Timestamp of the event, measured in milliseconds since the Unix epoch. Must be no older than 30 days. If not provided, we use the time at which the request was received. example: 1687193127 ClickedObjectIDsAfterSearch: @@ -946,14 +817,10 @@ components: minLength: 3 maxLength: 3 pattern: ^[A-Za-z]{3}$ - description: >- - Three-letter [currency - code](https://www.iso.org/iso-4217-currency-codes.html). + description: Three-letter [currency code](https://www.iso.org/iso-4217-currency-codes.html). example: EUR price: - description: >- - Final price of a single product, including any discounts, in units of - `currency`. + description: Final price of a single product, including any discounts, in units of `currency`. oneOf: - type: number format: double @@ -964,11 +831,9 @@ components: type: integer format: int32 example: 2 - description: > + description: | Quantity of a product that has been purchased or added to the cart. - - The total purchase value is the sum of `quantity` multiplied with the - `price` for each purchased item. + The total purchase value is the sum of `quantity` multiplied with the `price` for each purchased item. discount: description: Absolute value of the discount for this product, in units of `currency`. oneOf: @@ -986,9 +851,7 @@ components: pattern: '[0-9a-f]{32}' minLength: 32 maxLength: 32 - description: >- - Unique identifier for a search query, used to track purchase events - with multiple records that originate from different searches. + description: Unique identifier for a search query, used to track purchase events with multiple records that originate from different searches. example: 3e48cd0616e466948dd85abf5c3fbbe2 price: $ref: '#/components/schemas/price' @@ -998,10 +861,8 @@ components: $ref: '#/components/schemas/discount' objectDataAfterSearchList: type: array - description: > - Extra information about the records involved in a purchase or - add-to-cart events. - + description: | + Extra information about the records involved in a purchase or add-to-cart events. If provided, it must be the same length as `objectIDs`. items: @@ -1022,12 +883,9 @@ components: AddedToCartObjectIDsAfterSearch: type: object title: Added to cart object IDs after search - description: > - Use this event to track when users add items to their shopping cart - after a previous Algolia request. - - If you're building your category pages with Algolia, you'll also use - this event. + description: | + Use this event to track when users add items to their shopping cart after a previous Algolia request. + If you're building your category pages with Algolia, you'll also use this event. properties: eventName: $ref: '#/components/schemas/eventName' @@ -1073,12 +931,9 @@ components: PurchasedObjectIDsAfterSearch: type: object title: Purchased object IDs after search - description: > - Use this event to track when users make a purchase after a previous - Algolia request. - - If you're building your category pages with Algolia, you'll also use - this event. + description: | + Use this event to track when users make a purchase after a previous Algolia request. + If you're building your category pages with Algolia, you'll also use this event. properties: eventName: $ref: '#/components/schemas/eventName' @@ -1118,18 +973,12 @@ components: ConvertedObjectIDsAfterSearch: type: object title: Converted object IDs after search - description: > - Use this event to track when users convert after a previous Algolia - request. - - For example, a user clicks on an item in the search results to view the - product detail page. - + description: | + Use this event to track when users convert after a previous Algolia request. + For example, a user clicks on an item in the search results to view the product detail page. Then, the user adds the item to their shopping cart. - If you're building your category pages with Algolia, - you'll also use this event. properties: eventName: @@ -1161,16 +1010,11 @@ components: ClickedObjectIDs: type: object title: Clicked object IDs - description: > - Use this event to track when users click items unrelated to a previous - Algolia request. - - For example, if you don't use Algolia to build your category pages, use - this event. - + description: | + Use this event to track when users click items unrelated to a previous Algolia request. + For example, if you don't use Algolia to build your category pages, use this event. - To track click events related to Algolia requests, use the "Clicked - object IDs after search" event. + To track click events related to Algolia requests, use the "Clicked object IDs after search" event. properties: eventName: $ref: '#/components/schemas/eventName' @@ -1207,10 +1051,8 @@ components: $ref: '#/components/schemas/discount' objectDataList: type: array - description: > - Extra information about the records involved in a purchase or - add-to-cart event. - + description: | + Extra information about the records involved in a purchase or add-to-cart event. If specified, it must have the same length as `objectIDs`. items: @@ -1220,14 +1062,10 @@ components: PurchasedObjectIDs: type: object title: Purchased object IDs - description: > - Use this event to track when users make a purchase unrelated to a - previous Algolia request. For example, if you don't use Algolia to build - your category pages, use this event. - + description: | + Use this event to track when users make a purchase unrelated to a previous Algolia request. For example, if you don't use Algolia to build your category pages, use this event. - To track purchase events related to Algolia requests, use the "Purchased - object IDs after search" event. + To track purchase events related to Algolia requests, use the "Purchased object IDs after search" event. properties: eventName: $ref: '#/components/schemas/eventName' @@ -1265,14 +1103,10 @@ components: AddedToCartObjectIDs: type: object title: Added to cart object IDs - description: > - Use this event to track when users add items to their shopping cart - unrelated to a previous Algolia request. For example, if you don't use - Algolia to build your category pages, use this event. - + description: | + Use this event to track when users add items to their shopping cart unrelated to a previous Algolia request. For example, if you don't use Algolia to build your category pages, use this event. - To track add-to-cart events related to Algolia requests, use the "Added - to cart object IDs after search" event. + To track add-to-cart events related to Algolia requests, use the "Added to cart object IDs after search" event. properties: eventName: $ref: '#/components/schemas/eventName' @@ -1310,16 +1144,11 @@ components: ConvertedObjectIDs: type: object title: Converted object IDs - description: > - Use this event to track when users convert on items unrelated to a - previous Algolia request. - - For example, if you don't use Algolia to build your category pages, use - this event. - + description: | + Use this event to track when users convert on items unrelated to a previous Algolia request. + For example, if you don't use Algolia to build your category pages, use this event. - To track conversion events related to Algolia requests, use the - "Converted object IDs after search" event. + To track conversion events related to Algolia requests, use the "Converted object IDs after search" event. properties: eventName: $ref: '#/components/schemas/eventName' @@ -1360,9 +1189,7 @@ components: ClickedFilters: type: object title: Clicked filters - description: >- - Use this event to track when users click facet filters in your user - interface. + description: Use this event to track when users click facet filters in your user interface. properties: eventName: $ref: '#/components/schemas/eventName' @@ -1477,6 +1304,53 @@ components: x-discriminator-fields: - eventType - filters + InstantSearchEvent: + type: string + enum: + - instant-search + sessionID: + type: string + pattern: '[0-9a-f]{32}' + minLength: 32 + maxLength: 32 + description: | + Unique identifier for a session + [TODO]: Document here where this is derived and how it is used + example: 3e48cd0616e466948dd85abf5c3fbbe2 + InstantSearch: + type: object + title: Instant Search + description: | + Tracks an initial user interaction with the Agentic Analytics API + properties: + eventType: + $ref: '#/components/schemas/InstantSearchEvent' + eventName: + $ref: '#/components/schemas/eventName' + sessionID: + $ref: '#/components/schemas/sessionID' + index: + $ref: '#/components/schemas/index' + userToken: + $ref: '#/components/schemas/userToken' + authenticatedUserToken: + $ref: '#/components/schemas/authenticatedUserToken' + timestamp: + $ref: '#/components/schemas/timestamp' + performance: + description: free form object for performance data + type: object + widgets: + description: free form object for widget information + type: object + required: + - eventName + - sessionID + - eventType + - index + - userToken + x-discriminator-fields: + - eventType EventsItems: oneOf: - $ref: '#/components/schemas/ClickedObjectIDsAfterSearch' @@ -1491,6 +1365,7 @@ components: - $ref: '#/components/schemas/ConvertedFilters' - $ref: '#/components/schemas/ViewedObjectIDs' - $ref: '#/components/schemas/ViewedFilters' + - $ref: '#/components/schemas/InstantSearch' EventsResponse: type: object description: The response of the Insights API. @@ -1539,9 +1414,7 @@ components: schema: type: integer x-ratelimit-reset: - description: >- - Timestamp when the rate limit will reset, measured in seconds since the - Unix epoch. + description: Timestamp when the rate limit will reset, measured in seconds since the Unix epoch. example: 1710682486 schema: type: integer From 84b340f1702d2c30ead301411d283285fe9a9170 Mon Sep 17 00:00:00 2001 From: Dave Sirockin Date: Fri, 27 Mar 2026 14:59:50 +0100 Subject: [PATCH 03/14] chore: add githook packages to package.json --- package.json | 2 ++ 1 file changed, 2 insertions(+) diff --git a/package.json b/package.json index eef840f9899..2b4364f73dc 100644 --- a/package.json +++ b/package.json @@ -17,8 +17,10 @@ "clean": "rm -rf **/dist **/build **/.build **/node_modules **/.gradle **/vendor **/bin **/obj **/__pycache__ || true", "cli": "yarn workspace scripts start", "docker:setup": "./scripts/docker/setup.sh", + "eslint": "eslint", "fix:json": "eslint '**/*.json' --fix", "github-actions:lint": "eslint '.github/**/*.yml'", + "lint-staged": "lint-staged", "postinstall": "husky && yarn workspace eslint-plugin-automation-custom build", "playground:browser": "yarn workspace javascript-browser-playground start", "scripts:build": "yarn workspace scripts build:actions", From b88c2e7ca74b43630174edf3db0a9f9f227c2471 Mon Sep 17 00:00:00 2001 From: Dave Sirockin Date: Fri, 27 Mar 2026 15:15:26 +0100 Subject: [PATCH 04/14] chore: rename InstantSearchTelemetry event and add examples --- specs/insights/common/schemas/EventsItems.yml | 26 ++++++++--------- .../common/schemas/InstantSearchEvent.yml | 2 -- ...tSearch.yml => InstantSearchTelemetry.yml} | 24 +++++++-------- .../schemas/InstantSearchTelemetryEvent.yml | 2 ++ specs/insights/paths/pushEvents.yml | 29 ++++++++++++------- 5 files changed, 46 insertions(+), 37 deletions(-) delete mode 100644 specs/insights/common/schemas/InstantSearchEvent.yml rename specs/insights/common/schemas/{InstantSearch.yml => InstantSearchTelemetry.yml} (78%) create mode 100644 specs/insights/common/schemas/InstantSearchTelemetryEvent.yml diff --git a/specs/insights/common/schemas/EventsItems.yml b/specs/insights/common/schemas/EventsItems.yml index 1b96873155e..6cfd792d1fb 100644 --- a/specs/insights/common/schemas/EventsItems.yml +++ b/specs/insights/common/schemas/EventsItems.yml @@ -1,14 +1,14 @@ oneOf: -- $ref: './ClickedObjectIDsAfterSearch.yml' -- $ref: './AddedToCartObjectIDsAfterSearch.yml' -- $ref: './PurchasedObjectIDsAfterSearch.yml' -- $ref: './ConvertedObjectIDsAfterSearch.yml' -- $ref: './ClickedObjectIDs.yml' -- $ref: './PurchasedObjectIDs.yml' -- $ref: './AddedToCartObjectIDs.yml' -- $ref: './ConvertedObjectIDs.yml' -- $ref: './ClickedFilters.yml' -- $ref: './ConvertedFilters.yml' -- $ref: './ViewedObjectIDs.yml' -- $ref: './ViewedFilters.yml' -- $ref: './InstantSearch.yml' + - $ref: './ClickedObjectIDsAfterSearch.yml' + - $ref: './AddedToCartObjectIDsAfterSearch.yml' + - $ref: './PurchasedObjectIDsAfterSearch.yml' + - $ref: './ConvertedObjectIDsAfterSearch.yml' + - $ref: './ClickedObjectIDs.yml' + - $ref: './PurchasedObjectIDs.yml' + - $ref: './AddedToCartObjectIDs.yml' + - $ref: './ConvertedObjectIDs.yml' + - $ref: './ClickedFilters.yml' + - $ref: './ConvertedFilters.yml' + - $ref: './ViewedObjectIDs.yml' + - $ref: './ViewedFilters.yml' + - $ref: './InstantSearchTelemetry.yml' diff --git a/specs/insights/common/schemas/InstantSearchEvent.yml b/specs/insights/common/schemas/InstantSearchEvent.yml deleted file mode 100644 index 57e39cf7af4..00000000000 --- a/specs/insights/common/schemas/InstantSearchEvent.yml +++ /dev/null @@ -1,2 +0,0 @@ -type: string -enum: [instant-search] diff --git a/specs/insights/common/schemas/InstantSearch.yml b/specs/insights/common/schemas/InstantSearchTelemetry.yml similarity index 78% rename from specs/insights/common/schemas/InstantSearch.yml rename to specs/insights/common/schemas/InstantSearchTelemetry.yml index a7e2f9d7dd6..82adbb76623 100644 --- a/specs/insights/common/schemas/InstantSearch.yml +++ b/specs/insights/common/schemas/InstantSearchTelemetry.yml @@ -1,16 +1,16 @@ type: object -title: Instant Search +title: Instant Search Telemetry Event description: | - Tracks an initial user interaction with the Agentic Analytics API + Tracks an initial user interaction with the Agentic Analytics API. properties: eventType: - $ref: './InstantSearchEvent.yml' + $ref: './InstantSearchTelemetryEvent.yml' eventName: $ref: './EventAttributes.yml#/eventName' sessionID: $ref: './EventAttributes.yml#/sessionID' # Index and userToken are not specified in the Agentic Analytics document - ## but are required by all other event schemas. + # # but are required by all other event schemas. # Is there any case where we would not be able to provide either of these? index: $ref: './EventAttributes.yml#/index' @@ -25,19 +25,19 @@ properties: timestamp: $ref: './EventAttributes.yml#/timestamp' performance: - description: free form object for performance data + description: free form object for performance data. type: object widgets: - description: free form object for widget information + description: free form object for widget information. type: object # The library and version are requested by Agent Analytics as optional parameters. # I suggest ommiting them if they can be retrieved from the X-Algolia-Agent header required: -- eventName -- sessionID -- eventType -- index -- userToken + - eventName + - sessionID + - eventType + - index + - userToken x-discriminator-fields: -- eventType + - eventType diff --git a/specs/insights/common/schemas/InstantSearchTelemetryEvent.yml b/specs/insights/common/schemas/InstantSearchTelemetryEvent.yml new file mode 100644 index 00000000000..1b6ead685ac --- /dev/null +++ b/specs/insights/common/schemas/InstantSearchTelemetryEvent.yml @@ -0,0 +1,2 @@ +type: string +enum: [instantsearch_telemetry] diff --git a/specs/insights/paths/pushEvents.yml b/specs/insights/paths/pushEvents.yml index 8d456d6add9..09b110e703e 100644 --- a/specs/insights/paths/pushEvents.yml +++ b/specs/insights/paths/pushEvents.yml @@ -185,7 +185,22 @@ post: userToken: anonymous-user-1 authenticatedUserToken: user-1 filters: ['category:books'] - + InstantSearchTelemetry: + summary: InstantSearch Telemetry event + value: + events: + - eventName: My Event Name + eventType: instantsearch_telemetry + index: test-index + userToken: anonymous-user-1 + sessionID: f47ac10b-58cc-4372-a567-0e02b2c3d479 + client_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 + performance: + foo: 343 + bar: 'blah' + widgets: + ping: + pong: 21 responses: '200': description: OK @@ -197,11 +212,7 @@ post: Success: summary: Events successfully sent to the Insights API description: >- - Success indicates that the Insights API received the events correctly, - and that event properties are formatted correctly. - Success doesn't imply that the event can be used by any Algolia feature. - For example, the Insights API doesn't check if the index name you provided exists, - or if the object IDs exist in your index. + Success indicates that the Insights API received the events correctly, and that event properties are formatted correctly. Success doesn't imply that the event can be used by any Algolia feature. For example, the Insights API doesn't check if the index name you provided exists, or if the object IDs exist in your index. value: status: 200 message: OK @@ -283,8 +294,7 @@ post: NoEvents: summary: No events description: >- - This can happen if you're sending an empty `events` array, - or if you try to send a single event object instead of the `events` array. + This can happen if you're sending an empty `events` array, or if you try to send a single event object instead of the `events` array. value: status: 422 message: No events to process @@ -360,8 +370,7 @@ post: WrongPositionsItems: summary: Wrong number of items in positions array description: >- - For click events with the `queryID` and `objectIDs` attributes, - you must include the `positions` attribute with the same number of items as the `objectIDs` attribute. + For click events with the `queryID` and `objectIDs` attributes, you must include the `positions` attribute with the same number of items as the `objectIDs` attribute. value: status: 422 message: Event of type click should have the same number of ObjectIDs and Positions From 6db0d0cdbf64925f47a149d231142b4eb0708d49 Mon Sep 17 00:00:00 2001 From: Dave Sirockin Date: Fri, 27 Mar 2026 15:20:09 +0100 Subject: [PATCH 05/14] chore: add instantSearch property to other event schemas --- .../common/schemas/AddedToCartObjectIDs.yml | 2 + .../AddedToCartObjectIDsAfterSearch.yml | 2 + .../common/schemas/ClickedFilters.yml | 2 + .../common/schemas/ClickedObjectIDs.yml | 2 + .../schemas/ClickedObjectIDsAfterSearch.yml | 2 + .../common/schemas/ConvertedObjectIDs.yml | 2 + .../schemas/ConvertedObjectIDsAfterSearch.yml | 2 + .../common/schemas/EventAttributes.yml | 64 ++++++++++--------- .../common/schemas/PurchasedObjectIDs.yml | 2 + .../schemas/PurchasedObjectIDsAfterSearch.yml | 2 + .../insights/common/schemas/ViewedFilters.yml | 2 + .../common/schemas/ViewedObjectIDs.yml | 2 + 12 files changed, 55 insertions(+), 31 deletions(-) diff --git a/specs/insights/common/schemas/AddedToCartObjectIDs.yml b/specs/insights/common/schemas/AddedToCartObjectIDs.yml index cb794939f41..205e455dd5f 100644 --- a/specs/insights/common/schemas/AddedToCartObjectIDs.yml +++ b/specs/insights/common/schemas/AddedToCartObjectIDs.yml @@ -27,6 +27,8 @@ properties: $ref: './EventAttributes.yml#/timestamp' value: $ref: './EventAttributes.yml#/value' + instantSearch: + $ref: './EventAttributes.yml#/instantSearch' required: - eventName - eventType diff --git a/specs/insights/common/schemas/AddedToCartObjectIDsAfterSearch.yml b/specs/insights/common/schemas/AddedToCartObjectIDsAfterSearch.yml index 7dab5cb642b..d2e885f7e26 100644 --- a/specs/insights/common/schemas/AddedToCartObjectIDsAfterSearch.yml +++ b/specs/insights/common/schemas/AddedToCartObjectIDsAfterSearch.yml @@ -28,6 +28,8 @@ properties: $ref: './EventAttributes.yml#/timestamp' value: $ref: './EventAttributes.yml#/value' + instantSearch: + $ref: './EventAttributes.yml#/instantSearch' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ClickedFilters.yml b/specs/insights/common/schemas/ClickedFilters.yml index 5b5c79c8817..d0b2599ae9c 100644 --- a/specs/insights/common/schemas/ClickedFilters.yml +++ b/specs/insights/common/schemas/ClickedFilters.yml @@ -16,6 +16,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + instantSearch: + $ref: './EventAttributes.yml#/instantSearch' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ClickedObjectIDs.yml b/specs/insights/common/schemas/ClickedObjectIDs.yml index 0b1c43588f5..b0f52d32e5b 100644 --- a/specs/insights/common/schemas/ClickedObjectIDs.yml +++ b/specs/insights/common/schemas/ClickedObjectIDs.yml @@ -20,6 +20,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + instantSearch: + $ref: './EventAttributes.yml#/instantSearch' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml b/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml index 40fe705b34b..fc9cb9265f5 100644 --- a/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml +++ b/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml @@ -24,6 +24,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + instantSearch: + $ref: './EventAttributes.yml#/instantSearch' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ConvertedObjectIDs.yml b/specs/insights/common/schemas/ConvertedObjectIDs.yml index f4f3945914f..9f4b98f5102 100644 --- a/specs/insights/common/schemas/ConvertedObjectIDs.yml +++ b/specs/insights/common/schemas/ConvertedObjectIDs.yml @@ -20,6 +20,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + instantSearch: + $ref: './EventAttributes.yml#/instantSearch' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml b/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml index f346f6c16b2..4ce3430d967 100644 --- a/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml +++ b/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml @@ -24,6 +24,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + instantSearch: + $ref: './EventAttributes.yml#/instantSearch' required: - eventName - eventType diff --git a/specs/insights/common/schemas/EventAttributes.yml b/specs/insights/common/schemas/EventAttributes.yml index 5158db90129..151742c56c5 100644 --- a/specs/insights/common/schemas/EventAttributes.yml +++ b/specs/insights/common/schemas/EventAttributes.yml @@ -68,7 +68,7 @@ objectIDs: type: string minItems: 1 maxItems: 20 - example: [ 'object-1', 'object-2', 'object-3' ] + example: ['object-1', 'object-2', 'object-3'] filters: type: array @@ -81,39 +81,41 @@ filters: type: string minItems: 1 maxItems: 20 - example: [ 'brand:apple' ] + example: ['brand:apple'] instantSearch: - description: a set of fields for matching events to instant-search responses + description: a set of fields for matching events to instant-search responses. type: object properties: messageID: - description: the ID of the instant-search message to which this event is related + description: the ID of the instant-search message to which this event is related. type: string minLength: 1 maxLength: 256 toolCallID: - description: the ID of the instant-search tool to which this event is related + description: the ID of the instant-search tool to which this event is related. type: string minLength: 1 maxLength: 256 conversationID: - description: the ID of the instant-search conversation to which this event is related + description: the ID of the instant-search conversation to which this event is related. type: string minLength: 1 maxLength: 256 agentID: - description: the ID of instant-search agent to which this event is related + description: the ID of instant-search agent to which this event is related. type: string minLength: 1 maxLength: 256 + instantSearch: + $ref: './EventAttributes.yml#/instantSearch' required: - # Although all these fields are specified as optional in the Agentic Analytics document, now that they are grouped, it may - # make sense to make the parent property optional but require all sub properties to be supplied together, as here - - messageID - - toolCallID - - conversationID - - agentID + # Although all these fields are specified as optional in the Agentic Analytics document, now that they are grouped, it may + # make sense to make the parent property optional but require all sub properties to be supplied together, as here + - messageID + - toolCallID + - conversationID + - agentID positions: type: array items: @@ -125,25 +127,25 @@ positions: Position of the clicked item the search results. You must provide 1 `position` for each `objectID`. - example: [ 1, 2, 5 ] + example: [1, 2, 5] price: description: Final price of a single product, including any discounts, in units of `currency`. oneOf: - - type: number - format: double - example: 9.99 - - type: string - example: '9.99' + - type: number + format: double + example: 9.99 + - type: string + example: '9.99' discount: description: Absolute value of the discount for this product, in units of `currency`. oneOf: - - type: number - format: double - example: 20 - - type: string - example: '20' + - type: number + format: double + example: 20 + - type: string + example: '20' quantity: type: integer @@ -220,7 +222,7 @@ sessionID: maxLength: 32 description: | Unique identifier for a session - [TODO]: Document here where this is derived and how it is used + [TODO]: Document here where this is derived and how it is used. example: 3e48cd0616e466948dd85abf5c3fbbe2 value: @@ -228,9 +230,9 @@ value: Total monetary value of this event in units of `currency`. This should be equal to the sum of `price` times `quantity`. oneOf: - - type: number - format: double - example: 1000.00 - - type: string - maxLength: 16 - example: '1000.00' + - type: number + format: double + example: 1000.00 + - type: string + maxLength: 16 + example: '1000.00' diff --git a/specs/insights/common/schemas/PurchasedObjectIDs.yml b/specs/insights/common/schemas/PurchasedObjectIDs.yml index f8d3a61f038..78274b6377a 100644 --- a/specs/insights/common/schemas/PurchasedObjectIDs.yml +++ b/specs/insights/common/schemas/PurchasedObjectIDs.yml @@ -27,6 +27,8 @@ properties: $ref: './EventAttributes.yml#/timestamp' value: $ref: './EventAttributes.yml#/value' + instantSearch: + $ref: './EventAttributes.yml#/instantSearch' required: - eventName - eventType diff --git a/specs/insights/common/schemas/PurchasedObjectIDsAfterSearch.yml b/specs/insights/common/schemas/PurchasedObjectIDsAfterSearch.yml index 1932a7e4ebf..19a06275d31 100644 --- a/specs/insights/common/schemas/PurchasedObjectIDsAfterSearch.yml +++ b/specs/insights/common/schemas/PurchasedObjectIDsAfterSearch.yml @@ -26,6 +26,8 @@ properties: $ref: './EventAttributes.yml#/timestamp' value: $ref: './EventAttributes.yml#/value' + instantSearch: + $ref: './EventAttributes.yml#/instantSearch' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ViewedFilters.yml b/specs/insights/common/schemas/ViewedFilters.yml index 5e7a1356e46..8eacee8f27f 100644 --- a/specs/insights/common/schemas/ViewedFilters.yml +++ b/specs/insights/common/schemas/ViewedFilters.yml @@ -19,6 +19,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + instantSearch: + $ref: './EventAttributes.yml#/instantSearch' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ViewedObjectIDs.yml b/specs/insights/common/schemas/ViewedObjectIDs.yml index aba9c3b1939..e9055e58b33 100644 --- a/specs/insights/common/schemas/ViewedObjectIDs.yml +++ b/specs/insights/common/schemas/ViewedObjectIDs.yml @@ -16,6 +16,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + instantSearch: + $ref: './EventAttributes.yml#/instantSearch' required: - eventName - eventType From 4953000edacd688366ebf3dd09a9e76954bdd564 Mon Sep 17 00:00:00 2001 From: Dave Sirockin Date: Fri, 27 Mar 2026 15:37:01 +0100 Subject: [PATCH 06/14] chore: rename instantSearch -> agent --- .../common/schemas/AddedToCartObjectIDs.yml | 4 ++-- .../AddedToCartObjectIDsAfterSearch.yml | 4 ++-- .../common/schemas/ClickedFilters.yml | 4 ++-- .../common/schemas/ClickedObjectIDs.yml | 4 ++-- .../schemas/ClickedObjectIDsAfterSearch.yml | 4 ++-- .../common/schemas/ConvertedFilters.yml | 2 ++ .../common/schemas/ConvertedObjectIDs.yml | 4 ++-- .../schemas/ConvertedObjectIDsAfterSearch.yml | 4 ++-- .../common/schemas/EventAttributes.yml | 20 +++++++++---------- .../common/schemas/PurchasedObjectIDs.yml | 4 ++-- .../schemas/PurchasedObjectIDsAfterSearch.yml | 4 ++-- .../insights/common/schemas/ViewedFilters.yml | 4 ++-- .../common/schemas/ViewedObjectIDs.yml | 4 ++-- 13 files changed, 33 insertions(+), 33 deletions(-) diff --git a/specs/insights/common/schemas/AddedToCartObjectIDs.yml b/specs/insights/common/schemas/AddedToCartObjectIDs.yml index 205e455dd5f..e7088c50bad 100644 --- a/specs/insights/common/schemas/AddedToCartObjectIDs.yml +++ b/specs/insights/common/schemas/AddedToCartObjectIDs.yml @@ -27,8 +27,8 @@ properties: $ref: './EventAttributes.yml#/timestamp' value: $ref: './EventAttributes.yml#/value' - instantSearch: - $ref: './EventAttributes.yml#/instantSearch' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/AddedToCartObjectIDsAfterSearch.yml b/specs/insights/common/schemas/AddedToCartObjectIDsAfterSearch.yml index d2e885f7e26..3392ad597f6 100644 --- a/specs/insights/common/schemas/AddedToCartObjectIDsAfterSearch.yml +++ b/specs/insights/common/schemas/AddedToCartObjectIDsAfterSearch.yml @@ -28,8 +28,8 @@ properties: $ref: './EventAttributes.yml#/timestamp' value: $ref: './EventAttributes.yml#/value' - instantSearch: - $ref: './EventAttributes.yml#/instantSearch' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ClickedFilters.yml b/specs/insights/common/schemas/ClickedFilters.yml index d0b2599ae9c..0126dcfe185 100644 --- a/specs/insights/common/schemas/ClickedFilters.yml +++ b/specs/insights/common/schemas/ClickedFilters.yml @@ -16,8 +16,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' - instantSearch: - $ref: './EventAttributes.yml#/instantSearch' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ClickedObjectIDs.yml b/specs/insights/common/schemas/ClickedObjectIDs.yml index b0f52d32e5b..8ed76319c94 100644 --- a/specs/insights/common/schemas/ClickedObjectIDs.yml +++ b/specs/insights/common/schemas/ClickedObjectIDs.yml @@ -20,8 +20,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' - instantSearch: - $ref: './EventAttributes.yml#/instantSearch' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml b/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml index fc9cb9265f5..1800f945358 100644 --- a/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml +++ b/specs/insights/common/schemas/ClickedObjectIDsAfterSearch.yml @@ -24,8 +24,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' - instantSearch: - $ref: './EventAttributes.yml#/instantSearch' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ConvertedFilters.yml b/specs/insights/common/schemas/ConvertedFilters.yml index b3e75a874b0..b7f56b664b7 100644 --- a/specs/insights/common/schemas/ConvertedFilters.yml +++ b/specs/insights/common/schemas/ConvertedFilters.yml @@ -15,6 +15,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ConvertedObjectIDs.yml b/specs/insights/common/schemas/ConvertedObjectIDs.yml index 9f4b98f5102..cf8f80ecdc2 100644 --- a/specs/insights/common/schemas/ConvertedObjectIDs.yml +++ b/specs/insights/common/schemas/ConvertedObjectIDs.yml @@ -20,8 +20,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' - instantSearch: - $ref: './EventAttributes.yml#/instantSearch' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml b/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml index 4ce3430d967..dbd68cbd45d 100644 --- a/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml +++ b/specs/insights/common/schemas/ConvertedObjectIDsAfterSearch.yml @@ -24,8 +24,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' - instantSearch: - $ref: './EventAttributes.yml#/instantSearch' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/EventAttributes.yml b/specs/insights/common/schemas/EventAttributes.yml index 151742c56c5..3b5ba326e9f 100644 --- a/specs/insights/common/schemas/EventAttributes.yml +++ b/specs/insights/common/schemas/EventAttributes.yml @@ -83,12 +83,17 @@ filters: maxItems: 20 example: ['brand:apple'] -instantSearch: - description: a set of fields for matching events to instant-search responses. +agent: + description: a set of fields for matching events to agent responses. type: object properties: + agentID: + description: the ID of the agent to which this event is related. + type: string + minLength: 1 + maxLength: 256 messageID: - description: the ID of the instant-search message to which this event is related. + description: the ID of the agent message to which this event is related. type: string minLength: 1 maxLength: 256 @@ -102,20 +107,13 @@ instantSearch: type: string minLength: 1 maxLength: 256 - agentID: - description: the ID of instant-search agent to which this event is related. - type: string - minLength: 1 - maxLength: 256 - instantSearch: - $ref: './EventAttributes.yml#/instantSearch' required: # Although all these fields are specified as optional in the Agentic Analytics document, now that they are grouped, it may # make sense to make the parent property optional but require all sub properties to be supplied together, as here + - agentID - messageID - toolCallID - conversationID - - agentID positions: type: array items: diff --git a/specs/insights/common/schemas/PurchasedObjectIDs.yml b/specs/insights/common/schemas/PurchasedObjectIDs.yml index 78274b6377a..70155afe64a 100644 --- a/specs/insights/common/schemas/PurchasedObjectIDs.yml +++ b/specs/insights/common/schemas/PurchasedObjectIDs.yml @@ -27,8 +27,8 @@ properties: $ref: './EventAttributes.yml#/timestamp' value: $ref: './EventAttributes.yml#/value' - instantSearch: - $ref: './EventAttributes.yml#/instantSearch' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/PurchasedObjectIDsAfterSearch.yml b/specs/insights/common/schemas/PurchasedObjectIDsAfterSearch.yml index 19a06275d31..baf6683f885 100644 --- a/specs/insights/common/schemas/PurchasedObjectIDsAfterSearch.yml +++ b/specs/insights/common/schemas/PurchasedObjectIDsAfterSearch.yml @@ -26,8 +26,8 @@ properties: $ref: './EventAttributes.yml#/timestamp' value: $ref: './EventAttributes.yml#/value' - instantSearch: - $ref: './EventAttributes.yml#/instantSearch' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ViewedFilters.yml b/specs/insights/common/schemas/ViewedFilters.yml index 8eacee8f27f..ff19351dbe3 100644 --- a/specs/insights/common/schemas/ViewedFilters.yml +++ b/specs/insights/common/schemas/ViewedFilters.yml @@ -19,8 +19,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' - instantSearch: - $ref: './EventAttributes.yml#/instantSearch' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType diff --git a/specs/insights/common/schemas/ViewedObjectIDs.yml b/specs/insights/common/schemas/ViewedObjectIDs.yml index e9055e58b33..caabc67abf0 100644 --- a/specs/insights/common/schemas/ViewedObjectIDs.yml +++ b/specs/insights/common/schemas/ViewedObjectIDs.yml @@ -16,8 +16,8 @@ properties: $ref: './EventAttributes.yml#/authenticatedUserToken' timestamp: $ref: './EventAttributes.yml#/timestamp' - instantSearch: - $ref: './EventAttributes.yml#/instantSearch' + agent: + $ref: './EventAttributes.yml#/agent' required: - eventName - eventType From 00a5fbb5f8b22e14d52e9150dedcbb4f8caed8f1 Mon Sep 17 00:00:00 2001 From: Dave Sirockin Date: Fri, 27 Mar 2026 15:38:21 +0100 Subject: [PATCH 07/14] chore: edit InstantSearch in line with feedback --- .../common/schemas/InstantSearchTelemetry.yml | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/specs/insights/common/schemas/InstantSearchTelemetry.yml b/specs/insights/common/schemas/InstantSearchTelemetry.yml index 82adbb76623..c6ad11414b2 100644 --- a/specs/insights/common/schemas/InstantSearchTelemetry.yml +++ b/specs/insights/common/schemas/InstantSearchTelemetry.yml @@ -9,19 +9,12 @@ properties: $ref: './EventAttributes.yml#/eventName' sessionID: $ref: './EventAttributes.yml#/sessionID' - # Index and userToken are not specified in the Agentic Analytics document - # # but are required by all other event schemas. - # Is there any case where we would not be able to provide either of these? - index: - $ref: './EventAttributes.yml#/index' userToken: $ref: './EventAttributes.yml#/userToken' # This is not specified in the Agentic Analytics document but is optional in all other schemas # Can we keep it here for consistency? authenticatedUserToken: $ref: './EventAttributes.yml#/authenticatedUserToken' - # This is stated as required by Agentic Analytics but we recommend leaving as optional for consistency - # with other schemas (it can be inferred if ommitted) timestamp: $ref: './EventAttributes.yml#/timestamp' performance: @@ -30,14 +23,10 @@ properties: widgets: description: free form object for widget information. type: object - - # The library and version are requested by Agent Analytics as optional parameters. - # I suggest ommiting them if they can be retrieved from the X-Algolia-Agent header required: - eventName - sessionID - eventType - - index - userToken x-discriminator-fields: - eventType From f283426966ea6c91e8b6dfc9137e7c6f4b9672df Mon Sep 17 00:00:00 2001 From: Dave Sirockin Date: Mon, 30 Mar 2026 10:35:57 +0200 Subject: [PATCH 08/14] chore: rename instant-search->instantsearch --- specs/insights/common/schemas/EventAttributes.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/insights/common/schemas/EventAttributes.yml b/specs/insights/common/schemas/EventAttributes.yml index 3b5ba326e9f..c414be23e03 100644 --- a/specs/insights/common/schemas/EventAttributes.yml +++ b/specs/insights/common/schemas/EventAttributes.yml @@ -98,12 +98,12 @@ agent: minLength: 1 maxLength: 256 toolCallID: - description: the ID of the instant-search tool to which this event is related. + description: the ID of the instant search tool to which this event is related. type: string minLength: 1 maxLength: 256 conversationID: - description: the ID of the instant-search conversation to which this event is related. + description: the ID of the instant search conversation to which this event is related. type: string minLength: 1 maxLength: 256 From c0972a196fc08f9a16e656a22af4d81d4202bc39 Mon Sep 17 00:00:00 2001 From: Dave Sirockin Date: Mon, 30 Mar 2026 10:37:28 +0200 Subject: [PATCH 09/14] chore: update bundled insights spec Co-Authored-By: Claude Opus 4.6 (1M context) From 44764e234d312617cf5a89a80fd5a2139e81e132 Mon Sep 17 00:00:00 2001 From: Dave Sirockin Date: Mon, 30 Mar 2026 11:16:54 +0200 Subject: [PATCH 10/14] chore: remove index from example --- specs/insights/paths/pushEvents.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/specs/insights/paths/pushEvents.yml b/specs/insights/paths/pushEvents.yml index 09b110e703e..09f0ba221e7 100644 --- a/specs/insights/paths/pushEvents.yml +++ b/specs/insights/paths/pushEvents.yml @@ -191,7 +191,6 @@ post: events: - eventName: My Event Name eventType: instantsearch_telemetry - index: test-index userToken: anonymous-user-1 sessionID: f47ac10b-58cc-4372-a567-0e02b2c3d479 client_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 From 2a5e72853caaef1e934dba4cf1d22a96daceba60 Mon Sep 17 00:00:00 2001 From: Dave Sirockin Date: Mon, 30 Mar 2026 11:30:50 +0200 Subject: [PATCH 11/14] chore: revert changes to bundled spec From 19e54dfd717cf4657cbd5ccd7492e1b80ee097c3 Mon Sep 17 00:00:00 2001 From: Dave Sirockin Date: Mon, 30 Mar 2026 11:37:06 +0200 Subject: [PATCH 12/14] chore: revert bundled spec to main Co-Authored-By: Claude Opus 4.6 (1M context) From 1446abd00064ee6805bc577543ac178d63f13c1a Mon Sep 17 00:00:00 2001 From: Dave Sirockin Date: Mon, 30 Mar 2026 11:37:19 +0200 Subject: [PATCH 13/14] chore: revert bundled spec to main Co-Authored-By: Claude Opus 4.6 (1M context) --- specs/bundled/insights.yml | 409 ++++++++++++++++++++++++------------- 1 file changed, 268 insertions(+), 141 deletions(-) diff --git a/specs/bundled/insights.yml b/specs/bundled/insights.yml index 88e4c7d5a55..72f04a822ff 100644 --- a/specs/bundled/insights.yml +++ b/specs/bundled/insights.yml @@ -1,57 +1,100 @@ openapi: 3.0.2 info: title: Insights API - summary: The Insights API lets you collect events related to your search and discovery experience - description: | + summary: >- + The Insights API lets you collect events related to your search and + discovery experience + description: > Events represent user interactions with your app or website. - They unlock powerful features, such as recommendations, personalization, smarter search results, + + They unlock powerful features, such as recommendations, personalization, + smarter search results, + and analytics that help you optimize your user experience. + ## Client libraries - Use Algolia's API clients, libraries, and integrations to collect events from your UI and send them to the Insights API. - For more information, see [Algolia's ecosystem](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem). + + Use Algolia's API clients, libraries, and integrations to collect events + from your UI and send them to the Insights API. + + For more information, see [Algolia's + ecosystem](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem). + ## Base URLs + The base URLs for making requests to the Insights API are: + - `https://insights.us.algolia.io` + - `https://insights.de.algolia.io` - - `https//insights.algolia.io` (routes requests to the closest of the above servers, based on your geographical location) + + - `https//insights.algolia.io` (routes requests to the closest of the above + servers, based on your geographical location) + **All requests must use HTTPS.** + ## Authentication + Add these headers to authenticate requests: + - `x-algolia-application-id`. Your Algolia application ID. - - `x-algolia-api-key`. An API key with the necessary permissions to make the request. + + - `x-algolia-api-key`. An API key with the necessary permissions to make the + request. The required access control list (ACL) to make a request is listed in each endpoint's reference. - You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys). + You can find your application ID and API key in the [Algolia + dashboard](https://dashboard.algolia.com/account/api-keys). + ## Request format + Request bodies must be JSON objects. + ## Response status and errors + Response bodies are JSON objects. - Deleting a user token returns an empty response body with rate-limiting information as headers. - Successful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses. + Deleting a user token returns an empty response body with rate-limiting + information as headers. + + + Successful responses return `2xx` statuses. Client errors return `4xx` + statuses. Server errors return `5xx` statuses. + Error responses have a `message` property with more information. - The Insights API doesn't validate if the event parameters such as `indexName`, `objectIDs`, or `userToken`, - correspond to anything in the Search API. It just checks if they're formatted correctly. - Check the [Events](https://dashboard.algolia.com/events/health) health section, - whether your events can be used for Algolia features such as Analytics, or Dynamic Re-Ranking. + + The Insights API doesn't validate if the event parameters such as + `indexName`, `objectIDs`, or `userToken`, + + correspond to anything in the Search API. It just checks if they're + formatted correctly. + + Check the [Events](https://dashboard.algolia.com/events/health) health + section, + + whether your events can be used for Algolia features such as Analytics, or + Dynamic Re-Ranking. + ## Version - The current version of the Insights API is version 1, indicated by the `/1/` in each endpoint's URL. + + The current version of the Insights API is version 1, indicated by the `/1/` + in each endpoint's URL. version: 1.0.0 servers: - url: https://insights.{region}.algolia.io @@ -69,7 +112,9 @@ security: tags: - name: events x-displayName: Events - description: Events represent user interactions with your website or app. They include details like the event's name, type, a timestamp, or a user token. + description: >- + Events represent user interactions with your website or app. They include + details like the event's name, type, a timestamp, or a user token. - name: usertokens x-displayName: User tokens description: | @@ -101,6 +146,8 @@ paths: $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' + tags: + - insights post: operationId: customPost requestBody: @@ -129,6 +176,8 @@ paths: $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' + tags: + - insights put: operationId: customPut requestBody: @@ -157,6 +206,8 @@ paths: $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' + tags: + - insights delete: operationId: customDelete summary: Send requests to the Algolia REST API @@ -179,10 +230,12 @@ paths: $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' + tags: + - insights /1/events: post: tags: - - events + - insights operationId: pushEvents summary: Send events x-acl: @@ -204,10 +257,12 @@ paths: properties: events: type: array - description: | + description: > Click and conversion events. - **All** events must be valid, otherwise the API returns an error. + + **All** events must be valid, otherwise the API returns an + error. minItems: 1 maxItems: 1000 items: @@ -392,7 +447,13 @@ paths: examples: Success: summary: Events successfully sent to the Insights API - description: Success indicates that the Insights API received the events correctly, and that event properties are formatted correctly. Success doesn't imply that the event can be used by any Algolia feature. For example, the Insights API doesn't check if the index name you provided exists, or if the object IDs exist in your index. + description: >- + Success indicates that the Insights API received the events + correctly, and that event properties are formatted + correctly. Success doesn't imply that the event can be used + by any Algolia feature. For example, the Insights API + doesn't check if the index name you provided exists, or if + the object IDs exist in your index. value: status: 200 message: OK @@ -407,7 +468,9 @@ paths: BadRequest: summary: Bad request description: This error doesn't return a JSON object, but HTML. - value: 'Error: Bad Request. Your client has issued a malformed or illegal request.' + value: >- + Error: Bad Request. Your client has issued a malformed or + illegal request. '401': description: Unauthorized content: @@ -417,7 +480,10 @@ paths: examples: Unauthorized: summary: Invalid credentials - description: You need to provide your application ID using the `X-Algolia-Application-ID` header and your (search) API key with the `X-Algolia-API-Key` header. + description: >- + You need to provide your application ID using the + `X-Algolia-Application-ID` header and your (search) API key + with the `X-Algolia-API-Key` header. value: status: 401 message: Invalid credentials @@ -433,7 +499,11 @@ paths: description: Check that you're using the correct URL. value: status: 404 - message: Path not supported by Insights REST API. Please have a look at [https://www.algolia.com/doc/rest-api/insights/](https://www.algolia.com/doc/rest-api/insights) for the list of valid commands. + message: >- + Path not supported by Insights REST API. Please have a + look at + [https://www.algolia.com/doc/rest-api/insights/](https://www.algolia.com/doc/rest-api/insights) + for the list of valid commands. '405': description: Method Not Allowed. content: @@ -473,16 +543,23 @@ paths: message: Invalid payload NoEvents: summary: No events - description: This can happen if you're sending an empty `events` array, or if you try to send a single event object instead of the `events` array. + description: >- + This can happen if you're sending an empty `events` array, + or if you try to send a single event object instead of the + `events` array. value: status: 422 message: No events to process NoEventsField: summary: Missing events attribute - description: This can happen if you try to send an array of events directly instead of using the `events` attribute. + description: >- + This can happen if you try to send an array of events + directly instead of using the `events` attribute. value: status: 422 - message: 'Invalid type for field : expected insights.PublicEventsBatch, got array' + message: >- + Invalid type for field : expected + insights.PublicEventsBatch, got array EventNameRequired: summary: Missing eventName attribute value: @@ -492,7 +569,9 @@ paths: summary: Event name too long or wrong characters value: status: 422 - message: EventName must contain only visible ASCII characters, and be between 1 and 64 characters long + message: >- + EventName must contain only visible ASCII characters, and + be between 1 and 64 characters long EventTypeRequired: summary: Missing eventType attribute value: @@ -517,10 +596,15 @@ paths: summary: Malformed user token value: status: 422 - message: UserToken must contain only alphanumeric, equal, plus, slash, hyphen, or underscore characters, and be between 1 and 128 characters long + message: >- + UserToken must contain only alphanumeric, equal, plus, + slash, hyphen, or underscore characters, and be between 1 + and 128 characters long NoObjectIDsOrFilters: summary: Missing objectIDs or filters attribute - description: Each event must include either the `objectIDs` or `filters` attribute. + description: >- + Each event must include either the `objectIDs` or `filters` + attribute. value: status: 422 message: Event should specify either some ObjectIDs or some Filters @@ -533,33 +617,50 @@ paths: summary: Wrong combination of positions and eventType attributes value: status: 422 - message: Only event of type click should specify the positions attribute + message: >- + Only event of type click should specify the positions + attribute PositionsWithoutQueryID: summary: Positions attribute without queryID - description: Click events with the `positions` attribute require the `queryID` attribute. + description: >- + Click events with the `positions` attribute require the + `queryID` attribute. value: status: 422 - message: Event of type click with positions should specify a queryID + message: >- + Event of type click with positions should specify a + queryID WrongPositionsValue: summary: Wrong value in positions array description: Any value in the `positions` array must be greater than 0. value: status: 422 - message: Event of type click may only have strictly positive positions + message: >- + Event of type click may only have strictly positive + positions WrongPositionsItems: summary: Wrong number of items in positions array - description: For click events with the `queryID` and `objectIDs` attributes, you must include the `positions` attribute with the same number of items as the `objectIDs` attribute. + description: >- + For click events with the `queryID` and `objectIDs` + attributes, you must include the `positions` attribute with + the same number of items as the `objectIDs` attribute. value: status: 422 - message: Event of type click should have the same number of ObjectIDs and Positions + message: >- + Event of type click should have the same number of + ObjectIDs and Positions WrongQueryID: summary: Malformed query ID value: status: 422 - message: Query ID must be a search query ID (32 characters hexadecimal string) + message: >- + Query ID must be a search query ID (32 characters + hexadecimal string) InvalidDataType: summary: Wrong data type - description: This can happen if one or more attribute is a number instead of a string. + description: >- + This can happen if one or more attribute is a number instead + of a string. value: status: 422 message: 'Invalid type for field events: expected string, got number' @@ -577,13 +678,17 @@ paths: /1/usertokens/{userToken}: delete: tags: - - usertokens + - insights operationId: deleteUserToken summary: Delete user token - description: | - Deletes all events related to the specified user token from events metrics and analytics. + description: > + Deletes all events related to the specified user token from events + metrics and analytics. + The deletion is asynchronous, and processed within 48 hours. - To delete a personalization user profile, see `Delete a user profile` in the Personalization API. + + To delete a personalization user profile, see `Delete a user profile` in + the Personalization API. x-acl: - deleteObject parameters: @@ -610,8 +715,9 @@ paths: schema: $ref: '#/components/schemas/EventsResponse' '429': - description: | - Too Many Requests. This operation is rate-limited. Check the `x-ratelimit-limit` and `x-ratelimit-reset` headers of the response. + description: > + Too Many Requests. This operation is rate-limited. Check the + `x-ratelimit-limit` and `x-ratelimit-reset` headers of the response. content: application/json: schema: @@ -622,7 +728,7 @@ paths: x-asynchronous-helper: false x-acl: [] tags: - - Api Key + - insights operationId: setClientApiKey summary: Switch the API key used to authenticate requests description: | @@ -648,10 +754,14 @@ components: type: apiKey in: header name: x-algolia-api-key - description: | + description: > Your Algolia API key with the necessary permissions to make the request. - Permissions are controlled through access control lists (ACL) and access restrictions. - The required ACL to make a request is listed in each endpoint's reference. + + Permissions are controlled through access control lists (ACL) and access + restrictions. + + The required ACL to make a request is listed in each endpoint's + reference. parameters: PathInPath: name: path @@ -683,11 +793,14 @@ components: minLength: 1 maxLength: 64 pattern: '[\x20-\x7E]{1,64}' - description: | + description: > Event name, up to 64 ASCII characters. + Consider naming events consistently—for example, by adopting Segment's + [object-action](https://segment.com/academy/collecting-data/naming-conventions-for-clean-data/#the-object-action-framework) + framework. ClickEvent: type: string @@ -728,41 +841,57 @@ components: pattern: '[0-9a-f]{32}' minLength: 32 maxLength: 32 - description: | + description: > Unique identifier for a search query. - The query ID is required for events related to search or browse requests. - If you add `clickAnalytics: true` as a search request parameter, the query ID is included in the API response. + + The query ID is required for events related to search or browse + requests. + + If you add `clickAnalytics: true` as a search request parameter, the + query ID is included in the API response. example: 3e48cd0616e466948dd85abf5c3fbbe2 userToken: type: string minLength: 1 maxLength: 129 pattern: '[a-zA-Z0-9_=/+-]{1,129}' - description: | + description: > Anonymous or pseudonymous user identifier. + Don't use personally identifiable information in user tokens. - For more information, see [User token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken). + + For more information, see [User + token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken). example: test-user-1 authenticatedUserToken: type: string minLength: 1 maxLength: 129 pattern: '[a-zA-Z0-9_=/+-]{1,129}' - description: | + description: > Identifier for authenticated users. - When the user signs in, you can get an identifier from your system and send it as `authenticatedUserToken`. - This lets you keep using the `userToken` from before the user signed in, while providing a reliable way to identify users across sessions. + + When the user signs in, you can get an identifier from your system and + send it as `authenticatedUserToken`. + + This lets you keep using the `userToken` from before the user signed in, + while providing a reliable way to identify users across sessions. + Don't use personally identifiable information in user tokens. - For more information, see [User token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken). + + For more information, see [User + token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken). example: c6a52c02-d0c7-4b53-8ce3-2b8fd202f3f9 timestamp: type: integer format: int64 - description: | - Timestamp of the event, measured in milliseconds since the Unix epoch. Must be no older than 30 days. + description: > + Timestamp of the event, measured in milliseconds since the Unix epoch. + Must be no older than 30 days. + If not provided, we use the time at which the request was received. example: 1687193127 ClickedObjectIDsAfterSearch: @@ -817,10 +946,14 @@ components: minLength: 3 maxLength: 3 pattern: ^[A-Za-z]{3}$ - description: Three-letter [currency code](https://www.iso.org/iso-4217-currency-codes.html). + description: >- + Three-letter [currency + code](https://www.iso.org/iso-4217-currency-codes.html). example: EUR price: - description: Final price of a single product, including any discounts, in units of `currency`. + description: >- + Final price of a single product, including any discounts, in units of + `currency`. oneOf: - type: number format: double @@ -831,9 +964,11 @@ components: type: integer format: int32 example: 2 - description: | + description: > Quantity of a product that has been purchased or added to the cart. - The total purchase value is the sum of `quantity` multiplied with the `price` for each purchased item. + + The total purchase value is the sum of `quantity` multiplied with the + `price` for each purchased item. discount: description: Absolute value of the discount for this product, in units of `currency`. oneOf: @@ -851,7 +986,9 @@ components: pattern: '[0-9a-f]{32}' minLength: 32 maxLength: 32 - description: Unique identifier for a search query, used to track purchase events with multiple records that originate from different searches. + description: >- + Unique identifier for a search query, used to track purchase events + with multiple records that originate from different searches. example: 3e48cd0616e466948dd85abf5c3fbbe2 price: $ref: '#/components/schemas/price' @@ -861,8 +998,10 @@ components: $ref: '#/components/schemas/discount' objectDataAfterSearchList: type: array - description: | - Extra information about the records involved in a purchase or add-to-cart events. + description: > + Extra information about the records involved in a purchase or + add-to-cart events. + If provided, it must be the same length as `objectIDs`. items: @@ -883,9 +1022,12 @@ components: AddedToCartObjectIDsAfterSearch: type: object title: Added to cart object IDs after search - description: | - Use this event to track when users add items to their shopping cart after a previous Algolia request. - If you're building your category pages with Algolia, you'll also use this event. + description: > + Use this event to track when users add items to their shopping cart + after a previous Algolia request. + + If you're building your category pages with Algolia, you'll also use + this event. properties: eventName: $ref: '#/components/schemas/eventName' @@ -931,9 +1073,12 @@ components: PurchasedObjectIDsAfterSearch: type: object title: Purchased object IDs after search - description: | - Use this event to track when users make a purchase after a previous Algolia request. - If you're building your category pages with Algolia, you'll also use this event. + description: > + Use this event to track when users make a purchase after a previous + Algolia request. + + If you're building your category pages with Algolia, you'll also use + this event. properties: eventName: $ref: '#/components/schemas/eventName' @@ -973,12 +1118,18 @@ components: ConvertedObjectIDsAfterSearch: type: object title: Converted object IDs after search - description: | - Use this event to track when users convert after a previous Algolia request. - For example, a user clicks on an item in the search results to view the product detail page. + description: > + Use this event to track when users convert after a previous Algolia + request. + + For example, a user clicks on an item in the search results to view the + product detail page. + Then, the user adds the item to their shopping cart. + If you're building your category pages with Algolia, + you'll also use this event. properties: eventName: @@ -1010,11 +1161,16 @@ components: ClickedObjectIDs: type: object title: Clicked object IDs - description: | - Use this event to track when users click items unrelated to a previous Algolia request. - For example, if you don't use Algolia to build your category pages, use this event. + description: > + Use this event to track when users click items unrelated to a previous + Algolia request. + + For example, if you don't use Algolia to build your category pages, use + this event. - To track click events related to Algolia requests, use the "Clicked object IDs after search" event. + + To track click events related to Algolia requests, use the "Clicked + object IDs after search" event. properties: eventName: $ref: '#/components/schemas/eventName' @@ -1051,8 +1207,10 @@ components: $ref: '#/components/schemas/discount' objectDataList: type: array - description: | - Extra information about the records involved in a purchase or add-to-cart event. + description: > + Extra information about the records involved in a purchase or + add-to-cart event. + If specified, it must have the same length as `objectIDs`. items: @@ -1062,10 +1220,14 @@ components: PurchasedObjectIDs: type: object title: Purchased object IDs - description: | - Use this event to track when users make a purchase unrelated to a previous Algolia request. For example, if you don't use Algolia to build your category pages, use this event. + description: > + Use this event to track when users make a purchase unrelated to a + previous Algolia request. For example, if you don't use Algolia to build + your category pages, use this event. + - To track purchase events related to Algolia requests, use the "Purchased object IDs after search" event. + To track purchase events related to Algolia requests, use the "Purchased + object IDs after search" event. properties: eventName: $ref: '#/components/schemas/eventName' @@ -1103,10 +1265,14 @@ components: AddedToCartObjectIDs: type: object title: Added to cart object IDs - description: | - Use this event to track when users add items to their shopping cart unrelated to a previous Algolia request. For example, if you don't use Algolia to build your category pages, use this event. + description: > + Use this event to track when users add items to their shopping cart + unrelated to a previous Algolia request. For example, if you don't use + Algolia to build your category pages, use this event. + - To track add-to-cart events related to Algolia requests, use the "Added to cart object IDs after search" event. + To track add-to-cart events related to Algolia requests, use the "Added + to cart object IDs after search" event. properties: eventName: $ref: '#/components/schemas/eventName' @@ -1144,11 +1310,16 @@ components: ConvertedObjectIDs: type: object title: Converted object IDs - description: | - Use this event to track when users convert on items unrelated to a previous Algolia request. - For example, if you don't use Algolia to build your category pages, use this event. + description: > + Use this event to track when users convert on items unrelated to a + previous Algolia request. + + For example, if you don't use Algolia to build your category pages, use + this event. - To track conversion events related to Algolia requests, use the "Converted object IDs after search" event. + + To track conversion events related to Algolia requests, use the + "Converted object IDs after search" event. properties: eventName: $ref: '#/components/schemas/eventName' @@ -1189,7 +1360,9 @@ components: ClickedFilters: type: object title: Clicked filters - description: Use this event to track when users click facet filters in your user interface. + description: >- + Use this event to track when users click facet filters in your user + interface. properties: eventName: $ref: '#/components/schemas/eventName' @@ -1304,53 +1477,6 @@ components: x-discriminator-fields: - eventType - filters - InstantSearchEvent: - type: string - enum: - - instant-search - sessionID: - type: string - pattern: '[0-9a-f]{32}' - minLength: 32 - maxLength: 32 - description: | - Unique identifier for a session - [TODO]: Document here where this is derived and how it is used - example: 3e48cd0616e466948dd85abf5c3fbbe2 - InstantSearch: - type: object - title: Instant Search - description: | - Tracks an initial user interaction with the Agentic Analytics API - properties: - eventType: - $ref: '#/components/schemas/InstantSearchEvent' - eventName: - $ref: '#/components/schemas/eventName' - sessionID: - $ref: '#/components/schemas/sessionID' - index: - $ref: '#/components/schemas/index' - userToken: - $ref: '#/components/schemas/userToken' - authenticatedUserToken: - $ref: '#/components/schemas/authenticatedUserToken' - timestamp: - $ref: '#/components/schemas/timestamp' - performance: - description: free form object for performance data - type: object - widgets: - description: free form object for widget information - type: object - required: - - eventName - - sessionID - - eventType - - index - - userToken - x-discriminator-fields: - - eventType EventsItems: oneOf: - $ref: '#/components/schemas/ClickedObjectIDsAfterSearch' @@ -1365,7 +1491,6 @@ components: - $ref: '#/components/schemas/ConvertedFilters' - $ref: '#/components/schemas/ViewedObjectIDs' - $ref: '#/components/schemas/ViewedFilters' - - $ref: '#/components/schemas/InstantSearch' EventsResponse: type: object description: The response of the Insights API. @@ -1414,7 +1539,9 @@ components: schema: type: integer x-ratelimit-reset: - description: Timestamp when the rate limit will reset, measured in seconds since the Unix epoch. + description: >- + Timestamp when the rate limit will reset, measured in seconds since the + Unix epoch. example: 1710682486 schema: type: integer From d6b7956807bc4a471e9c8fa43b59dee0142ffec5 Mon Sep 17 00:00:00 2001 From: Dave Sirockin Date: Mon, 30 Mar 2026 11:39:44 +0200 Subject: [PATCH 14/14] chore: remove from all agent fields except --- specs/insights/common/schemas/EventAttributes.yml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/specs/insights/common/schemas/EventAttributes.yml b/specs/insights/common/schemas/EventAttributes.yml index c414be23e03..e65f96916da 100644 --- a/specs/insights/common/schemas/EventAttributes.yml +++ b/specs/insights/common/schemas/EventAttributes.yml @@ -108,12 +108,7 @@ agent: minLength: 1 maxLength: 256 required: - # Although all these fields are specified as optional in the Agentic Analytics document, now that they are grouped, it may - # make sense to make the parent property optional but require all sub properties to be supplied together, as here - - agentID - messageID - - toolCallID - - conversationID positions: type: array items: