diff --git a/.eslintrc.cjs b/.eslintrc.cjs
index dde81581a1..bb9eb6f98d 100644
--- a/.eslintrc.cjs
+++ b/.eslintrc.cjs
@@ -132,6 +132,12 @@ module.exports = {
},
},
],
+ 'jsdoc/match-description':[
+ 'error',
+ {
+ matchDescription: '^\n?([A-Z`\[\\d_][\\s\\S]*[.?!`]\\s*)?$'
+ },
+ ],
},
},
// JS client rules
diff --git a/.github/.cache_version b/.github/.cache_version
index 81340c7e72..bbdeab6222 100644
--- a/.github/.cache_version
+++ b/.github/.cache_version
@@ -1 +1 @@
-0.0.4
+0.0.5
diff --git a/specs/abtesting/common/parameters.yml b/specs/abtesting/common/parameters.yml
index e586f9cf80..6ce0770377 100644
--- a/specs/abtesting/common/parameters.yml
+++ b/specs/abtesting/common/parameters.yml
@@ -2,40 +2,49 @@
ID:
in: path
name: id
- description: The A/B test ID.
+ description: Unique A/B test ID.
required: true
schema:
type: integer
+ example: 390
# misc
index:
type: string
- description: The index performing the A/B test.
+ description: A/B test index.
+ example: 'delcourt_production'
abTestID:
type: integer
- description: The A/B test ID.
+ description: Unique A/B test ID.
+ example: 224
endAt:
type: string
- description: End date for the A/B test expressed as YYYY-MM-DDThh:mm:ssZ.
+ description: End date timestamp in [ISO-8601](https://wikipedia.org/wiki/ISO_8601) format.
+ example: '2023-06-17T00:00:00Z'
createdAt:
type: string
- description: Creation date for the A/B test expressed as YYYY-MM-DDThh:mm:ssZ.
+ description: Creation date timestamp in [ISO-8601](https://wikipedia.org/wiki/ISO_8601) format.
+ example: '2023-06-15T15:06:04.249906Z'
updatedAt:
type: string
- description: Update date for the A/B test expressed as YYYY-MM-DDThh:mm:ssZ.
+ description: Update date timestamp in [ISO-8601](https://wikipedia.org/wiki/ISO_8601) format.
+ example: '2023-06-15T15:06:44.400601Z'
name:
type: string
description: A/B test name.
+ example: 'Custom ranking sales rank test'
description:
type: string
- description: The A/B test description.
+ description: A/B test description.
+ example: 'Current production index'
trafficPercentage:
type: integer
- description: The traffic percentage for the A/B test.
+ description: A/B test traffic percentage.
+ example: 60
diff --git a/specs/abtesting/common/schemas/ABTest.yml b/specs/abtesting/common/schemas/ABTest.yml
index ed2b7d9c35..7b3693484f 100644
--- a/specs/abtesting/common/schemas/ABTest.yml
+++ b/specs/abtesting/common/schemas/ABTest.yml
@@ -1,6 +1,6 @@
ABTests:
type: array
- description: List of A/B tests.
+ description: A/B tests.
items:
$ref: '#/ABTest'
@@ -13,12 +13,14 @@ ABTest:
clickSignificance:
type: number
format: double
- description: A/B test significance based on click data. Should be > 0.95 to be considered significant (no matter which variant is winning).
+ description: >
+ [A/B test significance](https://www.algolia.com/doc/guides/ab-testing/what-is-ab-testing/in-depth/how-ab-test-scores-are-calculated/#statistical-significance-or-chance) based on click data. A value of 0.95 or over is considered to be _significant_.
+ example: 1
conversionSignificance:
type: number
format: double
- description: A/B test significance based on conversion data. Should be > 0.95 to be considered significant (no matter which variant is winning).
- endAt:
+ description: >
+ [A/B test significance](https://www.algolia.com/doc/guides/ab-testing/what-is-ab-testing/in-depth/how-ab-test-scores-are-calculated/#statistical-significance-or-chance) based on conversion. A value of 0.95 or over is considered to be _significant_.
$ref: '../parameters.yml#/endAt'
updatedAt:
$ref: '../parameters.yml#/updatedAt'
@@ -28,7 +30,8 @@ ABTest:
$ref: '../parameters.yml#/name'
status:
type: string
- description: status of the A/B test.
+ description: A/B test status.
+ example: 'running'
variants:
$ref: 'Variant.yml#/variants'
required:
diff --git a/specs/abtesting/common/schemas/AddABTestsVariant.yml b/specs/abtesting/common/schemas/AddABTestsVariant.yml
index 6a4ca55e68..f42056c51c 100644
--- a/specs/abtesting/common/schemas/AddABTestsVariant.yml
+++ b/specs/abtesting/common/schemas/AddABTestsVariant.yml
@@ -24,6 +24,8 @@ abTestsVariant:
customSearchParams:
type: object
+ description: Applies search parameters from [a restricted set of options](https://www.algolia.com/doc/api-reference/api-methods/add-ab-test/#method-param-customsearchparameters). Only use this parameter if the two variants use the same index.
+ example: {'typoTolerance': false,'synonyms': false}
additionalProperties: false
properties:
customSearchParameters:
diff --git a/specs/abtesting/common/schemas/Variant.yml b/specs/abtesting/common/schemas/Variant.yml
index 9f3d92ca7f..80cfd106a6 100644
--- a/specs/abtesting/common/schemas/Variant.yml
+++ b/specs/abtesting/common/schemas/Variant.yml
@@ -1,6 +1,6 @@
variants:
type: array
- description: List of A/B test variant.
+ description: A/B test variants.
items:
$ref: '#/variant'
@@ -10,43 +10,54 @@ variant:
properties:
averageClickPosition:
type: integer
- description: Average click position for the variant.
+ description: Variant's [average click position](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#click-position).
+ example: 0
clickCount:
type: integer
- description: Distinct click count for the variant.
+ description: Number of click events for this variant.
+ example: 65131
clickThroughRate:
type: number
format: double
- description: Click through rate for the variant.
+ description: Variant's [click-through rate](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#click-through-rate).
+ example: 0.22219857724813036
conversionCount:
type: integer
- description: Distinct conversion count for the variant.
+ description: Number of click events for this variant.
+ example: 4785
conversionRate:
type: number
format: double
- description: Conversion rate for the variant.
+ description: Variant's [conversion rate](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#conversion-rate).
+ example: 0.14546725846658964
description:
$ref: '../parameters.yml#/description'
index:
$ref: '../parameters.yml#/index'
noResultCount:
- $ref: '../../../common/parameters.yml#/count'
+ type: integer
+ description: Number of [searches without results](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#searches-without-results) for that variant.
+ example: 0
outlierTrackedSearchesCount:
type: integer
- description: Count of the tracked searches attributed to outlier traffic that were removed from the A/B test.
+ description: Number of tracked searches attributed to [outlier traffic](https://www.algolia.com/doc/guides/ab-testing/how-to-read-your-a-b-test-results/#is-the-split-off) that were removed from the A/B test. A _tracked_ search is a search request where the `clickAnalytics` parameter is `true`.
+ example: 0
outlierUsersCount:
type: integer
- description: Count of users attributed to outlier traffic that were removed from the A/B test.
+ description: Number of users attributed to [outlier traffic](https://www.algolia.com/doc/guides/ab-testing/how-to-read-your-a-b-test-results/#is-the-split-off) that were removed from the A/B test.
+ example: 0
searchCount:
type: integer
- description: The number of search during the A/B test.
+ description: Number of searches carried out during the A/B test.
+ example: 86269
trackedSearchCount:
$ref: '../../../common/parameters.yml#/trackedSearchCount'
trafficPercentage:
$ref: '../parameters.yml#/trafficPercentage'
userCount:
type: integer
- description: The number of user during the A/B test.
+ description: Number of users during the A/B test.
+ example: 55501
required:
- userCount
- trafficPercentage
diff --git a/specs/abtesting/paths/abtest.yml b/specs/abtesting/paths/abtest.yml
index 22bbfcb4ab..f0b29afae3 100644
--- a/specs/abtesting/paths/abtest.yml
+++ b/specs/abtesting/paths/abtest.yml
@@ -2,9 +2,11 @@ get:
tags:
- abtest
operationId: getABTest
- summary: Get a test.
+ summary: Get A/B test details.
description: >
- Returns metadata and metrics for an A/B test.
+ Get specific details for an A/B test.
+
+ To determine the `id` for an A/B test, use the [`listABTests` operation](#tag/abtest/operation/listABTests).
parameters:
- $ref: '../common/parameters.yml#/ID'
responses:
@@ -27,8 +29,11 @@ delete:
tags:
- abtest
operationId: deleteABTest
- summary: Delete a test.
- description: Delete a test.
+ summary: Delete an A/B test.
+ description: >
+ Delete an A/B test.
+
+ To determine the `id` for an A/B test, use the [`listABTests` operation](#tag/abtest/operation/listABTests).
parameters:
- $ref: '../common/parameters.yml#/ID'
responses:
diff --git a/specs/abtesting/paths/abtests.yml b/specs/abtesting/paths/abtests.yml
index 76008d2790..5526782a91 100644
--- a/specs/abtesting/paths/abtests.yml
+++ b/specs/abtesting/paths/abtests.yml
@@ -2,11 +2,8 @@ post:
tags:
- abtest
operationId: addABTests
- summary: Create a test.
- description: >
- Creates a new A/B test with provided configuration.
-
- You can set an A/B test on two different indices with different settings, or on the same index with different search parameters by providing a customSearchParameters setting on one of the variants.
+ summary: Create an A/B test.
+ description: Creates an A/B test.
requestBody:
required: true
content:
@@ -18,9 +15,9 @@ post:
properties:
name:
$ref: '../common/parameters.yml#/name'
- variant:
+ variants:
type: array
- description: List of 2 variants for the A/B test.
+ description: A/B test variants.
minItems: 2
maxItems: 2
items:
@@ -29,7 +26,7 @@ post:
$ref: '../common/parameters.yml#/endAt'
required:
- name
- - variant
+ - variants
- endAt
responses:
'200':
@@ -51,22 +48,21 @@ get:
tags:
- abtest
operationId: listABTests
- summary: List all tests.
- description: >
- Fetch all existing A/B tests for App that are available for the current API Key.
-
- When no data has been processed, the metrics will be returned as null.
+ summary: List all A/B tests.
+ description: List all A/B tests.
parameters:
- $ref: '../../common/parameters.yml#/Offset'
- $ref: '../../common/parameters.yml#/Limit'
- name: indexPrefix
in: query
- description: Filters the returned ab tests by any indices starting with the provided prefix that are assigned to either variant of an ab test.
+ description: Only return A/B tests for indices starting with this prefix.
+ example: 'dev_'
schema:
type: string
- name: indexSuffix
in: query
- description: Filters the returned ab tests by any indices ending with the provided suffix that are assigned to either variant of an ab test.
+ description: Only return A/B tests for indices ending with this suffix.
+ example: '_development'
schema:
type: string
responses:
@@ -83,10 +79,12 @@ get:
$ref: '../common/schemas/ABTest.yml#/ABTests'
count:
type: integer
- description: Number of A/B tests found for the app.
+ description: Number of A/B tests implemented.
+ example: 10
total:
type: integer
- description: Number of A/B tests retrievable.
+ description: Number of retrievable A/B tests.
+ example: 12
required:
- abtests
- count
diff --git a/specs/abtesting/paths/stopABTest.yml b/specs/abtesting/paths/stopABTest.yml
index 8282c94810..d9ebe72152 100644
--- a/specs/abtesting/paths/stopABTest.yml
+++ b/specs/abtesting/paths/stopABTest.yml
@@ -2,13 +2,14 @@ post:
tags:
- abtest
operationId: stopABTest
- summary: Stop a test.
+ summary: Stop an A/B test.
description: >
- Marks the A/B test as stopped.
+ If stopped, the test is over and can't be restarted.
+ There is now only one index, receiving 100% of all search requests.
+
+ The data gathered for stopped A/B tests is retained.
- At this point, the test is over and cannot be restarted.
- As a result, your application is back to normal: index A will perform as usual, receiving 100% of all search requests.
- Associated metadata and metrics are still stored.
+ To determine the `id` for an A/B test, use the [`listABTests` operation](#tag/abtest/operation/listABTests).
parameters:
- $ref: '../common/parameters.yml#/ID'
responses:
diff --git a/specs/abtesting/spec.yml b/specs/abtesting/spec.yml
index 3a70308d95..88b4d73b45 100644
--- a/specs/abtesting/spec.yml
+++ b/specs/abtesting/spec.yml
@@ -23,8 +23,8 @@ security:
apiKey: []
tags:
- name: abtest
- x-displayName: A/B Testing
- description: Manage A/B Tests.
+ x-displayName: A/B testing
+ description: Manage A/B tests.
x-tagGroups:
- name: General
tags:
diff --git a/specs/analytics/common/parameters.yml b/specs/analytics/common/parameters.yml
index eeb777a176..301443627e 100644
--- a/specs/analytics/common/parameters.yml
+++ b/specs/analytics/common/parameters.yml
@@ -2,10 +2,11 @@
Attribute:
in: path
name: attribute
- description: The exact name of the attribute.
+ description: Attribute name.
required: true
schema:
type: string
+ example: 'brand'
# query
OrderBy:
@@ -18,13 +19,18 @@ OrderBy:
# private
orderBy:
type: string
+ description: >
+ Method for ordering results.
+
+ `clickThroughRate`, `conversionRate` and `averageClickPosition` are only available if the `clickAnalytics` parameter is `true`.
enum: [searchCount, clickThroughRate, conversionRate, averageClickPosition]
default: searchCount
Direction:
in: query
name: direction
- description: The sorting of the result.
+ description: >
+ Sorting direction of the results: ascending or descending.
schema:
$ref: '#/direction'
@@ -37,22 +43,34 @@ direction:
ClickAnalytics:
in: query
name: clickAnalytics
- description: Whether to include the click-through and conversion rates for a search.
+ description: Whether to include [click and conversion](https://www.algolia.com/doc/guides/sending-events/getting-started/) rates for a search.
schema:
type: boolean
default: false
+count:
+ description: Number of tracked _and_ untracked searches (where the `clickAnalytics` parameter isn't `true`).
+ type: integer
+ example: 504
+
+noResultCount:
+ description: Number of occurences.
+ type: integer
+ example: 54
+
Search:
in: query
name: search
- description: The query term to search for. Must match the exact user input.
+ description: User query.
+ example: 'enable ab test'
schema:
type: string
Tags:
name: tags
in: query
- description: Filter metrics on the provided tags. Each tag must correspond to an analyticsTags set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it should be URL encoded.
+ description: Filter analytics on the [`analyticsTags`](https://www.algolia.com/doc/api-reference/api-parameters/analyticsTags/) set at search time. Multiple tags can be combined with the operators OR and AND. If a tag contains characters like spaces or parentheses, it must be URL-encoded.
+ example: 'device:mobile%20phone'
schema:
type: string
@@ -60,50 +78,66 @@ Tags:
average:
type: number
format: double
- description: The average of all the click count event.
+ description: Average count of all click events.
+ example: 2.3344634550185286
averageClickPosition:
type: integer
- description: The average position of all the click count event.
+ description: Average [position](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#click-position) of clicked search result.
+ example: 1
clickCount:
type: integer
- description: The number of click event.
+ description: Number of click events.
+ example: 162
date:
type: string
- description: Date of the event.
+ description: Date of the event in the format YYYY-MM-DD.
+ example: '2023-06-14'
rate:
type: number
format: double
- description: The click-through rate.
+ description: >
+ [Click-through rate (CTR)](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#click-through-rate).
+ minimum: 0
+ maximum: 1
+ example: 0.14634193523426317
conversionRate:
type: number
format: double
- description: The conversion rate.
+ description: >
+ [Conversion rate (CR)](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#conversion-rate).
+ example: 0
conversionCount:
type: integer
- description: The number of converted clicks.
+ description: Number of converted clicks.
+ example: 0
attribute:
- description: The attribute.
+ description: Attribute name.
type: string
+ example: 'url'
operator:
- description: The operator.
+ description: Operator.
type: string
+ example: ':'
value:
- description: The value of the attribute.
+ description: Attribute value.
type: string
+ example: 'integration'
search:
- description: The search query.
+ description: User query.
+ example: 'separator'
type: string
hit:
- description: The hit.
+ description: Hit.
type: string
+ example: 'method-export-rules-php'
diff --git a/specs/analytics/common/schemas/getTopFilterAttributes.yml b/specs/analytics/common/schemas/getTopFilterAttributes.yml
index 87969243ea..78c50e177d 100644
--- a/specs/analytics/common/schemas/getTopFilterAttributes.yml
+++ b/specs/analytics/common/schemas/getTopFilterAttributes.yml
@@ -6,7 +6,7 @@ getTopFilterAttributesResponse:
properties:
attributes:
type: array
- description: A list of attributes with their count.
+ description: Filterable attributes.
items:
$ref: '#/getTopFilterAttribute'
diff --git a/specs/analytics/common/schemas/getTopFilterForAttribute.yml b/specs/analytics/common/schemas/getTopFilterForAttribute.yml
index 6e4e1deb5c..fd13268619 100644
--- a/specs/analytics/common/schemas/getTopFilterForAttribute.yml
+++ b/specs/analytics/common/schemas/getTopFilterForAttribute.yml
@@ -6,7 +6,7 @@ getTopFilterForAttributeResponse:
properties:
values:
type: array
- description: A list of filters for the given attributes.
+ description: Filter values for an attribute.
items:
$ref: '#/getTopFilterForAttribute'
diff --git a/specs/analytics/common/schemas/getTopFiltersNoResults.yml b/specs/analytics/common/schemas/getTopFiltersNoResults.yml
index feb83cb4a0..d05af27eb1 100644
--- a/specs/analytics/common/schemas/getTopFiltersNoResults.yml
+++ b/specs/analytics/common/schemas/getTopFiltersNoResults.yml
@@ -6,7 +6,7 @@ getTopFiltersNoResultsResponse:
properties:
values:
type: array
- description: A list of filters without results.
+ description: Filters with no results.
items:
$ref: '#/getTopFiltersNoResultsValues'
@@ -21,7 +21,7 @@ getTopFiltersNoResultsValues:
$ref: '../../../common/parameters.yml#/count'
values:
type: array
- description: A list of filters without results.
+ description: Filters with no results.
items:
$ref: '#/getTopFiltersNoResultsValue'
diff --git a/specs/analytics/common/schemas/getTopHits.yml b/specs/analytics/common/schemas/getTopHits.yml
index 3233d54c78..5f2477441d 100644
--- a/specs/analytics/common/schemas/getTopHits.yml
+++ b/specs/analytics/common/schemas/getTopHits.yml
@@ -6,7 +6,7 @@ topHitsResponse:
properties:
hits:
type: array
- description: A list of top hits with their count.
+ description: Top hits.
items:
type: object
title: topHit
@@ -28,7 +28,7 @@ topHitsResponseWithAnalytics:
properties:
hits:
type: array
- description: A list of top hits with their count and analytics.
+ description: Top hits.
items:
type: object
title: topHitWithAnalytics
diff --git a/specs/analytics/common/schemas/getTopSearches.yml b/specs/analytics/common/schemas/getTopSearches.yml
index 98b2555eab..8ece553117 100644
--- a/specs/analytics/common/schemas/getTopSearches.yml
+++ b/specs/analytics/common/schemas/getTopSearches.yml
@@ -6,7 +6,7 @@ topSearchesResponse:
properties:
searches:
type: array
- description: A list of top searches with their count.
+ description: Top searches with their hits count.
items:
type: object
title: topSearch
@@ -19,7 +19,7 @@ topSearchesResponse:
search:
$ref: '../parameters.yml#/search'
count:
- $ref: '../../../common/parameters.yml#/count'
+ $ref: '../parameters.yml#/count'
nbHits:
$ref: '../../../search/common/schemas/SearchResponse.yml#/nbHits'
@@ -31,7 +31,7 @@ topSearchesResponseWithAnalytics:
properties:
searches:
type: array
- description: A list of top searches with their count and analytics.
+ description: Top searches with their hits count and analytics.
items:
type: object
title: topSearchWithAnalytics
@@ -50,7 +50,7 @@ topSearchesResponseWithAnalytics:
search:
$ref: '../parameters.yml#/search'
count:
- $ref: '../../../common/parameters.yml#/count'
+ $ref: '../parameters.yml#/count'
clickThroughRate:
$ref: '../parameters.yml#/rate'
averageClickPosition:
diff --git a/specs/analytics/paths/click/getAverageClickPosition.yml b/specs/analytics/paths/click/getAverageClickPosition.yml
index ec93eb5dc1..6d0ea7e459 100644
--- a/specs/analytics/paths/click/getAverageClickPosition.yml
+++ b/specs/analytics/paths/click/getAverageClickPosition.yml
@@ -3,7 +3,10 @@ get:
- click
operationId: getAverageClickPosition
summary: Get average click position.
- description: Returns the average click position. The endpoint returns a value for the complete given time range, as well as a value per day.
+ description: >
+ Return the average click position for the complete time range and for individual days.
+
+ > **Note**: If all `positions` have a `clickCount` of `0` or `null`, it means Algolia didn't receive any click events for tracked searches. A _tracked_ search is a search request where the `clickAnalytics` parameter is `true`.
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../../common/parameters.yml#/StartDate'
@@ -29,7 +32,7 @@ get:
$ref: '../../common/parameters.yml#/clickCount'
dates:
type: array
- description: A list of average click position with their date.
+ description: Average click positions.
items:
type: object
title: averageClickEvent
diff --git a/specs/analytics/paths/click/getClickPositions.yml b/specs/analytics/paths/click/getClickPositions.yml
index 8295ef882f..af901bfecf 100644
--- a/specs/analytics/paths/click/getClickPositions.yml
+++ b/specs/analytics/paths/click/getClickPositions.yml
@@ -2,12 +2,12 @@ get:
tags:
- click
operationId: getClickPositions
- summary: Get clicks per positions.
+ summary: Get click positions.
description: |
- Returns the distribution of clicks per range of positions.
+ Show the number of clicks events and their associated position in the search results.
+
+ > **Note**: If all `positions` have a `clickCount` of `0` or `null`, it means Algolia didn't receive any click events for tracked searches. A _tracked_ search is a search request where the `clickAnalytics` parameter is `true`.
- If the groups all have a count of 0, it means Algolia didn’t receive any click events for the queries with the clickAnalytics search parameter set to true.
- The count is 0 until Algolia receives at least one click event.
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../../common/parameters.yml#/StartDate'
@@ -27,7 +27,7 @@ get:
properties:
positions:
type: array
- description: A list of the click positions with their click count.
+ description: Click positions.
minItems: 2
maxItems: 2
items:
@@ -42,12 +42,11 @@ get:
description: >
Range of positions with the following pattern:
- - Positions from 1 to 10 included are displayed in separated groups.
-
- - Positions from 11 to 20 included are grouped together.
-
- - Positions from 21 and up are grouped together.
+ - For positions 1 to 10, the number of click events are shown for each position
+ - For positions 11 to 20, all click events are grouped
+ - For positions 21 and up, all click events are grouped.
type: array
+ example: [10,10]
items:
type: integer
clickCount:
diff --git a/specs/analytics/paths/click/getClickThroughRate.yml b/specs/analytics/paths/click/getClickThroughRate.yml
index 2f53179735..3f750e0111 100644
--- a/specs/analytics/paths/click/getClickThroughRate.yml
+++ b/specs/analytics/paths/click/getClickThroughRate.yml
@@ -3,7 +3,7 @@ get:
- click
operationId: getClickThroughRate
summary: Get click-through rate (CTR).
- description: Returns a click-through rate (CTR). The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of clicks and searches used to compute the rates.
+ description: Returns a [click-through rate (CTR)](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#click-through-rate).
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../../common/parameters.yml#/StartDate'
@@ -32,7 +32,7 @@ get:
$ref: '../../../common/parameters.yml#/trackedSearchCount'
dates:
type: array
- description: A list of click-through rate events with their date.
+ description: Click-through rate events.
items:
type: object
title: clickThroughRateEvent
diff --git a/specs/analytics/paths/click/getConversionRate.yml b/specs/analytics/paths/click/getConversionRate.yml
index 69e8c416ac..525c32f11f 100644
--- a/specs/analytics/paths/click/getConversionRate.yml
+++ b/specs/analytics/paths/click/getConversionRate.yml
@@ -3,7 +3,7 @@ get:
- click
operationId: getConversationRate
summary: Get conversion rate (CR).
- description: Returns a conversion rate (CR). The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of conversion and searches used to compute the rates.
+ description: Return a [conversion rate](https://www.algolia.com/doc/guides/search-analytics/concepts/metrics/#conversion-rate).
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../../common/parameters.yml#/StartDate'
@@ -32,7 +32,7 @@ get:
$ref: '../../common/parameters.yml#/conversionCount'
dates:
type: array
- description: A list of conversion events with their date.
+ description: Conversion events.
items:
type: object
title: conversionRateEvent
diff --git a/specs/analytics/paths/search/getNoClickRate.yml b/specs/analytics/paths/search/getNoClickRate.yml
index 519b98de78..32f6ea4ad7 100644
--- a/specs/analytics/paths/search/getNoClickRate.yml
+++ b/specs/analytics/paths/search/getNoClickRate.yml
@@ -3,7 +3,7 @@ get:
- search
operationId: getNoClickRate
summary: Get no click rate.
- description: Returns the rate at which searches didn't lead to any clicks. The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of searches and searches without clicks.
+ description: Returns the rate at which searches don't lead to any clicks. The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of searches and searches without clicks.
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../../common/parameters.yml#/StartDate'
@@ -32,7 +32,7 @@ get:
$ref: '../../common/parameters.yml#/clickCount'
dates:
type: array
- description: A list of searches without clicks with their date, rate and counts.
+ description: Overall count of searches without clicks plus a daily breakdown.
items:
type: object
title: noClickRateEvent
@@ -46,7 +46,7 @@ get:
rate:
$ref: '../../common/parameters.yml#/rate'
count:
- $ref: '../../common/parameters.yml#/clickCount'
+ $ref: '../../common/parameters.yml#/count'
noClickCount:
$ref: '../../common/parameters.yml#/clickCount'
date:
diff --git a/specs/analytics/paths/search/getNoResultsRate.yml b/specs/analytics/paths/search/getNoResultsRate.yml
index 8600334859..98b6f92387 100644
--- a/specs/analytics/paths/search/getNoResultsRate.yml
+++ b/specs/analytics/paths/search/getNoResultsRate.yml
@@ -3,7 +3,7 @@ get:
- search
operationId: getNoResultsRate
summary: Get no results rate.
- description: Returns the rate at which searches didn't return any results. The endpoint returns a value for the complete given time range, as well as a value per day. It also returns the count of searches and searches without results used to compute the rates.
+ description: Returns the rate at which searches didn't return any results.
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../../common/parameters.yml#/StartDate'
@@ -32,7 +32,7 @@ get:
$ref: '../../../common/parameters.yml#/count'
dates:
type: array
- description: A list of searches without results with their date, rate and counts.
+ description: Overall count of searches without results plus a daily breakdown.
items:
type: object
title: noResultsRateEvent
@@ -46,9 +46,9 @@ get:
date:
$ref: '../../common/parameters.yml#/date'
noResultCount:
- $ref: '../../../common/parameters.yml#/count'
+ $ref: '../../common/parameters.yml#/noResultCount'
count:
- $ref: '../../../common/parameters.yml#/count'
+ $ref: '../../common/parameters.yml#/count'
rate:
$ref: '../../common/parameters.yml#/rate'
'400':
diff --git a/specs/analytics/paths/search/getSearchesCount.yml b/specs/analytics/paths/search/getSearchesCount.yml
index 48c112e035..1cad7e1905 100644
--- a/specs/analytics/paths/search/getSearchesCount.yml
+++ b/specs/analytics/paths/search/getSearchesCount.yml
@@ -2,8 +2,8 @@ get:
tags:
- search
operationId: getSearchesCount
- summary: Get searches count.
- description: Returns the number of searches across the given time range. The endpoint returns a value for the complete given time range, as well as a value per day.
+ summary: Get number of searches.
+ description: Returns the number of searches within a time range.
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../../common/parameters.yml#/StartDate'
@@ -26,7 +26,7 @@ get:
$ref: '../../../common/parameters.yml#/count'
dates:
type: array
- description: A list of search events with their date and count.
+ description: Search events with their associated dates and hit counts.
items:
type: object
title: searchEvent
diff --git a/specs/analytics/paths/search/getSearchesNoClicks.yml b/specs/analytics/paths/search/getSearchesNoClicks.yml
index 1b8fbf204f..e4dbcecacd 100644
--- a/specs/analytics/paths/search/getSearchesNoClicks.yml
+++ b/specs/analytics/paths/search/getSearchesNoClicks.yml
@@ -3,7 +3,7 @@ get:
- search
operationId: getSearchesNoClicks
summary: Get top searches with no clicks.
- description: Returns top searches that didn't lead to any clicks. Limited to the 1000 most frequent ones. For each search, also returns the average number of found hits.
+ description: Return the most popular of the last 1,000 searches that didn't lead to any clicks.
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../../common/parameters.yml#/StartDate'
@@ -25,7 +25,7 @@ get:
properties:
searches:
type: array
- description: A list of searches with no clicks and their count.
+ description: Searches with no clicks.
items:
type: object
title: searchNoClickEvent
diff --git a/specs/analytics/paths/search/getSearchesNoResults.yml b/specs/analytics/paths/search/getSearchesNoResults.yml
index acaeae6d5e..8caefee69d 100644
--- a/specs/analytics/paths/search/getSearchesNoResults.yml
+++ b/specs/analytics/paths/search/getSearchesNoResults.yml
@@ -3,7 +3,7 @@ get:
- search
operationId: getSearchesNoResults
summary: Get top searches with no results.
- description: Returns top searches that didn't return any results. Limited to the 1000 most frequent ones.
+ description: Returns the most popular of the latest 1,000 searches that didn't return any results.
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../../common/parameters.yml#/StartDate'
@@ -25,7 +25,7 @@ get:
properties:
searches:
type: array
- description: A list of searches with no results and their count.
+ description: Searches with no results.
items:
type: object
title: searchNoResultEvent
diff --git a/specs/analytics/paths/search/getTopCountries.yml b/specs/analytics/paths/search/getTopCountries.yml
index 035d7f9f6c..f89f72d157 100644
--- a/specs/analytics/paths/search/getTopCountries.yml
+++ b/specs/analytics/paths/search/getTopCountries.yml
@@ -3,7 +3,7 @@ get:
- search
operationId: getTopCountries
summary: Get top countries.
- description: Returns top countries. Limited to the 1000 most frequent ones.
+ description: Returns top countries. Limited to the 1,000 most frequent ones.
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../../common/parameters.yml#/StartDate'
@@ -25,7 +25,7 @@ get:
properties:
countries:
type: array
- description: A list of countries with their count.
+ description: Countries
items:
type: object
title: topCountry
@@ -35,8 +35,9 @@ get:
- count
properties:
country:
- description: The country.
+ description: Country.
type: string
+ example: 'UK'
count:
$ref: '../../../common/parameters.yml#/count'
'400':
diff --git a/specs/analytics/paths/search/getTopFilterAttributes.yml b/specs/analytics/paths/search/getTopFilterAttributes.yml
index c8081ac052..e093947bd6 100644
--- a/specs/analytics/paths/search/getTopFilterAttributes.yml
+++ b/specs/analytics/paths/search/getTopFilterAttributes.yml
@@ -2,8 +2,8 @@ get:
tags:
- search
operationId: getTopFilterAttributes
- summary: Get top filter attributes.
- description: Returns top filter attributes. Limited to the 1000 most used filters.
+ summary: Get top filterable attributes.
+ description: Return the most popular [filterable attributes](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/) in the 1,000 most recently used filters.
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../common/parameters.yml#/Search'
diff --git a/specs/analytics/paths/search/getTopFilterForAttribute.yml b/specs/analytics/paths/search/getTopFilterForAttribute.yml
index 08b46e0a5c..8bfc463e85 100644
--- a/specs/analytics/paths/search/getTopFilterForAttribute.yml
+++ b/specs/analytics/paths/search/getTopFilterForAttribute.yml
@@ -2,8 +2,8 @@ get:
tags:
- search
operationId: getTopFilterForAttribute
- summary: Get top filters for the an attribute.
- description: Returns top filters for the given attribute. Limited to the 1000 most used filters.
+ summary: Get top filter values for an attribute.
+ description: Returns the most popular filter values for an attribute in the 1,000 most recently used filters.
parameters:
- $ref: '../../common/parameters.yml#/Attribute'
- $ref: '../../../common/parameters.yml#/Index'
diff --git a/specs/analytics/paths/search/getTopFiltersNoResults.yml b/specs/analytics/paths/search/getTopFiltersNoResults.yml
index 370659005b..c88372d389 100644
--- a/specs/analytics/paths/search/getTopFiltersNoResults.yml
+++ b/specs/analytics/paths/search/getTopFiltersNoResults.yml
@@ -3,7 +3,7 @@ get:
- search
operationId: getTopFiltersNoResults
summary: Get top filters for a no result search.
- description: Returns top filters with no results. Limited to the 1000 most used filters.
+ description: Returns top filters for filter-enabled searches that don't return results. Limited to the 1,000 most recently used filters.
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../common/parameters.yml#/Search'
diff --git a/specs/analytics/paths/search/getTopHits.yml b/specs/analytics/paths/search/getTopHits.yml
index 6c90fa1502..78a5b9fea0 100644
--- a/specs/analytics/paths/search/getTopHits.yml
+++ b/specs/analytics/paths/search/getTopHits.yml
@@ -3,7 +3,7 @@ get:
- search
operationId: getTopHits
summary: Get top hits.
- description: Returns top hits. Limited to the 1000 most frequent ones.
+ description: Return the most popular clicked results in the last 1,000 searches.
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../common/parameters.yml#/Search'
diff --git a/specs/analytics/paths/search/getTopSearches.yml b/specs/analytics/paths/search/getTopSearches.yml
index 649d685fd6..ca7cfcac06 100644
--- a/specs/analytics/paths/search/getTopSearches.yml
+++ b/specs/analytics/paths/search/getTopSearches.yml
@@ -3,7 +3,7 @@ get:
- search
operationId: getTopSearches
summary: Get top searches.
- description: Returns top searches. Limited to the 1000 most frequent ones. For each search, also returns the average number of hits returned.
+ description: Returns the most popular of the latest 1,000 searches. For each search, also returns the number of hits.
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../common/parameters.yml#/ClickAnalytics'
diff --git a/specs/analytics/paths/search/getUsersCount.yml b/specs/analytics/paths/search/getUsersCount.yml
index 42245d1040..d20c70f376 100644
--- a/specs/analytics/paths/search/getUsersCount.yml
+++ b/specs/analytics/paths/search/getUsersCount.yml
@@ -2,8 +2,8 @@ get:
tags:
- search
operationId: getUsersCount
- summary: Get users count.
- description: Returns the distinct count of users across the given time range. The endpoint returns a value for the complete given time range, as well as a value per day.
+ summary: Get user count.
+ description: Return the count of unique users.
parameters:
- $ref: '../../../common/parameters.yml#/Index'
- $ref: '../../../common/parameters.yml#/StartDate'
@@ -26,7 +26,7 @@ get:
$ref: '../../../common/parameters.yml#/count'
dates:
type: array
- description: A list of users count with their date.
+ description: User count.
items:
type: object
title: userWithDate
diff --git a/specs/analytics/paths/status/getStatus.yml b/specs/analytics/paths/status/getStatus.yml
index 2a926df914..74ba2fa704 100644
--- a/specs/analytics/paths/status/getStatus.yml
+++ b/specs/analytics/paths/status/getStatus.yml
@@ -3,7 +3,10 @@ get:
- advanced
operationId: getStatus
summary: Get Analytics API status.
- description: Returns the latest update time of the analytics API for a given index. If the index has been recently created and/or no search has been performed yet the updated time will be null.
+ description: >
+ Return the latest update time of the Analytics API for an index. If the index has been recently created or no search has been performed yet, `updatedAt` will be `null`.
+
+ > **Note**: The Analytics API is updated every 5 minutes.
parameters:
- $ref: '../../../common/parameters.yml#/Index'
responses:
diff --git a/specs/analytics/spec.yml b/specs/analytics/spec.yml
index ceaeab656b..ca7f90e5ca 100644
--- a/specs/analytics/spec.yml
+++ b/specs/analytics/spec.yml
@@ -1,7 +1,10 @@
openapi: 3.0.2
info:
title: Analytics API
- description: API powering the Analytics feature of Algolia.
+ description: >
+ The Analytics API lets you review your search, and click and conversion analytics.
+
+ > **Note**: The API key in the `X-Algolia-API-Key` header requires the [`analytics` ACL](https://www.algolia.com/doc/guides/security/api-keys/#access-control-list-acl).
version: 1.0.0
components:
securitySchemes:
diff --git a/specs/common/parameters.yml b/specs/common/parameters.yml
index b08f45415b..c61369d0fc 100644
--- a/specs/common/parameters.yml
+++ b/specs/common/parameters.yml
@@ -2,7 +2,7 @@
IndexName:
name: indexName
in: path
- description: The index in which to perform the request.
+ description: Index on which to perform the request.
required: true
schema:
type: string
@@ -11,7 +11,7 @@ IndexName:
ObjectID:
name: objectID
in: path
- description: Unique identifier of an object.
+ description: Unique record (object) identifier.
required: true
schema:
type: string
@@ -21,58 +21,63 @@ ObjectID:
Index:
in: query
name: index
- description: The index name to target.
+ description: Index name to target.
required: true
schema:
type: string
+ example: YourIndexName
StartDate:
in: query
name: startDate
- description: The lower bound timestamp (a date, a string like "2006-01-02") of the period to analyze.
+ description: Start date (a string in the format `YYYY-MM-DD`) of the period to analyze.
schema:
type: string
- example: 1999-09-19
+ example: 2022-09-19
pattern: ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$
EndDate:
in: query
name: endDate
- description: The upper bound timestamp (a date, a string like "2006-01-02") of the period to analyze.
+ description: End date (a string in the format `YYYY-MM-DD`) of the period to analyze.
schema:
type: string
- example: 2000-01-21
+ example: 2023-01-21
pattern: ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$
ForwardToReplicas:
in: query
name: forwardToReplicas
- description: When true, changes are also propagated to replicas of the given indexName.
+ description: Indicates whether changed index settings are forwarded to the replica indices.
schema:
type: boolean
Page:
in: query
name: page
- description: Requested page (zero-based). When specified, will retrieve a specific page; the page size is implicitly set to 100. When null, will retrieve all indices (no pagination).
+ description: >
+ Returns the requested page number. The page size is determined by the `hitsPerPage` parameter. You can see the number of available pages in the `nbPages` response attribute. When `page` is null, the API response is not paginated.
schema:
type: integer
+ minimum: 0
nullable: true
default: null
PageDefault0:
in: query
name: page
- description: Requested page (zero-based). When specified, will retrieve a specific page; the page size is implicitly set to 100. When null, will retrieve all indices (no pagination).
+ description: >
+ Returns the requested page number (the first page is 0). Page size is set by `hitsPerPage`. When null, there's no pagination.
schema:
type: integer
nullable: true
+ minimum: 0
default: 0
HitsPerPage:
in: query
name: hitsPerPage
- description: Maximum number of objects to retrieve.
+ description: Maximum number of hits per page.
schema:
type: integer
default: 100
@@ -88,7 +93,7 @@ Offset:
Limit:
in: query
name: limit
- description: Number of records to return. Limit is the size of the page.
+ description: Number of records to return (page size).
schema:
type: integer
default: 10
@@ -96,36 +101,42 @@ Limit:
# misc
objectID:
type: string
- description: Unique identifier of the object.
+ description: Unique object identifier.
+ example: 'product-1'
id:
type: string
- description: objectID of the inserted object.
+ example: '12'
+ description: Unique identifier of a synonym object.
indexName:
type: string
example: products
- description: The Algolia index name.
+ description: Algolia index name.
hitsPerPage:
type: integer
default: 20
- description: Maximum number of hits in a page. Minimum is 1, maximum is 1000.
+ minimum: 1
+ maximum: 1000
+ description: Maximum number of hits per page.
query:
type: string
- description: Full text query.
+ description: Full-text query.
default: ''
page:
type: integer
- default: 0
- description: Requested page (zero-based).
+ minimum: 0
+ description: Requested page (the first page is page 0).
trackedSearchCount:
type: integer
- description: The number of tracked search click.
+ example: 2
+ description: Number of tracked searches. This is the number of search requests where the `clickAnalytics` parameter is `true`.
count:
- description: The number of occurrences.
+ description: Number of occurrences.
+ example: 2
type: integer
diff --git a/specs/common/paths/customRequest.yml b/specs/common/paths/customRequest.yml
index 3bcdd1d542..c8c7528d23 100644
--- a/specs/common/paths/customRequest.yml
+++ b/specs/common/paths/customRequest.yml
@@ -5,7 +5,7 @@ get:
post:
operationId: post
requestBody:
- description: The parameters to send with the custom request.
+ description: Parameters to send with the custom request.
content:
application/json:
schema:
@@ -15,7 +15,7 @@ post:
put:
operationId: put
requestBody:
- description: The parameters to send with the custom request.
+ description: Parameters to send with the custom request.
content:
application/json:
schema:
diff --git a/specs/common/responses/CreatedAt.yml b/specs/common/responses/CreatedAt.yml
index fb318d2d59..955d6c38a8 100644
--- a/specs/common/responses/CreatedAt.yml
+++ b/specs/common/responses/CreatedAt.yml
@@ -3,7 +3,7 @@ content:
application/json:
schema:
title: createdAtResponse
- description: The response with a createdAt timestamp.
+ description: Response and creation timestamp.
additionalProperties: false
type: object
required:
diff --git a/specs/common/responses/DeletedAt.yml b/specs/common/responses/DeletedAt.yml
index b57e8340de..dde847ed56 100644
--- a/specs/common/responses/DeletedAt.yml
+++ b/specs/common/responses/DeletedAt.yml
@@ -3,7 +3,7 @@ content:
application/json:
schema:
title: deletedAtResponse
- description: The response with a taskID and a deletedAt timestamp.
+ description: Response, taskID, and deletion timestamp.
additionalProperties: false
type: object
required:
diff --git a/specs/common/responses/StatusUnprocessableEntity.yml b/specs/common/responses/StatusUnprocessableEntity.yml
index 157350c040..70d01ef175 100644
--- a/specs/common/responses/StatusUnprocessableEntity.yml
+++ b/specs/common/responses/StatusUnprocessableEntity.yml
@@ -1,4 +1,4 @@
-description: Status unprocessable entity.
+description: Unprocessable Entity.
content:
application/json:
schema:
diff --git a/specs/common/responses/Success.yml b/specs/common/responses/Success.yml
index 53f53ef3b3..94cafe90ae 100644
--- a/specs/common/responses/Success.yml
+++ b/specs/common/responses/Success.yml
@@ -12,8 +12,8 @@ content:
status:
type: integer
example: 200
- description: The status code.
+ description: Status code.
message:
type: string
example: Success
- description: Message of the response.
+ description: Response message.
diff --git a/specs/common/responses/UpdatedAt.yml b/specs/common/responses/UpdatedAt.yml
index b4082957ef..0eb88197f5 100644
--- a/specs/common/responses/UpdatedAt.yml
+++ b/specs/common/responses/UpdatedAt.yml
@@ -3,7 +3,7 @@ content:
application/json:
schema:
title: updatedAtResponse
- description: The response with a taskID and an updatedAt timestamp.
+ description: Response, taskID, and update timestamp.
additionalProperties: false
type: object
required:
diff --git a/specs/common/responses/UpdatedAtWithObjectId.yml b/specs/common/responses/UpdatedAtWithObjectId.yml
index 057bcc408c..7887901f10 100644
--- a/specs/common/responses/UpdatedAtWithObjectId.yml
+++ b/specs/common/responses/UpdatedAtWithObjectId.yml
@@ -3,7 +3,7 @@ content:
application/json:
schema:
title: updatedAtWithObjectIdResponse
- description: The response with a taskID, an objectID and an updatedAt timestamp.
+ description: Response, taskID, unique object identifier, and an update timestamp.
additionalProperties: false
type: object
properties:
diff --git a/specs/common/responses/common.yml b/specs/common/responses/common.yml
index 6996276885..cd4019396a 100644
--- a/specs/common/responses/common.yml
+++ b/specs/common/responses/common.yml
@@ -1,27 +1,36 @@
taskID:
type: integer
format: int64
- description: taskID of the task to wait for.
+ example: 1514562690001
+ description: >
+ Unique identifier of a task.
+
+ A successful API response means that a task was added to a queue. It might not run immediately. You can check the task's progress with the `task` operation and this `taskID`.
objectIDs:
type: array
items:
type: string
- description: List of objectID.
+ example: ['record-1','record-2']
+ description: Unique object (record) identifiers.
createdAt:
type: string
- description: Date of creation (ISO-8601 format).
+ example: '2023-07-04T12:49:15Z'
+ description: Timestamp of creation in [ISO-8601](https://wikipedia.org/wiki/ISO_8601) format.
createdAtTimestamp:
type: integer
format: int64
- description: Time of the event expressed in milliseconds since the Unix epoch.
+ example: 1656345570000
+ description: Timestamp of creation in milliseconds in [Unix epoch time](https://wikipedia.org/wiki/Unix_time).
updatedAt:
type: string
- description: Date of last update (ISO-8601 format).
+ example: '2023-07-04T12:49:15Z'
+ description: Timestamp of the last update in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.
deletedAt:
type: string
- description: Date of deletion (ISO-8601 format).
+ example: '2023-06-27T14:42:38.831Z'
+ description: Timestamp of deletion in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.
diff --git a/specs/common/schemas/CustomRequest.yml b/specs/common/schemas/CustomRequest.yml
index 4ef34cef6c..5e05a1cb09 100644
--- a/specs/common/schemas/CustomRequest.yml
+++ b/specs/common/schemas/CustomRequest.yml
@@ -26,7 +26,7 @@ Responses:
PathInPath:
name: path
in: path
- description: The path of the API endpoint to target, anything after the /1 needs to be specified.
+ description: Path of the endpoint, anything after "/1" must be specified.
required: true
schema:
type: string
@@ -35,7 +35,7 @@ PathInPath:
Parameters:
name: parameters
in: query
- description: Query parameters to be applied to the current query.
+ description: Query parameters to apply to the current query.
schema:
type: object
additionalProperties: true
diff --git a/specs/common/schemas/IndexSettings.yml b/specs/common/schemas/IndexSettings.yml
index dbbf711cd4..09b19d00cc 100644
--- a/specs/common/schemas/IndexSettings.yml
+++ b/specs/common/schemas/IndexSettings.yml
@@ -1,5 +1,5 @@
indexSettings:
- description: The Algolia index settings.
+ description: Algolia index settings.
allOf:
- $ref: '#/baseIndexSettings'
- $ref: '#/indexSettingsAsSearchParams'
@@ -12,19 +12,22 @@ baseIndexSettings:
type: array
items:
type: string
- description: Creates replicas, exact copies of an index.
+ example: [virtual(prod_products_price_asc),dev_products_replica]
+ description: Creates [replicas](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/replicas/), which are copies of a primary index with the same records but different settings.
default: []
x-categories:
- Ranking
paginationLimitedTo:
type: integer
- description: Set the maximum number of hits accessible via pagination.
+ example: 20
+ description: Maximum number of hits accessible through pagination.
default: 1000
unretrievableAttributes:
type: array
items:
type: string
- description: List of attributes that can't be retrieved at query time.
+ example: [popularity]
+ description: Attributes that can't be retrieved at query time.
default: []
x-categories:
- Attributes
@@ -32,28 +35,32 @@ baseIndexSettings:
type: array
items:
type: string
- description: A list of words for which you want to turn off typo tolerance.
+ example: ['wheel','1X2BCD']
+ description: Words for which you want to turn off [typo tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/).
default: []
x-categories:
- Typos
attributesToTransliterate:
- description: Specify on which attributes in your index Algolia should apply Japanese transliteration to make words indexed in Katakana or Kanji searchable in Hiragana.
+ description: Attributes in your index to which [Japanese transliteration](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/language-specific-configurations/#japanese-transliteration-and-type-ahead) applies. This will ensure that words indexed in Katakana or Kanji can also be searched in Hiragana.
type: array
items:
type: string
+ example: ['name','description']
x-categories:
- Languages
camelCaseAttributes:
type: array
items:
type: string
- description: List of attributes on which to do a decomposition of camel case words.
+ example: ['description']
+ description: Attributes on which to split [camel case](https://wikipedia.org/wiki/Camel_case) words.
default: []
x-categories:
- Languages
decompoundedAttributes:
type: object
- description: Specify on which attributes in your index Algolia should apply word segmentation, also known as decompounding.
+ example: {de: ['name']}
+ description: Attributes in your index to which [word segmentation](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-segmentation/) (decompounding) applies.
default: {}
x-categories:
- Languages
@@ -61,7 +68,8 @@ baseIndexSettings:
type: array
items:
type: string
- description: Sets the languages at the index level for language-specific processing such as tokenization and normalization.
+ example: ['ja']
+ description: Set the languages of your index, for language-specific processing steps such as [tokenization](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/tokenization/) and [normalization](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/normalization/).
default: []
x-categories:
- Languages
@@ -69,13 +77,17 @@ baseIndexSettings:
type: array
items:
type: string
- description: List of attributes on which you want to disable prefix matching.
+ example: ['sku']
+ description: Attributes for which you want to turn off [prefix matching](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/#adjusting-prefix-search).
default: []
x-categories:
- Query strategy
allowCompressionOfIntegerArray:
type: boolean
- description: Enables compression of large integer arrays.
+ description: >
+ Incidates whether the engine compresses arrays with exclusively non-negative integers.
+
+ When enabled, the compressed arrays may be reordered.
default: false
x-categories:
- Performance
@@ -83,13 +95,15 @@ baseIndexSettings:
type: array
items:
type: string
- description: List of numeric attributes that can be used as numerical filters.
+ description: Numeric attributes that can be used as [numerical filters](https://www.algolia.com/doc/guides/managing-results/rules/detecting-intent/how-to/applying-a-custom-filter-for-a-specific-query/#numerical-filters).
+ example: ['quantity','popularity']
default: []
x-categories:
- Performance
separatorsToIndex:
type: string
- description: Control which separators are indexed.
+ example: +#
+ description: Controls which separators are added to an Algolia index as part of [normalization](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/#what-does-normalization-mean). Separators are all non-letter characters except spaces and currency characters, such as $€£¥.
default: ''
x-categories:
- Typos
@@ -97,15 +111,19 @@ baseIndexSettings:
type: array
items:
type: string
- description: The complete list of attributes used for searching.
+ example: ['title,alternative_title','author','unordered(text)','emails.personal']
+ description: >
+ [Attributes used for searching](https://www.algolia.com/doc/guides/managing-results/must-do/searchable-attributes/), including determining [if matches at the beginning of a word are important (ordered) or not (unordered)](https://www.algolia.com/doc/guides/managing-results/must-do/searchable-attributes/how-to/configuring-searchable-attributes-the-right-way/#understanding-word-position).
default: []
x-categories:
- Attributes
userData:
$ref: '#/userData'
customNormalization:
- description: Overrides Algolia's default normalization.
+ description: A list of characters and their normalized replacements to override Algolia's default [normalization](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/normalization/).
type: object
+ example: >
+ {default: {'ä': 'ae', 'ü': 'ue'}}
additionalProperties:
type: object
additionalProperties:
@@ -121,7 +139,9 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- description: The complete list of attributes that will be used for faceting.
+ example: ['author','filterOnly(isbn)','searchable(edition)','afterDistinct(category)','afterDistinct(searchable(publisher))']
+ description: >
+ Attributes used for [faceting](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/) and the [modifiers](https://www.algolia.com/doc/api-reference/api-parameters/attributesForFaceting/#modifiers) that can be applied: `filterOnly`, `searchable`, and `afterDistinct`.
default: []
x-categories:
- Faceting
@@ -129,7 +149,8 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- description: This parameter controls which attributes to retrieve and which not to retrieve.
+ example: ['author','title','content']
+ description: Attributes to include in the API response. To reduce the size of your response, you can retrieve only some of the attributes. By default, the response includes all attributes.
default: ['*']
x-categories:
- Attributes
@@ -137,7 +158,8 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- description: Restricts a given query to look in only a subset of your searchable attributes.
+ example: ['title','author']
+ description: Restricts a query to only look at a subset of your [searchable attributes](https://www.algolia.com/doc/guides/managing-results/must-do/searchable-attributes/).
default: []
x-categories:
- Attributes
@@ -145,7 +167,7 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- description: Controls how Algolia should sort your results.
+ description: Determines the order in which Algolia [returns your results](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/).
default:
- typo
- geo
@@ -161,13 +183,16 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- description: Specifies the custom ranking criterion.
+ example: ['desc(popularity)','asc(price)']
+ description: >
+ Specifies the [Custom ranking criterion](https://www.algolia.com/doc/guides/managing-results/must-do/custom-ranking/). Use the `asc` and `desc` modifiers to specify the ranking order: ascending or descending.
default: []
x-categories:
- Ranking
relevancyStrictness:
type: integer
- description: Controls the relevancy threshold below which less relevant results aren't included in the results.
+ example: 90
+ description: Relevancy threshold below which less relevant results aren't included in the results.
default: 100
x-categories:
- Ranking
@@ -175,26 +200,29 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- description: List of attributes to highlight.
+ example: ['author','title','content']
+ description: Attributes to highlight. Strings that match the search query in the attributes are highlighted by surrounding them with HTML tags (`highlightPreTag` and `highlightPostTag`).
x-categories:
- Highlighting and Snippeting
attributesToSnippet:
type: array
items:
type: string
- description: List of attributes to snippet, with an optional maximum number of words to snippet.
+ example: ['content:80','description']
+ description: >
+ Attributes to _snippet_. 'Snippeting' is shortening the attribute to a certain number of words. If not specified, the attribute is shortened to the 10 words around the matching string but you can specify the number. For example: `body:20`.
default: []
x-categories:
- Highlighting and Snippeting
highlightPreTag:
type: string
- description: The HTML string to insert before the highlighted parts in all highlight and snippet results.
+ description: HTML string to insert before the highlighted parts in all highlight and snippet results.
default:
x-categories:
- Highlighting and Snippeting
highlightPostTag:
type: string
- description: The HTML string to insert after the highlighted parts in all highlight and snippet results.
+ description: HTML string to insert after the highlighted parts in all highlight and snippet results.
default:
x-categories:
- Highlighting and Snippeting
@@ -214,13 +242,13 @@ indexSettingsAsSearchParams:
$ref: '#/hitsPerPage'
minWordSizefor1Typo:
type: integer
- description: Minimum number of characters a word in the query string must contain to accept matches with 1 typo.
+ description: Minimum number of characters a word in the query string must contain to accept matches with [one typo](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/in-depth/configuring-typo-tolerance/#configuring-word-length-for-typos).
default: 4
x-categories:
- Typos
minWordSizefor2Typos:
type: integer
- description: Minimum number of characters a word in the query string must contain to accept matches with 2 typos.
+ description: Minimum number of characters a word in the query string must contain to accept matches with [two typos](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/in-depth/configuring-typo-tolerance/#configuring-word-length-for-typos).
default: 8
x-categories:
- Typos
@@ -236,7 +264,8 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- description: List of attributes on which you want to disable typo tolerance.
+ example: ['sku']
+ description: Attributes for which you want to turn off [typo tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/).
default: []
x-categories:
- Typos
@@ -246,7 +275,8 @@ indexSettingsAsSearchParams:
$ref: '#/removeStopWords'
keepDiacriticsOnCharacters:
type: string
- description: List of characters that the engine shouldn't automatically normalize.
+ example: øé
+ description: Characters that the engine shouldn't automatically [normalize](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/normalization/).
default: ''
x-categories:
- Languages
@@ -254,25 +284,27 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- description: Sets the languages to be used by language-specific settings and functionalities such as ignorePlurals, removeStopWords, and CJK word-detection.
+ example: ['es']
+ description: Sets your user's search language. This adjusts language-specific settings and features such as `ignorePlurals`, `removeStopWords`, and [CJK](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/normalization/#normalization-for-logogram-based-languages-cjk) word detection.
default: []
x-categories:
- Languages
decompoundQuery:
type: boolean
- description: Splits compound words into their composing atoms in the query.
+ description: >
+ [Splits compound words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/language-specific-configurations/#splitting-compound-words) into their component word parts in the query.
default: true
x-categories:
- Languages
enableRules:
type: boolean
- description: Whether Rules should be globally enabled.
+ description: Incidates whether [Rules](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/) are enabled.
default: true
x-categories:
- Rules
enablePersonalization:
type: boolean
- description: Enable the Personalization feature.
+ description: Incidates whether [Personalization](https://www.algolia.com/doc/guides/personalization/what-is-personalization/) is enabled.
default: false
x-categories:
- Personalization
@@ -285,11 +317,11 @@ indexSettingsAsSearchParams:
semanticSearch:
type: object
description: >
- The settings relevant for configuration of the semantic search engine.
- These settings are only used when the mode is set to 'neuralSearch'.
+ Settings for the semantic search part of NeuralSearch.
+ Only used when `mode` is _neuralSearch_.
properties:
eventSources:
- description: When null, the current index / replica group will be used as the event source.
+ description: Indices from which to collect click and conversion events. If null, the current index and replica group will be used as the event source.
nullable: true
type: array
items:
@@ -297,7 +329,7 @@ indexSettingsAsSearchParams:
advancedSyntax:
type: boolean
- description: Enables the advanced query syntax.
+ description: Enables the [advanced query syntax](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/#advanced-syntax).
default: false
x-categories:
- Query strategy
@@ -305,7 +337,8 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- description: A list of words that should be considered as optional when found in the query.
+ example: ['blue','iphone case']
+ description: Words which should be considered [optional](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/empty-or-insufficient-results/#creating-a-list-of-optional-words) when found in a query.
default: []
x-categories:
- Query strategy
@@ -313,7 +346,8 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- description: List of attributes on which you want to disable the exact ranking criterion.
+ example: ['description']
+ description: Attributes for which you want to [turn off the exact ranking criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/adjust-exact-settings/#turn-off-exact-for-some-attributes).
default: []
x-categories:
- Query strategy
@@ -323,7 +357,7 @@ indexSettingsAsSearchParams:
type: array
items:
$ref: '#/alternativesAsExact'
- description: List of alternatives that should be considered an exact match by the exact ranking criterion.
+ description: Alternatives that should be considered an exact match by [the exact ranking criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/adjust-exact-settings/#turn-off-exact-for-some-attributes).
default: [ignorePlurals, singleWordSynonym]
x-categories:
- Query strategy
@@ -331,7 +365,7 @@ indexSettingsAsSearchParams:
type: array
items:
$ref: '#/advancedSyntaxFeatures'
- description: Allows you to specify which advanced syntax features are active when ‘advancedSyntax' is enabled.
+ description: Allows you to specify which advanced syntax features are active when `advancedSyntax` is enabled.
default: [exactPhrase, excludeWords]
x-categories:
- Query strategy
@@ -339,14 +373,15 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- description: Enriches the API’s response with meta-information as to how the query was processed.
+ description: Enriches the API's response with information about how the query was processed.
default: []
x-categories:
- Query strategy
distinct:
$ref: '#/distinct'
attributeForDistinct:
- description: Name of the de-duplication attribute to be used with the distinct feature.
+ description: Name of the deduplication attribute to be used with Algolia's [_distinct_ feature](https://www.algolia.com/doc/guides/managing-results/refine-results/grouping/#introducing-algolias-distinct-feature).
+ example: 'url'
type: string
synonyms:
type: boolean
@@ -364,7 +399,7 @@ indexSettingsAsSearchParams:
type: integer
minimum: 1
maximum: 7
- description: Precision of the proximity ranking criterion.
+ description: Precision of the [proximity ranking criterion](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/#proximity).
default: 1
x-categories:
- Advanced
@@ -372,7 +407,7 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- description: Choose which fields to return in the API response. This parameters applies to search and browse queries.
+ description: Attributes to include in the API response for search and browse queries.
default: []
x-categories:
- Advanced
@@ -380,7 +415,7 @@ indexSettingsAsSearchParams:
$ref: '#/maxFacetHits'
attributeCriteriaComputedByMinProximity:
type: boolean
- description: When attribute is ranked above proximity in your ranking formula, proximity is used to select which searchable attribute is matched in the attribute ranking stage.
+ description: When the [Attribute criterion is ranked above Proximity](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/#attribute-and-proximity-combinations) in your ranking formula, Proximity is used to select which searchable attribute is matched in the Attribute ranking stage.
default: false
x-categories:
- Advanced
@@ -389,7 +424,7 @@ indexSettingsAsSearchParams:
maxFacetHits:
type: integer
- description: Maximum number of facet hits to return during a search for facet values. For performance reasons, the maximum allowed number of returned values is 100.
+ description: Maximum number of facet hits to return when [searching for facet values](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#search-for-facet-values).
maximum: 100
default: 10
x-categories:
@@ -397,13 +432,16 @@ maxFacetHits:
hitsPerPage:
type: integer
- description: Set the number of hits per page.
+ description: Number of hits per page.
default: 20
+ minimum: 1
+ maximum: 1000
x-categories:
- Pagination
userData:
type: object
+ example: {'settingID': 'f2a7b51e3503acc6a39b3784ffb84300','pluginVersion': '1.6.0'}
description: Lets you store custom data in your indices.
default: {}
x-categories:
@@ -412,7 +450,7 @@ userData:
queryType:
type: string
enum: [prefixLast, prefixAll, prefixNone]
- description: Controls if and how query words are interpreted as prefixes.
+ description: Determines how query words are [interpreted as prefixes](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/prefix-searching/).
default: prefixLast
x-categories:
- Query strategy
@@ -420,7 +458,7 @@ queryType:
mode:
type: string
enum: ['neuralSearch', 'keywordSearch']
- description: The search mode that the index will use to query for results.
+ description: Search mode the index will use to query for results.
default: keywordSearch
x-categories:
- Query strategy
@@ -428,7 +466,8 @@ mode:
removeWordsIfNoResults:
type: string
enum: [none, lastWords, firstWords, allOptional]
- description: Selects a strategy to remove words from the query when it doesn't match any hits.
+ example: firstWords
+ description: Strategy to [remove words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/empty-or-insufficient-results/in-depth/why-use-remove-words-if-no-results/) from the query when it doesn't match any hits.
default: none
x-categories:
- Query strategy
@@ -436,7 +475,7 @@ removeWordsIfNoResults:
exactOnSingleWordQuery:
type: string
enum: [attribute, none, word]
- description: Controls how the exact ranking criterion is computed when the query contains only one word.
+ description: Determines how the [Exact ranking criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/adjust-exact-settings/#turn-off-exact-for-some-attributes) is computed when the query contains only one word.
default: attribute
x-categories:
- Query strategy
@@ -454,7 +493,8 @@ advancedSyntaxFeatures:
- Query strategy
distinct:
- description: Enables de-duplication or grouping of results.
+ description: Enables [deduplication or grouping of results (Algolia's _distinct_ feature](https://www.algolia.com/doc/guides/managing-results/refine-results/grouping/#introducing-algolias-distinct-feature)).
+ example: 1
oneOf:
- type: boolean
- type: integer
@@ -465,7 +505,7 @@ distinct:
- Advanced
typoTolerance:
- description: Controls whether typo tolerance is enabled and how it is applied.
+ description: Controls whether [typo tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/) is enabled and how it is applied.
oneOf:
- type: boolean
default: true
@@ -481,11 +521,12 @@ ignorePlurals:
description: >
Treats singular, plurals, and other forms of declensions as matching terms.
- ignorePlurals is used in conjunction with the queryLanguages setting.
+ `ignorePlurals` is used in conjunction with the `queryLanguages` setting.
- list: language ISO codes for which ignoring plurals should be enabled. This list will override any values that you may have set in queryLanguages.
- true: enables the ignore plurals functionality, where singulars and plurals are considered equivalent (foot = feet). The languages supported here are either every language (this is the default, see list of languages below), or those set by queryLanguages.
- false: disables ignore plurals, where singulars and plurals are not considered the same for matching purposes (foot will not find feet).
+ _list_: language ISO codes for which ignoring plurals should be enabled. This list will override any values that you may have set in `queryLanguages`.
+ _true_: enables the ignore plurals feature, where singulars and plurals are considered equivalent ("foot" = "feet"). The languages supported here are either [every language](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/) (this is the default) or those set by `queryLanguages`.
+ _false_: turns off the ignore plurals feature, so that singulars and plurals aren't considered to be the same ("foot" will not find "feet").
+ example: ['ca','es']
oneOf:
- type: array
items:
@@ -499,11 +540,12 @@ removeStopWords:
description: >
Removes stop (common) words from the query before executing it.
- removeStopWords is used in conjunction with the queryLanguages setting.
+ `removeStopWords` is used in conjunction with the `queryLanguages` setting.
- list: language ISO codes for which ignoring plurals should be enabled. This list will override any values that you may have set in queryLanguages.
- true: enables the stop word functionality, ensuring that stop words are removed from consideration in a search. The languages supported here are either every language, or those set by queryLanguages.
- false: disables stop word functionality, allowing stop words to be taken into account in a search.
+ _list_: language ISO codes for which stop words should be enabled. This list will override any values that you may have set in `queryLanguages`.
+ _true_: enables the stop words feature, ensuring that stop words are removed from consideration in a search. The languages supported here are either [every language](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/) (this is the default) or those set by `queryLanguages`.
+ _false_: turns off the stop words feature, allowing stop words to be taken into account in a search.
+ example: ['ca','es']
oneOf:
- type: array
items:
@@ -514,7 +556,7 @@ removeStopWords:
- Languages
renderingContent:
- description: Content defining how the search interface should be rendered. Can be set via the settings for a default value and can be overridden via rules.
+ description: Extra content for the search UI, for example, to control the [ordering and display of facets](https://www.algolia.com/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/merchandising-facets/#merchandise-facets-and-their-values-in-the-manual-editor). You can set a default value and dynamically override it with [Rules](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/).
type: object
additionalProperties: false
properties:
@@ -524,7 +566,7 @@ renderingContent:
- Advanced
facetOrdering:
- description: Defining how facets should be ordered.
+ description: Defines the ordering of facets (widgets).
type: object
additionalProperties: false
properties:
@@ -534,7 +576,7 @@ facetOrdering:
$ref: '#/values'
facets:
- description: The ordering of facets (widgets).
+ description: Ordering of facets (widgets).
type: object
additionalProperties: false
properties:
@@ -542,7 +584,7 @@ facets:
$ref: '#/order'
values:
- description: The ordering of facet values, within an individual list.
+ description: Ordering of facet values within an individual facet.
type: object
additionalProperties:
$ref: '#/value'
@@ -564,7 +606,8 @@ order:
sortRemainingBy:
description: >
- How to display the remaining items.
+ How to display the remaining items:
+
- `count`: facet count (descending).
- `alpha`: alphabetical (ascending).
- `hidden`: show only pinned values.
diff --git a/specs/common/schemas/SearchParams.yml b/specs/common/schemas/SearchParams.yml
index 6dd7d1ac05..861be2ba86 100644
--- a/specs/common/schemas/SearchParams.yml
+++ b/specs/common/schemas/SearchParams.yml
@@ -26,7 +26,7 @@ baseSearchParamsWithoutQuery:
properties:
similarQuery:
type: string
- description: Overrides the query parameter and performs a more generic search that can be used to find "similar" results.
+ description: Overrides the query parameter and performs a more generic search.
default: ''
x-categories:
- Search
@@ -42,7 +42,12 @@ baseSearchParamsWithoutQuery:
$ref: '#/tagFilters'
sumOrFiltersScores:
type: boolean
- description: Determines how to calculate the total score for filtering.
+ description: >
+ Determines how to calculate [filter scores](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/in-depth/filter-scoring/#accumulating-scores-with-sumorfiltersscores).
+
+ If `false`, maximum score is kept.
+
+ If `true`, score is summed.
default: false
x-categories:
- Filtering
@@ -50,19 +55,20 @@ baseSearchParamsWithoutQuery:
type: array
items:
type: string
- description: Retrieve facets and their facet values.
+ description: Returns [facets](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#contextual-facet-values-and-counts), their facet values, and the number of matching facet values.
default: []
x-categories:
- Faceting
maxValuesPerFacet:
type: integer
- description: Maximum number of facet values to return for each facet during a regular search.
+ description: Maximum number of facet values to return for each facet.
default: 100
x-categories:
- Faceting
facetingAfterDistinct:
type: boolean
- description: Force faceting to be applied after de-duplication (via the Distinct setting).
+ description: >
+ Forces faceting to be applied after [de-duplication](https://www.algolia.com/doc/guides/managing-results/refine-results/grouping/) (with the distinct feature). Alternatively, the `afterDistinct` [modifier](https://www.algolia.com/doc/api-reference/api-parameters/attributesForFaceting/#modifiers) of `attributesForFaceting` allows for more granular control.
default: false
x-categories:
- Faceting
@@ -76,12 +82,18 @@ baseSearchParamsWithoutQuery:
$ref: '#/page'
offset:
type: integer
- description: Specify the offset of the first hit to return.
+ description: >
+ Specifies the offset of the first hit to return.
+
+ > **Note**: Using `page` and `hitsPerPage` is the recommended method for [paging results](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/pagination/js/). However, you can use `offset` and `length` to implement [an alternative approach to paging](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/pagination/js/#retrieving-a-subset-of-records-with-offset-and-length).
x-categories:
- Pagination
length:
type: integer
- description: Set the number of hits to retrieve (used only with offset).
+ description: >
+ Sets the number of hits to retrieve (for use with `offset`).
+
+ > **Note**: Using `page` and `hitsPerPage` is the recommended method for [paging results](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/pagination/js/). However, you can use `offset` and `length` to implement [an alternative approach to paging](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/pagination/js/#retrieving-a-subset-of-records-with-offset-and-length).
minimum: 1
maximum: 1000
x-categories:
@@ -94,13 +106,13 @@ baseSearchParamsWithoutQuery:
$ref: '#/aroundRadius'
aroundPrecision:
type: integer
- description: Precision of geo search (in meters), to add grouping by geo location to the ranking formula.
+ description: Precision of a geographical search (in meters), to [group results that are more or less the same distance from a central point](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/in-depth/geo-ranking-precision/).
default: 10
x-categories:
- Geo-Search
minimumAroundRadius:
type: integer
- description: Minimum radius (in meters) used for a geo search when aroundRadius is not set.
+ description: Minimum radius (in meters) used for a geographical search when `aroundRadius` isn't set.
minimum: 1
x-categories:
- Geo-Search
@@ -112,7 +124,7 @@ baseSearchParamsWithoutQuery:
type: array
items:
type: string
- description: This parameter changes the default values of certain parameters and settings that work best for a natural language query, such as ignorePlurals, removeStopWords, removeWordsIfNoResults, analyticsTags and ruleContexts. These parameters and settings work well together when the query is formatted in natural language instead of keywords, for example when your user performs a voice search.
+ description: Changes the default values of parameters that work best for a natural language query, such as `ignorePlurals`, `removeStopWords`, `removeWordsIfNoResults`, `analyticsTags`, and `ruleContexts`. These parameters work well together when the query consists of fuller natural language strings instead of keywords, for example when processing voice search queries.
default: []
x-categories:
- Languages
@@ -120,36 +132,37 @@ baseSearchParamsWithoutQuery:
type: array
items:
type: string
- description: Enables contextual rules.
+ description: Assigns [rule contexts](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/how-to/customize-search-results-by-platform/#whats-a-context) to search queries.
default: []
x-categories:
- Rules
personalizationImpact:
type: integer
- description: Define the impact of the Personalization feature.
+ description: Defines how much [Personalization affects results](https://www.algolia.com/doc/guides/personalization/personalizing-results/in-depth/configuring-personalization/#understanding-personalization-impact).
default: 100
x-categories:
- Personalization
userToken:
type: string
- description: Associates a certain user token with the current search.
+ description: Associates a [user token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken/) with the current search.
+ example: '123456'
x-categories:
- Personalization
getRankingInfo:
type: boolean
- description: Retrieve detailed ranking information.
+ description: Incidates whether the search response includes [detailed ranking information](https://www.algolia.com/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/#ranking-information).
default: false
x-categories:
- Advanced
clickAnalytics:
type: boolean
- description: Enable the Click Analytics feature.
+ description: Indicates whether a query ID parameter is included in the search response. This is required for [tracking click and conversion events](https://www.algolia.com/doc/guides/sending-events/concepts/event-types/#events-related-to-algolia-requests).
default: false
x-categories:
- Analytics
analytics:
type: boolean
- description: Whether the current query will be taken into account in the Analytics.
+ description: Indicates whether this query will be included in [analytics](https://www.algolia.com/doc/guides/search-analytics/guides/exclude-queries/).
default: true
x-categories:
- Analytics
@@ -157,7 +170,7 @@ baseSearchParamsWithoutQuery:
type: array
items:
type: string
- description: List of tags to apply to the query for analytics purposes.
+ description: Tags to apply to the query for [segmenting analytics data](https://www.algolia.com/doc/guides/search-analytics/guides/segments/).
default: []
x-categories:
- Analytics
@@ -169,13 +182,13 @@ baseSearchParamsWithoutQuery:
- Advanced
enableABTest:
type: boolean
- description: Whether this search should participate in running AB tests.
+ description: Incidates whether this search will be considered in A/B testing.
default: true
x-categories:
- Advanced
enableReRanking:
type: boolean
- description: Whether this search should use AI Re-Ranking.
+ description: Indicates whether this search will use [Dynamic Re-Ranking](https://www.algolia.com/doc/guides/algolia-ai/re-ranking/).
default: true
x-categories:
- Advanced
@@ -190,26 +203,28 @@ searchParamsString:
$ref: '#/paramsAsString'
paramsAsString:
- description: Search parameters as URL-encoded query string.
+ description: Search parameters as a URL-encoded query string.
+ example: 'hitsPerPage=2&getRankingInfo=1'
type: string
default: ''
query:
type: string
- description: The text to search in the index.
+ description: Text to search for in an index.
default: ''
x-categories:
- Search
page:
type: integer
- description: Specify the page to retrieve.
+ description: Page to retrieve (the first page is `0`, not `1`).
default: 0
x-categories:
- Pagination
aroundRadius:
- description: Define the maximum radius for a geo search (in meters).
+ description: >
+ [Maximum radius](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/#increase-the-search-radius) for a geographical search (in meters).
oneOf:
- type: integer
minimum: 1
@@ -223,14 +238,15 @@ aroundRadiusAll:
aroundLatLng:
type: string
- description: Search for entries around a central geolocation, enabling a geo search within a circular area.
+ description: Search for entries [around a central location](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/#filter-around-a-central-point), enabling a geographical search within a circular area.
+ example: '40.71,-74.01'
default: ''
x-categories:
- Geo-Search
aroundLatLngViaIP:
type: boolean
- description: Search for entries around a given location automatically computed from the requester's IP address.
+ description: Search for entries around a location. The location is automatically computed from the requester's IP address.
default: false
x-categories:
- Geo-Search
@@ -240,7 +256,8 @@ insideBoundingBox:
items:
type: number
format: double
- description: Search inside a rectangular area (in geo coordinates).
+ description: Search inside a [rectangular area](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/#filtering-inside-rectangular-or-polygonal-areas) (in geographical coordinates).
+ example: [46.650828100116044,7.123046875,45.17210966999772,1.009765625]
x-categories:
- Geo-Search
@@ -249,7 +266,8 @@ insidePolygon:
items:
type: number
format: double
- description: Search inside a polygon (in geo coordinates).
+ description: Search inside a [polygon](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/#filtering-inside-rectangular-or-polygonal-areas) (in geographical coordinates).
+ example: [46.650828100116044,7.123046875,45.17210966999772,1.009765625,49.62625916704081,4.6181640625]
x-categories:
- Geo-Search
@@ -272,13 +290,17 @@ listOfSearchFilters:
filters:
type: string
- description: Filter the query with numeric, facet and/or tag filters.
+ description: >
+ [Filter](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/) the query with numeric, facet, or tag filters.
+ example: '(category:Book OR category:Ebook) AND _tags:published'
default: ''
x-categories:
- Filtering
facetFilters:
- description: Filter hits by facet value.
+ description: >
+ [Filter hits by facet value](https://www.algolia.com/doc/api-reference/api-parameters/facetFilters/).
+ example: ['category:Book','author:John Doe']
oneOf:
- $ref: '#/listOfSearchFilters'
- type: string
@@ -286,7 +308,7 @@ facetFilters:
- Filtering
reRankingApplyFilter:
- description: When Dynamic Re-Ranking is enabled, only records that match these filters will be impacted by Dynamic Re-Ranking.
+ description: When [Dynamic Re-Ranking](https://www.algolia.com/doc/guides/algolia-ai/re-ranking/) is enabled, only records that match these filters will be affected by Dynamic Re-Ranking.
nullable: true
oneOf:
- $ref: '#/listOfSearchFilters'
@@ -295,7 +317,9 @@ reRankingApplyFilter:
- Filtering
tagFilters:
- description: Filter hits by tags.
+ description: >
+ [Filter hits by tags](https://www.algolia.com/doc/api-reference/api-parameters/tagFilters/).
+ example: [['Book','Movie'],'SciFi']
oneOf:
- $ref: '#/listOfSearchFilters'
- type: string
@@ -303,7 +327,9 @@ tagFilters:
- Filtering
numericFilters:
- description: Filter on numeric attributes.
+ description: >
+ [Filter on numeric attributes](https://www.algolia.com/doc/api-reference/api-parameters/numericFilters/).
+ example: [['inStock = 1','deliveryDate < 1441755506'],'price < 1000']
oneOf:
- $ref: '#/listOfSearchFilters'
- type: string
@@ -311,7 +337,11 @@ numericFilters:
- Filtering
optionalFilters:
- description: Create filters for ranking purposes, where records that match the filter are ranked higher, or lower in the case of a negative optional filter.
+ description: |
+ Create filters to boost or demote records.
+
+ Records that match the filter are ranked higher for positive and lower for negative optional filters. In contrast to regular filters, records that don't match the optional filter are still included in the results, only their ranking is affected.
+ example: ['category:Book','author:John Doe']
oneOf:
- $ref: '#/listOfSearchFilters'
- type: string
diff --git a/specs/recommend/common/parameters.yml b/specs/recommend/common/parameters.yml
new file mode 100644
index 0000000000..e99d361e38
--- /dev/null
+++ b/specs/recommend/common/parameters.yml
@@ -0,0 +1,20 @@
+Models:
+ in: path
+ name: model
+ required: true
+ description: >
+ [Recommend models](https://www.algolia.com/doc/guides/algolia-recommend/overview/#recommend-models).
+ schema:
+ $ref: '#/recommendModels'
+
+recommendModels:
+ type: string
+ enum: [related-products, bought-together, trending-facets, trending-items]
+
+ObjectID:
+ in: path
+ name: objectID
+ required: true
+ type: string
+ description: Unique Recommend rule identifier.
+ example: 'a-recommend-rule-id'
diff --git a/specs/recommend/common/schemas/RecommendationsRequest.yml b/specs/recommend/common/schemas/RecommendationsRequest.yml
index bbcb60641a..6eb3812f5a 100644
--- a/specs/recommend/common/schemas/RecommendationsRequest.yml
+++ b/specs/recommend/common/schemas/RecommendationsRequest.yml
@@ -13,10 +13,10 @@ trendingRequest:
$ref: '#/trendingModels'
facetName:
type: string
- description: The facet name to use for trending models.
+ description: Facet name for trending models.
facetValue:
type: string
- description: The facet value to use for trending models.
+ description: Facet value for trending models.
required:
- model
- $ref: '#/baseRecommendRequest'
@@ -46,11 +46,14 @@ baseRecommendRequest:
type: integer
minimum: 0
maximum: 100
- description: The threshold to use when filtering recommendations by their score.
+ description: >
+ Recommendations with a confidence score lower than `threshold` won't appear in results.
+
+ > **Note**: Each recommendation has a confidence score of 0 to 100. The closer the score is to 100, the more relevant the recommendations are.
maxRecommendations:
type: integer
default: 0
- description: The max number of recommendations to retrieve. If it's set to 0, all the recommendations of the objectID may be returned.
+ description: Maximum number of recommendations to retrieve. If 0, all recommendations will be returned.
queryParameters:
$ref: '../../../common/schemas/SearchParams.yml#/searchParamsObject'
fallbackParameters:
@@ -60,11 +63,11 @@ baseRecommendRequest:
- threshold
trendingModels:
- description: The trending model to use.
+ description: Trending model.
type: string
enum: [trending-facets, trending-items]
recommendationModels:
- description: The recommendation model to use.
+ description: Recommendation model.
type: string
enum: [related-products, bought-together]
diff --git a/specs/recommend/common/schemas/RecommendationsResponse.yml b/specs/recommend/common/schemas/RecommendationsResponse.yml
index 9a84278011..09bb5d0eb2 100644
--- a/specs/recommend/common/schemas/RecommendationsResponse.yml
+++ b/specs/recommend/common/schemas/RecommendationsResponse.yml
@@ -16,7 +16,7 @@ recommendHits:
recommendHit:
type: object
- description: A Recommend hit.
+ description: Recommend hit.
additionalProperties: true
required:
- objectID
@@ -37,4 +37,37 @@ recommendHit:
format: double
minimum: 0
maximum: 100
- description: The recommendation score.
+ description: Recommendation score.
+
+ruleResponse:
+ type: object
+ description: Rule object.
+ additionalProperties: false
+ properties:
+ _metadata:
+ type: object
+ properties:
+ lastUpdate:
+ $ref: '../../../common/responses/common.yml#/updatedAt'
+ objectID:
+ type: string
+ description: Unique identifier for a rule object.
+ example: 'hide-12345'
+ conditions:
+ type: array
+ description: >
+ [Conditions](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/#conditions) required to activate a rule. You can use up to 25 conditions per rule.
+ items:
+ $ref: '../../../search/paths/rules/common/schemas.yml#/condition'
+ consequence:
+ $ref: '../../../search/paths/rules/common/schemas.yml#//consequence'
+ description:
+ type: string
+ description: Description of the rule's purpose. This can be helpful for display in the Algolia dashboard.
+ example: 'Display a promotional banner'
+ enabled:
+ type: boolean
+ default: true
+ description: Indicates whether to enable the rule. If it isn't enabled, it isn't applied at query time.
+ required:
+ - objectID
diff --git a/specs/recommend/paths/getRecommendStatus.yml b/specs/recommend/paths/getRecommendStatus.yml
new file mode 100644
index 0000000000..62cd9e4079
--- /dev/null
+++ b/specs/recommend/paths/getRecommendStatus.yml
@@ -0,0 +1,39 @@
+get:
+ tags:
+ - recommendations
+ operationId: getRecommendStatus
+ summary: Get a Recommend task's status.
+ description: Some operations, such as deleting a Recommend rule, will respond with a `taskID` value. Use this value here to check the status of that task.
+ parameters:
+ - $ref: '../../common/parameters.yml#/IndexName'
+ - $ref: '../common/parameters.yml#/Models'
+ - name: taskID
+ in: path
+ description: Unique identifier of a task. Numeric value (up to 64bits).
+ required: true
+ schema:
+ type: integer
+ format: int64
+ example: 13235
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ title: getRecommendTaskResponse
+ type: object
+ additionalProperties: false
+ properties:
+ status:
+ $ref: '../../search/common/enums.yml#/taskStatus'
+ required:
+ - status
+ '400':
+ $ref: '../../common/responses/BadRequest.yml'
+ '402':
+ $ref: '../../common/responses/FeatureNotEnabled.yml'
+ '403':
+ $ref: '../../common/responses/MethodNotAllowed.yml'
+ '404':
+ $ref: '../../common/responses/IndexNotFound.yml'
diff --git a/specs/recommend/paths/getRecommendations.yml b/specs/recommend/paths/getRecommendations.yml
index f5b721ff73..7bf45ad150 100644
--- a/specs/recommend/paths/getRecommendations.yml
+++ b/specs/recommend/paths/getRecommendations.yml
@@ -4,21 +4,25 @@ post:
operationId: getRecommendations
x-use-read-transporter: true
x-cacheable: true
- summary: Get results.
- description: Returns recommendations or trending results, for a specific model and `objectID`.
+ summary: Get recommendations and trending items.
+ description: >
+ Returns results from either recommendation or trending models:
+
+ - **Recommendations** are provided by the [Related Products](https://www.algolia.com/doc/guides/algolia-recommend/overview/#related-products-and-related-content) and [Frequently Bought Together](https://www.algolia.com/doc/guides/algolia-recommend/overview/#frequently-bought-together) models
+ - **Trending** models are [Trending Items and Trending Facet Values](https://www.algolia.com/doc/guides/algolia-recommend/overview/#trending-items-and-trending-facet-values).
requestBody:
required: true
content:
application/json:
schema:
title: getRecommendationsParams
- description: The `getRecommendations` parameters.
+ description: Recommend parameters.
type: object
additionalProperties: false
properties:
requests:
type: array
- description: The `getRecommendations` requests.
+ description: Request parameters depend on the model (recommendations or trending).
items:
$ref: '../common/schemas/RecommendationsRequest.yml#/recommendationsRequest'
required:
diff --git a/specs/recommend/paths/recommendRule.yml b/specs/recommend/paths/recommendRule.yml
new file mode 100644
index 0000000000..c271262dc0
--- /dev/null
+++ b/specs/recommend/paths/recommendRule.yml
@@ -0,0 +1,47 @@
+get:
+ tags:
+ - recommendations
+ operationId: getRecommendRule
+ summary: Get a Recommend rule.
+ description: Return a [Recommend rule](https://www.algolia.com/doc/guides/algolia-recommend/how-to/rules/).
+ parameters:
+ - $ref: '../../common/parameters.yml#/IndexName'
+ - $ref: '../common/parameters.yml#/Models'
+ - $ref: '../../common/parameters.yml#/ObjectID'
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: '../common/schemas/RecommendationsResponse.yml#/ruleResponse'
+ '400':
+ $ref: '../../common/responses/BadRequest.yml'
+ '402':
+ $ref: '../../common/responses/FeatureNotEnabled.yml'
+ '403':
+ $ref: '../../common/responses/MethodNotAllowed.yml'
+ '404':
+ $ref: '../../common/responses/IndexNotFound.yml'
+
+delete:
+ tags:
+ - recommendations
+ operationId: deleteRecommendRule
+ summary: Delete a Recommend rule.
+ description: Delete a [Recommend rule](https://www.algolia.com/doc/guides/algolia-recommend/how-to/rules/).
+ parameters:
+ - $ref: '../../common/parameters.yml#/IndexName'
+ - $ref: '../common/parameters.yml#/Models'
+ - $ref: '../../common/parameters.yml#/ObjectID'
+ responses:
+ '200':
+ $ref: '../../common/responses/DeletedAt.yml'
+ '400':
+ $ref: '../../common/responses/BadRequest.yml'
+ '402':
+ $ref: '../../common/responses/FeatureNotEnabled.yml'
+ '403':
+ $ref: '../../common/responses/MethodNotAllowed.yml'
+ '404':
+ $ref: '../../common/responses/IndexNotFound.yml'
\ No newline at end of file
diff --git a/specs/recommend/paths/searchRecommendRules.yml b/specs/recommend/paths/searchRecommendRules.yml
new file mode 100644
index 0000000000..eed612a53d
--- /dev/null
+++ b/specs/recommend/paths/searchRecommendRules.yml
@@ -0,0 +1,80 @@
+post:
+ tags:
+ - recommendations
+ operationId: searchRecommendRules
+ x-use-read-transporter: true
+ x-cacheable: true
+ summary: List Recommend rules.
+ description: List [Recommend rules](https://www.algolia.com/doc/guides/algolia-recommend/how-to/rules/).
+ parameters:
+ - $ref: '../../common/parameters.yml#/IndexName'
+ - $ref: '../common/parameters.yml#/Models'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ title: searchRecommendRulesParams
+ description: Recommend rules search parameters.
+ additionalProperties: false
+ properties:
+ query:
+ $ref: '../../common/parameters.yml#/query'
+ context:
+ type: string
+ description: Restricts responses to the specified [contextual rule](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/how-to/customize-search-results-by-platform/#creating-contextual-rules).
+ example: 'mobile'
+ page:
+ $ref: '../../common/parameters.yml#/page'
+ hitsPerPage:
+ $ref: '../../common/parameters.yml#/hitsPerPage'
+ enabled:
+ type: boolean
+ nullable: true
+ default: null
+ description: Restricts responses to enabled rules. When absent (default), _all_ rules are retrieved.
+ requestOptions:
+ type: array
+ description: Request options to send with the API call.
+ example: >
+ {timeouts:{read:20}}
+ items:
+ type: object
+ description: Request option.
+ responses:
+ '200':
+ description: OK
+ content:
+ application/json:
+ schema:
+ title: searchRecommendRulesResponse
+ type: object
+ additionalProperties: false
+ required:
+ - hits
+ - nbHits
+ - page
+ - nbPages
+ properties:
+ hits:
+ type: array
+ description: Fetched rules.
+ items:
+ $ref: '../common/schemas/RecommendationsResponse.yml#/ruleResponse'
+ nbHits:
+ type: integer
+ description: Number of fetched rules.
+ page:
+ type: integer
+ description: Current page.
+ nbPages:
+ type: integer
+ description: Number of pages.
+ '400':
+ $ref: '../../common/responses/BadRequest.yml'
+ '402':
+ $ref: '../../common/responses/FeatureNotEnabled.yml'
+ '403':
+ $ref: '../../common/responses/MethodNotAllowed.yml'
+ '404':
+ $ref: '../../common/responses/IndexNotFound.yml'
\ No newline at end of file
diff --git a/specs/recommend/spec.yml b/specs/recommend/spec.yml
index 9d7f70de64..2c4283dc0e 100644
--- a/specs/recommend/spec.yml
+++ b/specs/recommend/spec.yml
@@ -1,7 +1,11 @@
openapi: 3.0.2
info:
title: Recommend API
- description: API powering the Recommend feature of Algolia.
+ description: |-
+ The Recommend API lets you generate recommendations with several AI models.
+
+ > **Note**: You should use Algolia's [libraries and tools](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem/) to interact with the Recommend API. Using the HTTP endpoints directly is not covered by the [SLA](https://www.algolia.com/policies/sla/).
+
version: 1.0.0
components:
securitySchemes:
@@ -35,7 +39,7 @@ security:
apiKey: []
tags:
- name: recommendations
- x-displayName: Recommendations & Trending
+ x-displayName: Recommend
description: Manage recommendations.
x-tagGroups:
- name: General
@@ -50,3 +54,12 @@ paths:
/1/indexes/*/recommendations:
$ref: 'paths/getRecommendations.yml'
+
+ /1/indexes/{indexName}/{model}/recommend/rules/{objectID}:
+ $ref: 'paths/recommendRule.yml'
+
+ /1/indexes/{indexName}/{model}/task/{taskID}:
+ $ref: 'paths/getRecommendStatus.yml'
+
+ /1/indexes/{indexName}/{model}/recommend/rules/search:
+ $ref: 'paths/searchRecommendRules.yml'
\ No newline at end of file
diff --git a/specs/search/common/enums.yml b/specs/search/common/enums.yml
index fcb60bde9f..78e44425e9 100644
--- a/specs/search/common/enums.yml
+++ b/specs/search/common/enums.yml
@@ -1,11 +1,15 @@
searchStrategy:
type: string
enum: [none, stopIfEnoughMatches]
+ description: >
+ - `none`: executes all queries.
+ - `stopIfEnoughMatches`: executes queries one by one, stopping further query execution as soon as a query matches at least the `hitsPerPage` number of results.
operationType:
type: string
enum: [move, copy]
- description: Type of operation to perform (move or copy).
+ example: copy
+ description: Operation to perform (_move_ or _copy_).
scopeType:
type: string
@@ -20,7 +24,7 @@ dictionaryEntryState:
type: string
enum: [enabled, disabled]
default: enabled
- description: The state of the dictionary entry.
+ description: Indicates whether a dictionary entry is active (`enabled`) or inactive (`disabled`).
logType:
type: string
@@ -30,3 +34,4 @@ logType:
taskStatus:
type: string
enum: [published, notPublished]
+ description: _published_ if the task has been processed, _notPublished_ otherwise.
diff --git a/specs/search/common/schemas/BrowseParams.yml b/specs/search/common/schemas/BrowseParams.yml
index 1dd9450c18..fc1cfb6cd0 100644
--- a/specs/search/common/schemas/BrowseParams.yml
+++ b/specs/search/common/schemas/BrowseParams.yml
@@ -14,5 +14,10 @@ cursor:
properties:
cursor:
type: string
- description: Cursor indicating the location to resume browsing from. Must match the value returned by the previous call.
+ description: >
+ Cursor indicating the location to resume browsing from. Must match the value returned by the previous call.
+
+ Pass this value to the subsequent browse call to get the next page of results.
+
+ When the end of the index has been reached, `cursor` is absent from the response.
example: jMDY3M2MwM2QwMWUxMmQwYWI0ZTN
diff --git a/specs/search/common/schemas/Cluster.yml b/specs/search/common/schemas/Cluster.yml
index 6bdb706098..e9759113e3 100644
--- a/specs/search/common/schemas/Cluster.yml
+++ b/specs/search/common/schemas/Cluster.yml
@@ -1,6 +1,6 @@
cluster:
type: object
- description: A cluster.
+ description: Cluster.
properties:
clusterName:
$ref: '#/clusterName'
@@ -30,5 +30,5 @@ dataSize:
clusterName:
type: string
- description: Name of the cluster.
+ description: Cluster name.
example: c11-test
diff --git a/specs/search/common/schemas/Hit.yml b/specs/search/common/schemas/Hit.yml
index b471004d6c..e0906bef78 100644
--- a/specs/search/common/schemas/Hit.yml
+++ b/specs/search/common/schemas/Hit.yml
@@ -33,6 +33,7 @@ highlightResultOption:
matchedWords:
type: array
description: List of words from the query that matched the object.
+ example: ['action']
items:
type: string
fullyHighlighted:
@@ -135,8 +136,8 @@ rankingInfo:
highlightedValue:
type: string
- description: Markup text with occurrences highlighted.
- example: George Clooney
+ description: Markup text with `facetQuery` matches highlighted.
+ example: 'George Clooney'
matchLevel:
type: string
diff --git a/specs/search/common/schemas/SearchQuery.yml b/specs/search/common/schemas/SearchQuery.yml
index 5fe3120c75..2ff02f9759 100644
--- a/specs/search/common/schemas/SearchQuery.yml
+++ b/specs/search/common/schemas/SearchQuery.yml
@@ -18,7 +18,7 @@ searchForFacetsOptions:
properties:
facet:
type: string
- description: The `facet` name.
+ description: Facet name.
indexName:
$ref: '../../../common/parameters.yml#/indexName'
facetQuery:
@@ -35,6 +35,7 @@ searchForFacetsOptions:
facetQuery:
type: string
description: Text to search inside the facet's values.
+ example: 'george'
default: ''
searchForHitsOptions:
@@ -54,10 +55,14 @@ searchTypeFacet:
type: string
enum: [facet]
default: facet
- description: Perform a search query with `default`, will search for facet values if `facet` is given.
+ description: >
+ - `default`: perform a search query
+ - `facet` [searches for facet values](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#search-for-facet-values).
searchTypeDefault:
type: string
enum: [default]
default: default
- description: Perform a search query with `default`, will search for facet values if `facet` is given.
+ description: >
+ - `default`: perform a search query
+ - `facet` [searches for facet values](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#search-for-facet-values).
diff --git a/specs/search/common/schemas/SearchResponse.yml b/specs/search/common/schemas/SearchResponse.yml
index d1da9c6f9d..e902b53a1a 100644
--- a/specs/search/common/schemas/SearchResponse.yml
+++ b/specs/search/common/schemas/SearchResponse.yml
@@ -29,26 +29,28 @@ baseSearchResponse:
properties:
abTestID:
type: integer
- description: If a search encounters an index that is being A/B tested, abTestID reports the ongoing A/B test ID.
+ description: A/B test ID. This is only included in the response for indices that are part of an A/B test.
abTestVariantID:
type: integer
- description: If a search encounters an index that is being A/B tested, abTestVariantID reports the variant ID of the index used (starting at 1).
+ minimum: 1
+ description: Variant ID. This is only included in the response for indices that are part of an A/B test.
aroundLatLng:
type: string
- description: The computed geo location.
+ description: Computed geographical location.
+ example: '40.71,-74.01'
pattern: ^(-?\d+(\.\d+)?),\s*(-?\d+(\.\d+)?)$
automaticRadius:
type: string
- description: The automatically computed radius. For legacy reasons, this parameter is a string and not an integer.
+ description: Automatically-computed radius.
exhaustiveFacetsCount:
type: boolean
- description: Whether the facet count is exhaustive or approximate.
+ description: Indicates whether the facet count is exhaustive (exact) or approximate.
exhaustiveNbHits:
type: boolean
- description: Indicate if the nbHits count was exhaustive or approximate.
+ description: Indicates whether the number of hits `nbHits` is exhaustive (exact) or approximate.
exhaustiveTypo:
type: boolean
- description: Indicate if the typo-tolerance search was exhaustive or approximate (only included when typo-tolerance is enabled).
+ description: Indicates whether the search for typos was exhaustive (exact) or approximate.
facets:
title: facets
type: object
@@ -56,7 +58,7 @@ baseSearchResponse:
type: object
additionalProperties:
type: integer
- description: A mapping of each facet name to the corresponding facet counts.
+ description: Mapping of each facet name to the corresponding facet counts.
example:
category:
food: 1
@@ -72,19 +74,19 @@ baseSearchResponse:
min:
type: number
format: double
- description: The minimum value in the result set.
+ description: Minimum value in the results.
max:
type: number
format: double
- description: The maximum value in the result set.
+ description: Maximum value in the results.
avg:
type: number
format: double
- description: The average facet value in the result set.
+ description: Average facet value in the results.
sum:
type: number
format: double
- description: The sum of all values in the result set.
+ description: Sum of all values in the results.
hitsPerPage:
$ref: '../../../common/schemas/IndexSettings.yml#/hitsPerPage'
index:
@@ -93,28 +95,29 @@ baseSearchResponse:
description: Index name used for the query.
indexUsed:
type: string
- description: Index name used for the query. In the case of an A/B test, the targeted index isn't always the index used by the query.
+ description: Index name used for the query. During A/B testing, the targeted index isn't always the index used by the query.
example: indexNameAlt
message:
type: string
- description: Used to return warnings about the query.
+ description: Warnings about the query.
nbHits:
$ref: '#/nbHits'
nbPages:
$ref: '#/nbPages'
nbSortedHits:
type: integer
- description: The number of hits selected and sorted by the relevant sort algorithm.
+ description: Number of hits selected and sorted by the relevant sort algorithm.
example: 20
page:
$ref: '../../../common/schemas/SearchParams.yml#/page'
params:
type: string
- description: A url-encoded string of all search parameters.
+ description: URL-encoded string of all search parameters.
example: query=a&hitsPerPage=20
redirect:
type: object
- description: This parameter is for internal use only.
+ description: >
+ [Redirect results to a URL](https://www.algolia.com/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/redirects/).
properties:
index:
type: array
@@ -122,7 +125,8 @@ baseSearchResponse:
$ref: '#/RedirectRuleIndexMetadata'
parsedQuery:
type: string
- description: The query string that will be searched, after normalization.
+ description: Post-[normalization](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/#what-does-normalization-mean) query string that will be searched.
+ example: 'george clo'
processingTimeMS:
type: integer
description: Time the server took to process the request, in milliseconds.
@@ -131,10 +135,11 @@ baseSearchResponse:
$ref: '../../../common/schemas/SearchParams.yml#/query'
queryAfterRemoval:
type: string
- description: A markup text indicating which parts of the original query have been removed in order to retrieve a non-empty result set.
+ description: Markup text indicating which parts of the original query have been removed to retrieve a non-empty result set.
serverUsed:
type: string
- description: Actual host name of the server that processed the request.
+ description: Host name of the server that processed the request.
+ example: 'c2-uk-3.algolia.net'
userData:
$ref: '../../../common/schemas/IndexSettings.yml#/userData'
renderingContent:
@@ -142,12 +147,12 @@ baseSearchResponse:
nbHits:
type: integer
- description: Number of hits that the search query matched.
+ description: Number of hits the search query matched.
example: 20
nbPages:
type: integer
- description: Number of pages available for the current query.
+ description: Number of pages of results for the current query.
example: 1
RedirectRuleIndexMetadata:
@@ -164,10 +169,10 @@ RedirectRuleIndexMetadata:
description: Reason for the redirect rule.
succeed:
type: boolean
- description: Status for the redirect rule.
+ description: Redirect rule status.
data:
type: object
- description: Data for the redirect rule.
+ description: Redirect rule data.
required:
- ruleObjectID
properties:
diff --git a/specs/search/common/schemas/UserId.yml b/specs/search/common/schemas/UserId.yml
index 9d175bb290..e0405b1266 100644
--- a/specs/search/common/schemas/UserId.yml
+++ b/specs/search/common/schemas/UserId.yml
@@ -1,13 +1,13 @@
userId:
title: userID
type: object
- description: A userID.
+ description: Unique user ID.
properties:
userID:
$ref: '../../common/parameters.yml#/userID'
clusterName:
type: string
- description: Cluster on which the user is assigned.
+ description: Cluster to which the user is assigned.
example: c1-test
nbRecords:
type: integer
diff --git a/specs/search/common/schemas/listIndicesResponse.yml b/specs/search/common/schemas/listIndicesResponse.yml
index 10b448c4e6..c5901d5b2f 100644
--- a/specs/search/common/schemas/listIndicesResponse.yml
+++ b/specs/search/common/schemas/listIndicesResponse.yml
@@ -4,7 +4,7 @@ listIndicesResponse:
properties:
items:
type: array
- description: List of the fetched indices.
+ description: All indices in your Algolia application.
items:
$ref: '#/fetchedIndex'
nbPages:
@@ -21,23 +21,29 @@ fetchedIndex:
name:
type: string
description: Index name.
+ example: 'movies'
createdAt:
type: string
description: Index creation date. An empty string means that the index has no records.
+ example: '2022-09-19T16:36:44.471Z'
updatedAt:
$ref: '../../../common/responses/common.yml#/updatedAt'
entries:
type: integer
description: Number of records contained in the index.
+ example: 100
dataSize:
type: integer
description: Number of bytes of the index in minified format.
+ example: 48450
fileSize:
type: integer
description: Number of bytes of the index binary file.
+ example: 112927
lastBuildTimeS:
type: integer
description: Last build time.
+ example: 3
numberOfPendingTasks:
type: integer
default: 0
@@ -49,11 +55,13 @@ fetchedIndex:
primary:
type: string
description: Only present if the index is a replica. Contains the name of the related primary index.
+ example: 'T02'
replicas:
type: array
items:
type: string
description: Only present if the index is a primary index with replicas. Contains the names of all linked replicas.
+ example: ['T02_push','T2replica']
required:
- name
- createdAt
diff --git a/specs/search/paths/advanced/getLogs.yml b/specs/search/paths/advanced/getLogs.yml
index b22cc2738c..09be353aca 100644
--- a/specs/search/paths/advanced/getLogs.yml
+++ b/specs/search/paths/advanced/getLogs.yml
@@ -2,25 +2,33 @@ get:
tags:
- Advanced
operationId: getLogs
- description: Return the latest log entries.
+ description: >
+ The request must be authenticated by an API key with the [`logs` ACL](https://www.algolia.com/doc/guides/security/api-keys/#access-control-list-acl).
+
+ Logs are held for the last seven days. There's also a logging limit of 1,000 API calls per server.
+
+ This request counts towards your [operations quota](https://support.algolia.com/hc/en-us/articles/4406981829777-How-does-Algolia-count-records-and-operations-) but doesn't appear in the logs itself.
+
+ > **Note**: To fetch the logs for a Distributed Search Network (DSN) cluster, target the [DSN's endpoint](https://www.algolia.com/doc/guides/scaling/distributed-search-network-dsn/#accessing-dsn-servers).
summary: Return the latest log entries.
parameters:
- name: offset
in: query
- description: First entry to retrieve (zero-based). Log entries are sorted by decreasing date, therefore 0 designates the most recent log entry.
+ description: First log entry to retrieve. Sorted by decreasing date with 0 being the most recent.
schema:
type: integer
default: 0
- name: length
in: query
- description: Maximum number of entries to retrieve. The maximum allowed value is 1000.
+ description: Maximum number of entries to retrieve.
schema:
type: integer
default: 10
maximum: 1000
- name: indexName
in: query
- description: Index for which log entries should be retrieved. When omitted, log entries are retrieved across all indices.
+ description: Index for which log entries should be retrieved. When omitted, log entries are retrieved for all indices.
+ example: 'products'
schema:
type: string
nullable: true
@@ -49,49 +57,64 @@ get:
properties:
timestamp:
type: string
- description: Timestamp in ISO-8601 format.
+ description: Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.
+ example: '2023-03-08T12:34:56Z'
method:
type: string
description: HTTP method of the performed request.
+ example: 'GET'
answer_code:
type: string
description: HTTP response code.
+ example: '200'
query_body:
type: string
- description: Request body. Truncated after 1000 characters.
+ description: Request body. Truncated after 1,000 characters.
+ example: '\n{\n \"requests\": [\n {\n \"indexName\": \"best_buy\",\n \"params\": \"query=&hitsPerPage=10&page=0&attributesToRetrieve=*&highlightPreTag=%3Cais-highlight-0000000000%3E&highlightPostTag=%3C%2Fais-highlight-0000000000%3E&getRankingInfo=1&facets=%5B%22brand%22%2C%22categories%22%2C%22free_shipping%22%2C%22type%22%5D&tagFilters=\"\n }\n ]\n}\n'
answer:
type: string
- description: Answer body. Truncated after 1000 characters.
+ description: Answer body. Truncated after 1,000 characters.
+ example: >
+ 'n{\n \"results\": [\n {\n \"hits\": [\n {\n \"name\": \"Amazon - Fire TV Stick\",\n \"description\": \"Amazon Fire TV Stick connects to your TV's HDMI port. Just grab and go to enjoy Netflix, Prime Instant Video, Hulu Plus, YouTube.com, music, and much more.\",\n \"brand\": \"Amazon\",\n \"categories\": [\n \"TV & Home Theater\",\n \"Streaming Media Players\"\n ],\n \"hierarchicalCategories\": {\n \"lvl0\": \"TV & Home Theater\",\n \"lvl1\": \"TV & Home Theater > Streaming Media Players\"\n },\n \"type\": \"Streaming media plyr\",\n \"price\": 39.99,\n \"price_range\": \"1 - 50\",\n \"image\": \"https:\/\/cdn-demo.algolia.com\/bestbuy\/9999119_sb.jpg\",\n \"url\": \"http:\/\/www.bestbuy.com\/site\/amazon-fire-tv-stick\/9999119.p?id=1219460752591&skuId=9999119&cmp=RMX&ky=1uWSHMdQqBeVJB9cXgEke60s5EjfS6M1W\",\n \"free_shipping\": false,\n \"popularity\": 9843,\n \"rating\": 4,\n \"objectID\": \"9999119\"\n'
url:
type: string
description: Request URL.
+ example: '/1/indexes'
ip:
type: string
- description: IP of the client which performed the request.
+ description: IP address of the client that performed the request.
+ example: '127.0.0.1'
query_headers:
type: string
- description: Request Headers (API Key is obfuscated).
+ description: Request headers (API key is obfuscated).
+ example: 'User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8x zlib/1.2.5\nHost: localhost.algolia.com:8080\nAccept: */*\nContent-Type: application/json; charset=utf-8\nX-Algolia-API-Key: 20f***************************\nX-Algolia-Application-Id: MyApplicationID\n'
sha1:
type: string
description: SHA1 signature of the log entry.
+ example: '26c53bd7e38ca71f4741b71994cd94a600b7ac68'
nb_api_calls:
type: string
description: Number of API calls.
+ example: '1'
processing_time_ms:
type: string
- description: Processing time for the query. It doesn't include network time.
+ description: Processing time for the query. Doesn't include network time.
+ example: '2'
index:
type: string
description: Index targeted by the query.
+ example: 'best_buy'
query_params:
type: string
description: Query parameters sent with the request.
+ example: 'query=georgia&attributesToRetrieve=name,city,country'
query_nb_hits:
type: string
description: Number of hits returned for the query.
+ example: '1'
inner_queries:
type: array
- description: Array of all performed queries for the given request.
+ description: Performed queries for the given request.
items:
type: object
title: logQuery
@@ -99,12 +122,15 @@ get:
index_name:
type: string
description: Index targeted by the query.
+ example: 'best_buy'
user_token:
type: string
description: User identifier.
+ example: '93.189.166.128'
query_id:
type: string
- description: QueryID for the given query.
+ description: Unique query identifier.
+ example: '313453231'
required:
- timestamp
- method
diff --git a/specs/search/paths/advanced/getTask.yml b/specs/search/paths/advanced/getTask.yml
index 2299ba3f8b..800d4cce0d 100644
--- a/specs/search/paths/advanced/getTask.yml
+++ b/specs/search/paths/advanced/getTask.yml
@@ -2,18 +2,18 @@ get:
tags:
- Indices
operationId: getTask
- description: Check the current status of a given task.
- summary: Check the status of a task.
+ description: Some operations, such as copying an index, will respond with a `taskID` value. Use this value here to check the status of that task.
+ summary: Check a task's status.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- name: taskID
in: path
- description: Unique identifier of an task. Numeric value (up to 64bits).
+ description: Unique task identifier.
required: true
schema:
type: integer
format: int64
- example: 13235
+ example: 1506303845001
responses:
'200':
description: OK
diff --git a/specs/search/paths/dictionaries/batchDictionaryEntries.yml b/specs/search/paths/dictionaries/batchDictionaryEntries.yml
index a3c35b98ed..0e9eca9d72 100644
--- a/specs/search/paths/dictionaries/batchDictionaryEntries.yml
+++ b/specs/search/paths/dictionaries/batchDictionaryEntries.yml
@@ -2,7 +2,7 @@ post:
tags:
- Dictionaries
operationId: batchDictionaryEntries
- description: Send a batch of dictionary entries.
+ description: Add or remove a batch of dictionary entries.
summary: Batch dictionary entries.
parameters:
- $ref: 'common/parameters.yml#/DictionaryName'
@@ -12,7 +12,8 @@ post:
application/json:
schema:
title: batchDictionaryEntriesParams
- description: The `batchDictionaryEntries` parameters.
+ description: >
+ `batchDictionaryEntries` parameters.
type: object
required:
- requests
@@ -21,10 +22,10 @@ post:
clearExistingDictionaryEntries:
type: boolean
default: false
- description: When `true`, start the batch by removing all the custom entries from the dictionary.
+ description: Incidates whether to replace all custom entries in the dictionary with the ones sent with this request.
requests:
type: array
- description: List of operations to batch. Each operation is described by an `action` and a `body`.
+ description: Operations to batch.
items:
title: batchDictionaryEntriesRequest
type: object
diff --git a/specs/search/paths/dictionaries/common/parameters.yml b/specs/search/paths/dictionaries/common/parameters.yml
index dba15e24ad..267628e7fd 100644
--- a/specs/search/paths/dictionaries/common/parameters.yml
+++ b/specs/search/paths/dictionaries/common/parameters.yml
@@ -2,7 +2,7 @@
DictionaryName:
in: path
name: dictionaryName
- description: The dictionary to search in.
+ description: Dictionary to search in.
required: true
schema:
$ref: '#/dictionaryType'
@@ -13,12 +13,14 @@ dictionaryType:
# misc
language:
- description: Language ISO code supported by the dictionary (e.g., "en" for English).
+ description: >
+ [Supported language ISO code](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/).
+ example: 'en'
type: string
standardEntries:
- description: Map of language ISO code supported by the dictionary (e.g., "en" for English) to a boolean value.
- type: object
+ description: >
+ Key-value pairs of [supported language ISO codes](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/) and boolean values.
additionalProperties: false
properties:
plurals:
@@ -29,7 +31,9 @@ standardEntries:
$ref: '#/standardEntry'
standardEntry:
- description: Language ISO code.
+ description: Key-value pair of a language ISO code and a boolean value.
+ example: >
+ {'fr': false}
type: object
nullable: true
additionalProperties:
diff --git a/specs/search/paths/dictionaries/common/schemas/Languages.yml b/specs/search/paths/dictionaries/common/schemas/Languages.yml
index 4a6fdd31e4..cfa8350b29 100644
--- a/specs/search/paths/dictionaries/common/schemas/Languages.yml
+++ b/specs/search/paths/dictionaries/common/schemas/Languages.yml
@@ -1,6 +1,6 @@
languages:
type: object
- description: A dictionary language.
+ description: Dictionary language.
additionalProperties: false
required:
- plurals
@@ -20,6 +20,9 @@ dictionaryLanguage:
nullable: true
description: Custom entries for a dictionary.
properties:
- nbCustomEntires:
- description: "When nbCustomEntries is set to 0, the user didn't customize the dictionary. The dictionary is still supported with standard, Algolia-provided entries."
+ nbCustomEntries:
+ description: >
+ If `0`, the dictionary hasn't been customized and only contains standard entries provided by Algolia.
+
+ If `null`, that feature isn't available or isn't supported for that language.
type: integer
diff --git a/specs/search/paths/dictionaries/common/schemas/SearchDictionaryEntriesResponse.yml b/specs/search/paths/dictionaries/common/schemas/SearchDictionaryEntriesResponse.yml
index 6f9b89f29a..1243706610 100644
--- a/specs/search/paths/dictionaries/common/schemas/SearchDictionaryEntriesResponse.yml
+++ b/specs/search/paths/dictionaries/common/schemas/SearchDictionaryEntriesResponse.yml
@@ -16,28 +16,51 @@ searchDictionaryEntriesResponse:
dictionaryEntry:
type: object
- description: A dictionary entry.
+ description: Dictionary entry.
additionalProperties: true
required:
- objectID
- language
properties:
objectID:
- $ref: '../../../../../common/parameters.yml#/objectID'
+ type: string
+ description: Unique identifier for a dictionary object.
+ example: 'under'
language:
type: string
- description: Language ISO code supported by the dictionary (e.g., "en" for English).
+ description: >
+ [Supported language ISO code](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/).
+ example: 'de'
word:
type: string
- description: The word of the dictionary entry.
+ description: >
+ Dictionary entry word. Usage depends on the type of dictionary entry.
+
+ **`stopwordEntry`**
+
+ The stop word you want to add or update. If the entry already exists in Algolia's standard dictionary, you can override its behavior by adding it to the custom dictionary and setting its `state` to `disabled`.
+
+ **`compoundEntry`**
+
+ When `decomposition` is empty: adds `word` as a compound atom.
+ For example, atom “kino” decomposes the query “kopfkino” into "kopf" and "kino".
+
+ When `decomposition` isn't empty: creates a decomposition exception.
+ For example, when decomposition is set to the ["hund", "hutte"] exception, "hundehutte" decomposes into “hund” and “hutte”, discarding the linking "e".
+ example: 'down'
words:
type: array
- description: The words of the dictionary entry.
+ description: >
+ Compound dictionary [word declensions](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-plurals-and-other-declensions/).
+
+ If the entry already exists in Algolia's standard dictionary, you can override its behavior by adding it to the custom dictionary and setting its `state` to `disabled`.
+ example: ['cheval','chevaux']
items:
type: string
decomposition:
type: array
- description: A decomposition of the word of the dictionary entry.
+ description: For compound entries, governs the behavior of the `word` parameter.
+ example: ['kopf','schmerz','tablette']
items:
type: string
state:
diff --git a/specs/search/paths/dictionaries/dictionarySettings.yml b/specs/search/paths/dictionaries/dictionarySettings.yml
index e995931916..3b383575fb 100644
--- a/specs/search/paths/dictionaries/dictionarySettings.yml
+++ b/specs/search/paths/dictionaries/dictionarySettings.yml
@@ -2,8 +2,8 @@ get:
tags:
- Dictionaries
operationId: getDictionarySettings
- description: Retrieve dictionaries settings. The API stores languages whose standard entries are disabled. Fetch settings does not return false values.
- summary: Retrieve dictionaries settings.
+ description: Get the languages for which [stop words are turned off](#tag/Dictionaries/operation/setDictionarySettings).
+ summary: Get stop word settings.
responses:
'200':
description: OK
@@ -31,8 +31,8 @@ put:
tags:
- Dictionaries
operationId: setDictionarySettings
- description: Set dictionaries settings.
- summary: Set dictionaries settings.
+ description: Set stop word settings for a specific language.
+ summary: Set stop word settings.
requestBody:
required: true
content:
@@ -41,7 +41,7 @@ put:
title: dictionarySettingsParams
type: object
additionalProperties: false
- description: Disable the builtin Algolia entries for a type of dictionary per language.
+ description: Enable or turn off the built-in Algolia stop words for a specific language.
required:
- disableStandardEntries
properties:
diff --git a/specs/search/paths/dictionaries/getDictionaryLanguages.yml b/specs/search/paths/dictionaries/getDictionaryLanguages.yml
index 4d8abb6e30..1152bccd5d 100644
--- a/specs/search/paths/dictionaries/getDictionaryLanguages.yml
+++ b/specs/search/paths/dictionaries/getDictionaryLanguages.yml
@@ -2,7 +2,7 @@ get:
tags:
- Dictionaries
operationId: getDictionaryLanguages
- description: List dictionaries supported per language.
+ description: Lists Algolia's [supported languages](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/) and any customizations applied to each language's [stop word](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/), [plural](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-plurals-and-other-declensions/), and [segmentation (compound)](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-segmentation/) features.
summary: List available languages.
responses:
'200':
diff --git a/specs/search/paths/dictionaries/searchDictionaryEntries.yml b/specs/search/paths/dictionaries/searchDictionaryEntries.yml
index 853f2e6acc..604635f8d4 100644
--- a/specs/search/paths/dictionaries/searchDictionaryEntries.yml
+++ b/specs/search/paths/dictionaries/searchDictionaryEntries.yml
@@ -4,8 +4,8 @@ post:
operationId: searchDictionaryEntries
x-use-read-transporter: true
x-cacheable: true
- description: Search the dictionary entries.
- summary: Search a dictionary entries.
+ description: Search for standard and [custom](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/) entries in the [stop words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/), [plurals](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-plurals-and-other-declensions/), or [segmentation (compounds)](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-segmentation/) dictionaries.
+ summary: Search dictionary entries.
parameters:
- $ref: 'common/parameters.yml#/DictionaryName'
requestBody:
@@ -14,7 +14,8 @@ post:
application/json:
schema:
title: searchDictionaryEntriesParams
- description: The `searchDictionaryEntries` parameters.
+ description: >
+ `searchDictionaryEntries` parameters.
type: object
required:
- query
diff --git a/specs/search/paths/keys/common/parameters.yml b/specs/search/paths/keys/common/parameters.yml
index be5505567e..e9637fd79a 100644
--- a/specs/search/paths/keys/common/parameters.yml
+++ b/specs/search/paths/keys/common/parameters.yml
@@ -4,5 +4,5 @@ KeyString:
required: true
schema:
type: string
- example: myAPIKey
- description: API Key string.
+ example: YourAPIKey
+ description: API key.
diff --git a/specs/search/paths/keys/common/schemas.yml b/specs/search/paths/keys/common/schemas.yml
index 86760ceda5..dd57083822 100644
--- a/specs/search/paths/keys/common/schemas.yml
+++ b/specs/search/paths/keys/common/schemas.yml
@@ -1,52 +1,89 @@
apiKey:
type: object
- description: Api Key object.
+ description: API key object.
additionalProperties: false
properties:
acl:
type: array
- description: Set of permissions associated with the key.
+ description: >
+ [Permissions](https://www.algolia.com/doc/guides/security/api-keys/#access-control-list-acl) associated with the key.
+ example: ['search','addObject']
default: []
items:
$ref: '#/acl'
description:
type: string
- description: A comment used to identify a key more easily in the dashboard. It is not interpreted by the API.
+ description: Description of an API key for you and your team members.
+ example: 'Browse-restricted key'
default: ''
indexes:
type: array
- description: Restrict this new API key to a list of indices or index patterns. If the list is empty, all indices are allowed.
+ description: >
+ Restricts this API key to a list of indices or index patterns. If the list is empty, all indices are allowed.
+
+ Specify either an exact index name or a pattern with a leading or trailing wildcard character (or both). For example:
+
+ - `dev_*` matches all indices starting with "dev_"
+ - `*_dev` matches all indices ending with "_dev"
+ - `*_products_*` matches all indices containing "_products_".
+ example: ['dev_*','prod_products']
default: []
items:
type: string
maxHitsPerQuery:
type: integer
- description: Maximum number of hits this API key can retrieve in one query. If zero, no limit is enforced.
+ description: >
+ Maximum number of hits this API key can retrieve in one query. If zero, no limit is enforced.
+
+ > **Note**: Use this parameter to protect you from third-party attempts to retrieve your entire content by massively querying the index.
default: 0
maxQueriesPerIPPerHour:
type: integer
- description: Maximum number of API calls per hour allowed from a given IP address or a user token.
+ description: >
+ Maximum number of API calls per hour allowed from a given IP address or [user token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken/).
+
+ Each time an API call is performed with this key, a check is performed. If there were more than the specified number of calls within the last hour, the API returns an error with the status code `429` (Too Many Requests).
+
+
+ > **Note**: Use this parameter to protect you from third-party attempts to retrieve your entire content by massively querying the index.
default: 0
queryParameters:
type: string
- description: URL-encoded query string. Force some query parameters to be applied for each query made with this API key.
+ description: >
+ Force some [query parameters](https://www.algolia.com/doc/api-reference/api-parameters/) to be applied for each query made with this API key.
+
+ It's a URL-encoded query string.
+ example: 'typoTolerance%3Dstrict%26ignorePlurals%3Dfalse%26filters%3Drights%3Apublic'
default: ''
referers:
type: array
- description: Restrict this new API key to specific referers. If empty or blank, defaults to all referers.
+ description: >
+ Restrict this API key to specific [referrers](https://www.algolia.com/doc/guides/security/api-keys/in-depth/api-key-restrictions/#http-referrers). If empty, all referrers are allowed.
+
+ For example:
+
+ - `https://algolia.com/*` matches all referrers starting with "https://algolia.com/"
+ - `*.algolia.com` matches all referrers ending with ".algolia.com"
+ - `*algolia.com*` allows everything in the domain "algolia.com".
+ example: ['*algolia.com*']
default: []
items:
type: string
validity:
type: integer
- description: Validity limit for this key in seconds. The key will automatically be removed after this period of time.
+ description: >
+ Validity duration of a key (in seconds). The key will automatically be removed after this time has expired. The default value of 0 never expires.
+
+ Short-lived API keys are useful to grant temporary access to your data. For example, in mobile apps, you can't [control when users update your app](https://www.algolia.com/doc/guides/security/security-best-practices/#use-secured-api-keys-in-mobile-apps). So instead of encoding keys into your app as you would for a web app, you should dynamically fetch them from your mobile app's backend.
+ example: 86400
default: 0
required:
- acl
keyString:
type: string
- description: The API key.
+ description: API key.
+ example: '13ad45b4d0a2f6ea65ecbddf6aa260f2'
getApiKeyResponse:
allOf:
@@ -79,20 +116,20 @@ addApiKeyResponse:
acl:
description: |
- List of rights for the API key. The following rights can be used:
+ API key permissions:
- addObject: allows to add/update an object in the index (copy/move index are also allowed with this right).
- analytics: allows to retrieve the analytics through the Analytics API.
- browse: allows to retrieve all index content via the browse API.
- deleteIndex: allows to delete or clear index content.
- deleteObject: allows to delete objects from the index.
- editSettings: allows to change index settings.
- listIndexes: allows to list all accessible indices.
- logs: allows to get the logs.
- recommendation: Allows usage of the Personalization dashboard and the Recommendation API.
- search: allows to search the index.
- seeUnretrievableAttributes: disable unretrievableAttributes feature for all operations returning records.
- settings: allows to get index settings.
+ `addObject`: required to add or update records, copy or move an index.
+ `analytics`: required to access the Analytics API.
+ `browse`: required to view records
+ `deleteIndex`: required to delete indices.
+ `deleteObject`: required to delete records.
+ `editSettings`: required to change index settings.
+ `listIndexes`: required to list indices.
+ `logs`: required to access logs of search and indexing operations.
+ `recommendation`: required to access the Personalization and Recommend APIs.
+ `search`: required to search records
+ `seeUnretrievableAttributes`: required to retrieve [`unretrievableAttributes`](https://www.algolia.com/doc/api-reference/api-parameters/unretrievableAttributes/) for all operations that return records.
+ `settings`: required to examine index settings.
type: string
enum:
- addObject
diff --git a/specs/search/paths/keys/key.yml b/specs/search/paths/keys/key.yml
index 71b8f60f15..a2aaa679a5 100644
--- a/specs/search/paths/keys/key.yml
+++ b/specs/search/paths/keys/key.yml
@@ -2,8 +2,12 @@ get:
tags:
- Api Keys
operationId: getApiKey
- summary: Get an API key.
- description: Get the permissions of an API key.
+ summary: Get API key permissions.
+ description: >
+ Get the permissions and restrictions of a specific API key.
+
+ When authenticating with the admin API key, you can request information for any of your application's keys.
+ When authenticating with other API keys, you can only retrieve information for that key.
parameters:
- $ref: 'common/parameters.yml#/KeyString'
responses:
@@ -27,7 +31,12 @@ put:
- Api Keys
operationId: updateApiKey
summary: Update an API key.
- description: Replace every permission of an existing API key.
+ description: >
+ Replace the permissions of an existing API key.
+
+ Any unspecified parameter resets that permission to its default value.
+
+ The request must be authenticated with the admin API key.
parameters:
- $ref: 'common/parameters.yml#/KeyString'
requestBody:
@@ -66,8 +75,11 @@ delete:
tags:
- Api Keys
operationId: deleteApiKey
- summary: Delete an API key.
- description: Delete an existing API Key.
+ summary: Delete API key.
+ description: >
+ Delete an existing API key.
+
+ The request must be authenticated with the admin API key.
parameters:
- $ref: 'common/parameters.yml#/KeyString'
responses:
diff --git a/specs/search/paths/keys/keys.yml b/specs/search/paths/keys/keys.yml
index b3fa1ff126..556084c028 100644
--- a/specs/search/paths/keys/keys.yml
+++ b/specs/search/paths/keys/keys.yml
@@ -2,8 +2,8 @@ get:
tags:
- Api Keys
operationId: listApiKeys
- summary: List API Keys.
- description: List API keys, along with their associated rights.
+ summary: List API keys.
+ description: List all API keys associated with your Algolia application, including their permissions and restrictions.
responses:
'200':
description: OK
@@ -18,7 +18,7 @@ get:
properties:
keys:
type: array
- description: List of api keys.
+ description: API keys.
items:
$ref: 'common/schemas.yml#/getApiKeyResponse'
'400':
@@ -34,8 +34,13 @@ post:
tags:
- Api Keys
operationId: addApiKey
- summary: Create an API key.
- description: Add a new API Key with specific permissions/restrictions.
+ summary: Add API key.
+ description: >
+ Add a new API key with specific permissions and restrictions.
+
+ The request must be authenticated with the admin API key.
+
+ The response returns an API key string.
requestBody:
required: true
content:
diff --git a/specs/search/paths/keys/restoreApiKey.yml b/specs/search/paths/keys/restoreApiKey.yml
index f98dcc9cdb..c3ebe64396 100644
--- a/specs/search/paths/keys/restoreApiKey.yml
+++ b/specs/search/paths/keys/restoreApiKey.yml
@@ -2,8 +2,11 @@ post:
tags:
- Api Keys
operationId: restoreApiKey
- summary: Restore an API key.
- description: Restore a deleted API key, along with its associated rights.
+ summary: Restore API key.
+ description: >
+ Restore a deleted API key, along with its associated permissions.
+
+ The request must be authenticated with the admin API key.
parameters:
- $ref: 'common/parameters.yml#/KeyString'
responses:
diff --git a/specs/search/paths/manage_indices/listIndices.yml b/specs/search/paths/manage_indices/listIndices.yml
index 3baf1de929..186197b43f 100644
--- a/specs/search/paths/manage_indices/listIndices.yml
+++ b/specs/search/paths/manage_indices/listIndices.yml
@@ -2,10 +2,11 @@ get:
tags:
- Indices
operationId: listIndices
- summary: List existing indexes.
- description: List existing indexes from an application.
+ summary: List indices.
+ description: List indices in an Algolia application.
parameters:
- $ref: '../../../common/parameters.yml#/Page'
+ - $ref: '../../../common/parameters.yml#/HitsPerPage'
responses:
'200':
description: OK
diff --git a/specs/search/paths/manage_indices/operationIndex.yml b/specs/search/paths/manage_indices/operationIndex.yml
index 638897ad19..5bcb4218f7 100644
--- a/specs/search/paths/manage_indices/operationIndex.yml
+++ b/specs/search/paths/manage_indices/operationIndex.yml
@@ -2,8 +2,18 @@ post:
tags:
- Indices
operationId: operationIndex
- summary: Copy/move index.
- description: Performs a copy or a move operation on a index.
+ summary: Copy, move, or rename an index.
+ description: |-
+ This `operation`, _copy_ or _move_, will copy or move a source index's (`IndexName`) records, settings, synonyms, and rules to a `destination` index.
+ If the destination index exists, it will be replaced, except for index-specific API keys and analytics data.
+ If the destination index doesn't exist, it will be created.
+
+ The choice between moving or copying an index depends on your needs. Choose:
+
+ - **Move** to rename an index.
+ - **Copy** to create a new index with the same records and configuration as an existing one.
+
+ > **Note**: When considering copying or moving, be aware of the [rate limitations](https://www.algolia.com/doc/guides/scaling/algolia-service-limits/#application-record-and-index-limits) on these processes and the [impact on your analytics data](https://www.algolia.com/doc/guides/sending-and-managing-data/manage-indices-and-apps/manage-indices/concepts/indices-analytics/).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
@@ -23,7 +33,12 @@ post:
type: array
items:
$ref: '../../common/enums.yml#/scopeType'
- description: Scope of the data to copy. When absent, a full copy is performed. When present, only the selected scopes are copied.
+ description: |-
+ **This only applies to the _copy_ operation.**
+
+ If you omit `scope`, the copy command copies all records, settings, synonyms, and rules.
+
+ If you specify `scope`, only the specified scopes are copied.
required:
- operation
- destination
diff --git a/specs/search/paths/multiclusters/batchAssignUserIds.yml b/specs/search/paths/multiclusters/batchAssignUserIds.yml
index 9264861c50..eeaf5104da 100644
--- a/specs/search/paths/multiclusters/batchAssignUserIds.yml
+++ b/specs/search/paths/multiclusters/batchAssignUserIds.yml
@@ -4,11 +4,9 @@ post:
operationId: batchAssignUserIds
summary: Batch assign userIDs.
description: >
- Assign multiple userIDs to a cluster.
+ Assign multiple user IDs to a cluster.
- Upon success, the response is 200 OK.
-
- A successful response indicates that the operation has been taken into account, and the userIDs are directly usable.
+ **You can't _move_ users with this operation.**.
parameters:
- $ref: '../../common/parameters.yml#/UserIDInHeader'
requestBody:
@@ -25,7 +23,8 @@ post:
$ref: '../../common/schemas/Cluster.yml#/clusterName'
users:
type: array
- description: userIDs to assign. Note you cannot move users with this method.
+ description: User IDs to assign.
+ example: ['einstein','bohr','feynman']
items:
type: string
required:
diff --git a/specs/search/paths/multiclusters/getTopUserIds.yml b/specs/search/paths/multiclusters/getTopUserIds.yml
index 159fcaf633..6f9215f790 100644
--- a/specs/search/paths/multiclusters/getTopUserIds.yml
+++ b/specs/search/paths/multiclusters/getTopUserIds.yml
@@ -4,11 +4,10 @@ get:
operationId: getTopUserIds
summary: Get top userID.
description: >
- Get the top 10 userIDs with the highest number of records per cluster.
+ Get the IDs of the 10 users with the highest number of records per cluster.
- The data returned will usually be a few seconds behind real time, because userID usage may take up to a few seconds to propagate to the different clusters.
-
- Upon success, the response is 200 OK and contains the following array of userIDs and clusters.
+ Since it can take up to a few seconds to get the data from the different clusters,
+ the response isn't real-time.
responses:
'200':
description: OK
@@ -17,11 +16,11 @@ get:
schema:
title: getTopUserIdsResponse
type: object
- description: Array of userIDs and clusters.
+ description: User IDs and clusters.
properties:
topUsers:
type: array
- description: Mapping of cluster names to top users.
+ description: Key-value pairs with cluster names as keys and lists of users with the highest number of records per cluster as values.
items:
type: object
additionalProperties:
diff --git a/specs/search/paths/multiclusters/hasPendingMappings.yml b/specs/search/paths/multiclusters/hasPendingMappings.yml
index e3c03557e5..1dfabb1d81 100644
--- a/specs/search/paths/multiclusters/hasPendingMappings.yml
+++ b/specs/search/paths/multiclusters/hasPendingMappings.yml
@@ -2,19 +2,13 @@ get:
tags:
- Clusters
operationId: hasPendingMappings
- summary: Get migration status.
+ summary: Get migration and user mapping status.
description: >
- Get the status of your clusters' migrations or user creations.
-
- Creating a large batch of users or migrating your multi-cluster may take quite some time. This method lets you retrieve the status of the migration, so you can know when it's done.
-
- Upon success, the response is 200 OK.
-
- A successful response indicates that the operation has been taken into account, and the userIDs are directly usable.
+ To determine when the time-consuming process of creating a large batch of users or migrating users from one cluster to another is complete, this operation retrieves the status of the process.
parameters:
- in: query
name: getClusters
- description: If the clusters pending mapping state should be on the response.
+ description: Indicates whether to include the cluster's pending mapping state in the response.
schema:
type: boolean
responses:
@@ -28,10 +22,11 @@ get:
additionalProperties: false
properties:
pending:
- description: If there is any clusters with pending mapping state.
+ description: Indicates whether there are clusters undergoing migration, creation, or deletion.
type: boolean
clusters:
- description: Describe cluster pending (migrating, creating, deleting) mapping state.
+ description: >
+ Cluster pending mapping state: migrating, creating, deleting.
type: object
additionalProperties:
type: array
diff --git a/specs/search/paths/multiclusters/listClusters.yml b/specs/search/paths/multiclusters/listClusters.yml
index 397000faed..3e8512681c 100644
--- a/specs/search/paths/multiclusters/listClusters.yml
+++ b/specs/search/paths/multiclusters/listClusters.yml
@@ -3,10 +3,7 @@ get:
- Clusters
operationId: listClusters
summary: List clusters.
- description: >
- List the clusters available in a multi-clusters setup for a single appID.
-
- Upon success, the response is 200 OK and contains the following clusters.
+ description: List the available clusters in a multi-cluster setup.
responses:
'200':
description: OK
@@ -15,11 +12,11 @@ get:
schema:
title: listClustersResponse
type: object
- description: Array of clusters.
+ description: Clusters.
properties:
topUsers:
type: array
- description: Mapping of cluster names to top users.
+ description: Key-value pairs with cluster names as keys and lists of users with the highest number of records per cluster as values.
items:
$ref: '../../common/schemas/Cluster.yml#/clusterName'
required:
diff --git a/specs/search/paths/multiclusters/searchUserIds.yml b/specs/search/paths/multiclusters/searchUserIds.yml
index 4e3769f34b..96941cff43 100644
--- a/specs/search/paths/multiclusters/searchUserIds.yml
+++ b/specs/search/paths/multiclusters/searchUserIds.yml
@@ -4,15 +4,12 @@ post:
operationId: searchUserIds
x-use-read-transporter: true
x-cacheable: true
- summary: Search userID.
+ summary: Search for a user ID.
description: >
- Search for userIDs.
-
- The data returned will usually be a few seconds behind real time, because userID usage may take up to a few seconds propagate to the different clusters.
-
- To keep updates moving quickly, the index of userIDs isn't built synchronously with the mapping. Instead, the index is built once every 12h, at the same time as the update of userID usage. For example, when you perform a modification like adding or moving a userID, the search will report an outdated value until the next rebuild of the mapping, which takes place every 12h.
-
- Upon success, the response is 200 OK and contains the following userIDs data.
+ Since it can take up to a few seconds to get the data from the different clusters,
+ the response isn't real-time.
+
+ To ensure rapid updates, the user IDs index isn't built at the same time as the mapping. Instead, it's built every 12 hours, at the same time as the update of user ID usage. For example, if you add or move a user ID, the search will show an old value until the next time the mapping is rebuilt (every 12 hours).
requestBody:
required: true
content:
@@ -25,7 +22,7 @@ post:
properties:
query:
type: string
- description: Query to search. The search is a prefix search with typoTolerance. Use empty query to retrieve all users.
+ description: Query to search. The search is a prefix search with [typo tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/) enabled. An empty query will retrieve all users.
clusterName:
$ref: '../../common/schemas/Cluster.yml#/clusterName'
page:
@@ -46,7 +43,7 @@ post:
properties:
hits:
type: array
- description: List of user object matching the query.
+ description: User objects that match the query.
items:
title: userHit
type: object
diff --git a/specs/search/paths/multiclusters/userId.yml b/specs/search/paths/multiclusters/userId.yml
index bbca43d11c..881d9a0e38 100644
--- a/specs/search/paths/multiclusters/userId.yml
+++ b/specs/search/paths/multiclusters/userId.yml
@@ -6,9 +6,8 @@ get:
description: >
Returns the userID data stored in the mapping.
- The data returned will usually be a few seconds behind real time, because userID usage may take up to a few seconds to propagate to the different clusters.
-
- Upon success, the response is 200 OK and contains the following userID data.
+ Since it can take up to a few seconds to get the data from the different clusters,
+ the response isn't real-time.
parameters:
- $ref: '../../common/parameters.yml#/UserIDInPath'
responses:
@@ -32,10 +31,7 @@ delete:
- Clusters
operationId: removeUserId
summary: Remove userID.
- description: >
- Remove a userID and its associated data from the multi-clusters.
-
- Upon success, the response is 200 OK and a task is created to remove the userID data and mapping.
+ description: Remove a userID and its associated data from the multi-clusters.
parameters:
- $ref: '../../common/parameters.yml#/UserIDInPath'
responses:
diff --git a/specs/search/paths/multiclusters/userIds.yml b/specs/search/paths/multiclusters/userIds.yml
index 179d2527b6..ce77d7350f 100644
--- a/specs/search/paths/multiclusters/userIds.yml
+++ b/specs/search/paths/multiclusters/userIds.yml
@@ -2,15 +2,11 @@ post:
tags:
- Clusters
operationId: assignUserId
- summary: Assign or Move userID.
+ summary: Assign or move a user ID.
description: >
- Assign or Move a userID to a cluster.
+ Assign or move a user ID to a cluster.
- The time it takes to migrate (move) a user is proportional to the amount of data linked to the userID.
-
- Upon success, the response is 200 OK.
-
- A successful response indicates that the operation has been taken into account, and the userID is directly usable.
+ The time it takes to move a user is proportional to the amount of data linked to the user ID.
parameters:
- $ref: '../../common/parameters.yml#/UserIDInHeader'
requestBody:
@@ -45,11 +41,10 @@ get:
operationId: listUserIds
summary: List userIDs.
description: >
- List the userIDs assigned to a multi-clusters appID.
-
- The data returned will usually be a few seconds behind real time, because userID usage may take up to a few seconds to propagate to the different clusters.
+ List the userIDs assigned to a multi-cluster application.
- Upon success, the response is 200 OK and contains the following userIDs data.
+ Since it can take up to a few seconds to get the data from the different clusters,
+ the response isn't real-time.
parameters:
- $ref: '../../../common/parameters.yml#/Page'
- $ref: '../../../common/parameters.yml#/HitsPerPage'
@@ -61,11 +56,11 @@ get:
schema:
title: listUserIdsResponse
type: object
- description: UserIDs data.
+ description: User ID data.
properties:
userIDs:
type: array
- description: List of userIDs.
+ description: User IDs.
items:
$ref: '../../common/schemas/UserId.yml#/userId'
required:
diff --git a/specs/search/paths/objects/batch.yml b/specs/search/paths/objects/batch.yml
index e131d7e8d4..22d235c694 100644
--- a/specs/search/paths/objects/batch.yml
+++ b/specs/search/paths/objects/batch.yml
@@ -2,8 +2,12 @@ post:
tags:
- Records
operationId: batch
- summary: Batch operations to one index.
- description: Perform multiple write operations targeting one index, in a single API call.
+ summary: Batch write operations on one index.
+ description: >
+ To reduce the time spent on network round trips, you can perform several write actions in a single API call.
+ Actions are applied in the order they are specified.
+
+ The supported `action`s are equivalent to the individual operations of the same name.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
@@ -12,7 +16,7 @@ post:
application/json:
schema:
title: batchWriteParams
- description: The `batch` parameters.
+ description: Batch parameters.
type: object
additionalProperties: false
properties:
@@ -27,7 +31,8 @@ post:
$ref: 'common/schemas.yml#/action'
body:
type: object
- description: arguments to the operation (depends on the type of the operation).
+ description: Operation arguments (varies with specified `action`).
+ example: {'name': 'Betty Jane McCamey','company': 'Vita Foods Inc.','email': 'betty@mccamey.com'}
required:
- action
- body
diff --git a/specs/search/paths/objects/clearObjects.yml b/specs/search/paths/objects/clearObjects.yml
index 883dda84f1..5213b0b335 100644
--- a/specs/search/paths/objects/clearObjects.yml
+++ b/specs/search/paths/objects/clearObjects.yml
@@ -2,8 +2,8 @@ post:
tags:
- Records
operationId: clearObjects
- summary: Clear all objects from an index.
- description: Delete an index's content, but leave settings and index-specific API keys untouched.
+ summary: Delete all records from an index.
+ description: Delete the records but leave settings and index-specific API keys untouched.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
responses:
diff --git a/specs/search/paths/objects/common/schemas.yml b/specs/search/paths/objects/common/schemas.yml
index f69599bf0a..79552aa74a 100644
--- a/specs/search/paths/objects/common/schemas.yml
+++ b/specs/search/paths/objects/common/schemas.yml
@@ -8,7 +8,7 @@ action:
- deleteObject
- delete
- clear
- description: type of operation.
+ description: Type of batch operation.
builtInOperationType:
type: string
@@ -20,7 +20,7 @@ builtInOperationType:
- AddUnique
- IncrementFrom
- IncrementSet
- description: The operation to apply on the attribute.
+ description: Operation to apply to the attribute.
attribute:
type: string
@@ -35,7 +35,7 @@ builtInOperation:
$ref: '#/builtInOperationType'
value:
type: string
- description: the right-hand side argument to the operation, for example, increment or decrement step, value to add or remove.
+ description: Value that corresponds to the operation, for example an `Increment` or `Decrement` step, `Add` or `Remove` value.
required:
- _operation
- value
diff --git a/specs/search/paths/objects/deleteBy.yml b/specs/search/paths/objects/deleteBy.yml
index c9a8ad19ca..e925c976f0 100644
--- a/specs/search/paths/objects/deleteBy.yml
+++ b/specs/search/paths/objects/deleteBy.yml
@@ -2,13 +2,11 @@ post:
tags:
- Records
operationId: deleteBy
- summary: Delete all records matching the query.
+ summary: Delete all records matching a query.
description: >
- Remove all objects matching a filter (including geo filters).
+ This operation doesn't support all the query options, only its filters (numeric, facet, or tag) and geo queries.
- This method enables you to delete one or more objects based on filters (numeric, facet, tag or geo queries).
-
- It doesn't accept empty filters or a query.
+ It doesn't accept empty filters or queries.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
diff --git a/specs/search/paths/objects/getObjects.yml b/specs/search/paths/objects/getObjects.yml
index c1c4f7f9ea..fcdd8ca8d6 100644
--- a/specs/search/paths/objects/getObjects.yml
+++ b/specs/search/paths/objects/getObjects.yml
@@ -4,23 +4,25 @@ post:
operationId: getObjects
x-use-read-transporter: true
x-cacheable: true
- summary: Retrieve one or more objects.
- description: Retrieve one or more objects, potentially from different indices, in a single API call.
+ summary: Get multiple records.
+ description: >
+ Retrieve one or more records, potentially from different indices, in a single API operation.
+ Results will be received in the same order as the requests.
requestBody:
required: true
- description: The Algolia object.
+ description: Request object.
content:
application/json:
schema:
title: getObjectsParams
- description: The `getObjects` parameters.
+ description: Request parameters.
type: object
additionalProperties: false
properties:
requests:
type: array
items:
- description: getObjects operation on an index.
+ description: Record retrieval operation.
title: getObjectsRequest
type: object
additionalProperties: false
@@ -32,13 +34,16 @@ post:
type: array
items:
type: string
- description: List of attributes to retrieve. By default, all retrievable attributes are returned.
+ description: Attributes to retrieve. If not specified, all retrievable attributes are returned.
+ example: ['author','title','content']
objectID:
type: string
- description: ID of the object within that index.
+ description: Record's objectID.
+ example: '8b9b7619230b1950f653b962fb0dfd6b'
indexName:
type: string
- description: name of the index containing the object.
+ description: Name of the index containing the required records.
+ example: books
required:
- requests
responses:
@@ -53,7 +58,7 @@ post:
properties:
results:
type: array
- description: List of results fetched.
+ description: Retrieved results.
items:
type: object
description: Fetched object.
diff --git a/specs/search/paths/objects/multipleBatch.yml b/specs/search/paths/objects/multipleBatch.yml
index 58467600df..9bdf3e9270 100644
--- a/specs/search/paths/objects/multipleBatch.yml
+++ b/specs/search/paths/objects/multipleBatch.yml
@@ -2,15 +2,20 @@ post:
tags:
- Records
operationId: multipleBatch
- description: Perform multiple write operations, potentially targeting multiple indices, in a single API call.
- summary: Batch operations to many indices.
+ description: >
+ To reduce the time spent on network round trips, you can perform several write actions in a single request.
+ It's a multi-index version of the [`batch` operation](#tag/Records/operation/batch).
+ Actions are applied in the order they are specified.
+
+ The supported actions are equivalent to the individual operations of the same name.
+ summary: Batch write operations on multiple indices.
requestBody:
required: true
content:
application/json:
schema:
title: batchParams
- description: The `multipleBatch` parameters.
+ description: Batch parameters.
type: object
additionalProperties: false
properties:
@@ -25,10 +30,13 @@ post:
$ref: 'common/schemas.yml#/action'
body:
type: object
- description: arguments to the operation (depends on the type of the operation).
+ description: Operation arguments (varies with specified `action`).
+ example: >
+ {'requests':[{'action':'addObject','indexName':'contacts','body':{'name':'Betty Jane McCamey','company':'Vita Foods Inc.','email':'betty@mccamey.com'}},{'action':'addObject','indexName':'public_contacts','body':{'name':'Gayla Geimer','company': "Ortman McCain Co','email':'gayla@geimer.com'}}]}
indexName:
type: string
description: Index to target for this operation.
+ example: 'index1'
required:
- action
- body
@@ -47,7 +55,7 @@ post:
properties:
taskID:
type: object
- description: List of tasksIDs per index.
+ description: TaskIDs per index.
additionalProperties:
$ref: '../../../common/responses/common.yml#/taskID'
objectIDs:
diff --git a/specs/search/paths/objects/object.yml b/specs/search/paths/objects/object.yml
index 8268ec3043..f91d9f0748 100644
--- a/specs/search/paths/objects/object.yml
+++ b/specs/search/paths/objects/object.yml
@@ -2,14 +2,21 @@ get:
tags:
- Records
operationId: getObject
- summary: Retrieve an object.
- description: Retrieve one object from the index.
+ summary: Get a record.
+ description: To get more than one record, use the [`objects` operation](#tag/Records/operation/getObjects).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ObjectID'
- name: attributesToRetrieve
in: query
- description: List of attributes to retrieve. If not specified, all retrievable attributes are returned.
+ description: >
+ Attributes to include with the records in the response.
+ This is useful to reduce the size of the API response.
+ By default, all retrievable attributes are returned.
+
+ `objectID` is always retrieved, even when not specified.
+
+ [`unretrievableAttributes`](https://www.algolia.com/doc/api-reference/api-parameters/unretrievableAttributes/) won't be retrieved unless the request is authenticated with the admin API key.
schema:
type: array
items:
@@ -38,17 +45,19 @@ put:
tags:
- Records
operationId: addOrUpdateObject
- summary: Add or replace an object.
+ summary: Add or update a record (using objectID).
description: |
- Add or replace an object with a given object ID.
- If the object does not exist, it will be created.
- If it already exists, it will be replaced.
+ If you use an existing `objectID`, the existing record will be replaced with the new one.
+
+ To update only some attributes of an existing record, use the [`partial` operation](#tag/Records/operation/partialUpdateObject) instead.
+
+ To add multiple records to your index in a single API request, use the [`batch` operation](#tag/Records/operation/batch).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ObjectID'
requestBody:
required: true
- description: The Algolia object.
+ description: Algolia record.
content:
application/json:
schema:
@@ -69,8 +78,8 @@ delete:
tags:
- Records
operationId: deleteObject
- summary: Delete an object.
- description: Delete an existing object.
+ summary: Delete a record.
+ description: To delete a set of records matching a query, use the [`deleteByQuery` operation](#tag/Records/operation/deleteBy) instead.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ObjectID'
diff --git a/specs/search/paths/objects/objects.yml b/specs/search/paths/objects/objects.yml
index 14c35ab117..8dcf46daf4 100644
--- a/specs/search/paths/objects/objects.yml
+++ b/specs/search/paths/objects/objects.yml
@@ -2,8 +2,15 @@ post:
tags:
- Records
operationId: saveObject
- description: Add an object to the index, automatically assigning it an object ID.
- summary: Add an object to the index.
+ description: >
+ Add a record (object) to an index or replace it.
+
+ If the record doesn't contain an `objectID`, Algolia automatically adds it.
+
+ If you use an existing `objectID`, the existing record is replaced with the new one.
+
+ To add multiple records to your index in a single API request, use the [`batch` operation](#tag/Records/operation/batch).
+ summary: Add or update a record.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
@@ -25,6 +32,8 @@ post:
properties:
createdAt:
type: string
+ description: Date of creation (ISO-8601 format).
+ example: '2023-06-29T15:15:40.747Z'
taskID:
$ref: '../../../common/responses/common.yml#/taskID'
objectID:
diff --git a/specs/search/paths/objects/partialUpdate.yml b/specs/search/paths/objects/partialUpdate.yml
index daebbd6a15..9cae5ae264 100644
--- a/specs/search/paths/objects/partialUpdate.yml
+++ b/specs/search/paths/objects/partialUpdate.yml
@@ -2,33 +2,30 @@ post:
tags:
- Records
operationId: partialUpdateObject
- summary: Partially update an object.
+ summary: Update record attributes.
x-codegen-request-body-name: attributesToUpdate
description: >
- Update one or more attributes of an existing object.
+ Add new attributes or update current ones in an existing record.
- This method lets you update only a part of an existing object, either by adding new attributes or updating existing ones.
-
- You can partially update several objects in a single method call.
-
- If the index targeted by this operation doesn't exist yet, it's automatically created.
+ You can use any first-level attribute but not nested attributes. If you specify a [nested attribute](https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/how-to/creating-and-using-nested-attributes/), the engine treats it as a replacement for its first-level ancestor.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ObjectID'
- name: createIfNotExists
- description: Creates the record if it does not exist yet.
+ description: >
+ Indicates whether to create a new record if it doesn't exist yet.
in: query
schema:
type: boolean
default: true
requestBody:
required: true
- description: Map of attribute(s) to update.
+ description: Object with attributes to update.
content:
application/json:
schema:
type: object
- description: Attribute(s) to update.
+ description: Attributes to update.
additionalProperties:
$ref: 'common/schemas.yml#/attributeToUpdate'
responses:
diff --git a/specs/search/paths/rules/clearRules.yml b/specs/search/paths/rules/clearRules.yml
index fc7a88df3f..9f50068f9b 100644
--- a/specs/search/paths/rules/clearRules.yml
+++ b/specs/search/paths/rules/clearRules.yml
@@ -2,8 +2,8 @@ post:
tags:
- Rules
operationId: clearRules
- summary: Clear Rules.
- description: Delete all Rules in the index.
+ summary: Delete all rules.
+ description: Delete all rules in the index.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ForwardToReplicas'
diff --git a/specs/search/paths/rules/common/parameters.yml b/specs/search/paths/rules/common/parameters.yml
index df87cba731..388341c18f 100644
--- a/specs/search/paths/rules/common/parameters.yml
+++ b/specs/search/paths/rules/common/parameters.yml
@@ -4,4 +4,18 @@ ClearExistingRules:
required: false
schema:
type: boolean
- description: When true, existing Rules are cleared before adding this batch. When false, existing Rules are kept.
+ description: Indicates whether existing rules should be deleted before adding this batch.
+
+ObjectID:
+ in: path
+ name: objectID
+ description: Unique identifier of a rule object.
+ example: 'a-rule-id'
+ required: true
+ schema:
+ type: string
+
+query:
+ type: string
+ description: Rule object query.
+ default: ''
\ No newline at end of file
diff --git a/specs/search/paths/rules/common/schemas.yml b/specs/search/paths/rules/common/schemas.yml
index 2114812e91..9ef27cf8b4 100644
--- a/specs/search/paths/rules/common/schemas.yml
+++ b/specs/search/paths/rules/common/schemas.yml
@@ -4,24 +4,28 @@ rule:
additionalProperties: false
properties:
objectID:
- $ref: '../../../../common/parameters.yml#/objectID'
+ type: string
+ description: Unique identifier for a rule object.
+ example: 'hide-12345'
conditions:
type: array
- description: A list of conditions that should apply to activate a Rule. You can use up to 25 conditions per Rule.
+ description: >
+ [Conditions](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/#conditions) required to activate a rule. You can use up to 25 conditions per rule.
items:
$ref: '#/condition'
consequence:
$ref: '#/consequence'
description:
type: string
- description: This field is intended for Rule management purposes, in particular to ease searching for Rules and presenting them to human readers. It's not interpreted by the API.
+ description: Description of the rule's purpose. This can be helpful for display in the Algolia dashboard.
+ example: 'Display a promotional banner'
enabled:
type: boolean
default: true
- description: Whether the Rule is enabled. Disabled Rules remain in the index, but aren't applied at query time.
+ description: Indicates whether to enable the rule. If it isn't enabled, it isn't applied at query time.
validity:
type: array
- description: By default, Rules are permanently valid. When validity periods are specified, the Rule applies only during those periods; it's ignored the rest of the time. The list must not be empty.
+ description: If you specify a validity period, the rule _only_ applies only during that period. If specified, the array must not be empty.
items:
$ref: '#/timeRange'
required:
@@ -34,6 +38,7 @@ condition:
pattern:
type: string
description: Query pattern syntax.
+ example: '{facet:brand}'
anchoring:
$ref: '#/anchoring'
alternatives:
@@ -43,35 +48,37 @@ condition:
context:
type: string
description: 'Rule context format: [A-Za-z0-9_-]+).'
+ example: 'trackedFilters'
anchoring:
type: string
- description: Whether the pattern parameter must match the beginning or the end of the query string, or both, or none.
+ description: Whether the pattern parameter matches the beginning (`startsWith`) or end (`endsWith`) of the query string, is an exact match (`is`), or a partial match (`contains`).
enum: [is, startsWith, endsWith, contains]
consequence:
type: object
- description: Consequence of the Rule.
+ description: >
+ [Consequences](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/#consequences) of a rule.
additionalProperties: false
properties:
params:
$ref: '#/consequenceParams'
promote:
type: array
- description: Objects to promote as hits.
+ description: Records to promote.
items:
$ref: '#/promote'
filterPromotes:
type: boolean
default: false
- description: Only use in combination with the promote consequence. When true, promoted results will be restricted to match the filters of the current search. When false, the promoted results will show up regardless of the filters.
+ description: Only use in combination with the `promote` consequence. When `true`, promoted results will be restricted to match the filters of the current search. When `false`, the promoted results will show up regardless of the filters.
hide:
type: array
- description: Objects to hide from hits. Each object must contain an objectID field. By default, you can hide up to 50 items per rule.
+ description: Records to hide. By default, you can hide up to 50 records per rule.
items:
title: consequenceHide
type: object
- description: Unique identifier of the object to hide.
+ description: Unique identifier of the record to hide.
additionalProperties: false
properties:
objectID:
@@ -81,6 +88,7 @@ consequence:
userData:
type: object
description: Custom JSON object that will be appended to the userData array in the response. This object isn't interpreted by the API. It's limited to 1kB of minified JSON.
+ example: {'settingID': 'f2a7b51e3503acc6a39b3784ffb84300','pluginVersion': '1.6.0'}
consequenceParams:
allOf:
@@ -94,13 +102,14 @@ promote:
- $ref: '#/promoteObjectID'
promoteObjectID:
- description: Single objectID to promote as hits.
+ description: Record to promote.
type: object
additionalProperties: false
properties:
objectID:
type: string
- description: Unique identifier of the object to promote.
+ example: '2b642cf64c587f50388eb1b8d047bf56'
+ description: Unique identifier of the record to promote.
position:
$ref: '#/promotePosition'
required:
@@ -108,13 +117,14 @@ promoteObjectID:
- objectID
promoteObjectIDs:
- description: Multiple objectIDs to promote as hits.
+ description: Records to promote.
type: object
additionalProperties: false
properties:
objectIDs:
type: array
- description: Array of unique identifiers of the objects to promote.
+ description: Unique identifiers of the records to promote.
+ example: ['3f31c087763a2ceec359b318fc3edef3','63c3c871e31a152d67df7720192fd752']
items:
type: string
position:
@@ -125,11 +135,12 @@ promoteObjectIDs:
promotePosition:
type: integer
- description: The position to promote the objects to (zero-based). If you pass objectIDs, the objects are placed at this position as a group. For example, if you pass four objectIDs to position 0, the objects take the first four positions.
+ description: The position to promote the records to. If you pass objectIDs, the records are placed at this position as a group. For example, if you pronmote four objectIDs to position 0, the records take the first four positions.
+ example: 0
params:
type: object
- description: Additional search parameters. Any valid search parameter is allowed.
+ description: Additional search parameters.
additionalProperties: false
properties:
query:
@@ -191,7 +202,7 @@ automaticFacetFilters:
type: string
automaticOptionalFacetFilters:
- description: Same syntax as automaticFacetFilters, but the engine treats the filters as optional.
+ description: Same syntax as `automaticFacetFilters`, but the engine treats the filters as optional.
$ref: '#/automaticFacetFilters'
automaticFacetFilter:
diff --git a/specs/search/paths/rules/rule.yml b/specs/search/paths/rules/rule.yml
index 2ef9e5e867..25b32dfab4 100644
--- a/specs/search/paths/rules/rule.yml
+++ b/specs/search/paths/rules/rule.yml
@@ -3,10 +3,10 @@ get:
- Rules
operationId: getRule
summary: Get a rule.
- description: Retrieve the Rule with the specified objectID.
+ description: Get a rule by its `objectID`. To find the `objectID` for rules, use the [`search` operation](#tag/Rules/operation/searchRules).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- - $ref: '../../../common/parameters.yml#/ObjectID'
+ - $ref: 'common/parameters.yml#/ObjectID'
responses:
'200':
description: OK
@@ -27,11 +27,11 @@ put:
tags:
- Rules
operationId: saveRule
- summary: Save/Update a rule.
- description: Create or update the Rule with the specified objectID.
+ summary: Create or update a rule.
+ description: To create or update more than one rule, use the [`batch` operation](#tag/Rules/operation/saveRules).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- - $ref: '../../../common/parameters.yml#/ObjectID'
+ - $ref: 'common/parameters.yml#/ObjectID'
- $ref: '../../../common/parameters.yml#/ForwardToReplicas'
requestBody:
required: true
@@ -60,10 +60,10 @@ delete:
- Rules
operationId: deleteRule
summary: Delete a rule.
- description: Delete the Rule with the specified objectID.
+ description: Delete a rule by its `objectID`. To find the `objectID` for rules, use the [`search` operation](#tag/Rules/operation/searchRules).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- - $ref: '../../../common/parameters.yml#/ObjectID'
+ - $ref: 'common/parameters.yml#/ObjectID'
- $ref: '../../../common/parameters.yml#/ForwardToReplicas'
responses:
'200':
diff --git a/specs/search/paths/rules/saveRules.yml b/specs/search/paths/rules/saveRules.yml
index c120798a41..0d08a8a4cb 100644
--- a/specs/search/paths/rules/saveRules.yml
+++ b/specs/search/paths/rules/saveRules.yml
@@ -3,7 +3,7 @@ post:
- Rules
operationId: saveRules
summary: Save a batch of rules.
- description: Create/update multiple rules objects at once.
+ description: Create or update multiple rules.
x-codegen-request-body-name: rules
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
diff --git a/specs/search/paths/rules/searchRules.yml b/specs/search/paths/rules/searchRules.yml
index e8ab44fab5..23e95b2169 100644
--- a/specs/search/paths/rules/searchRules.yml
+++ b/specs/search/paths/rules/searchRules.yml
@@ -5,7 +5,7 @@ post:
x-use-read-transporter: true
x-cacheable: true
summary: Search for rules.
- description: Search for rules matching various criteria.
+ description: Search for rules in your index. You can control the search with parameters. To list all rules, send an empty request body.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
@@ -14,16 +14,17 @@ post:
schema:
type: object
title: searchRulesParams
- description: Parameters for the search.
+ description: Rules search parameters.
additionalProperties: false
properties:
query:
- $ref: '../../../common/parameters.yml#/query'
+ $ref: 'common/parameters.yml#/query'
anchoring:
$ref: 'common/schemas.yml#/anchoring'
context:
type: string
- description: Restricts matches to contextual rules with a specific context (exact match).
+ description: Restricts responses to the specified [contextual rule](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/how-to/customize-search-results-by-platform/#creating-contextual-rules).
+ example: 'mobile'
page:
$ref: '../../../common/parameters.yml#/page'
hitsPerPage:
@@ -32,13 +33,15 @@ post:
type: boolean
nullable: true
default: null
- description: When specified, restricts matches to rules with a specific enabled status. When absent (default), all rules are retrieved, regardless of their enabled status.
+ description: Restricts responses to enabled rules. When not specified (default), _all_ rules are retrieved.
requestOptions:
type: array
- description: A mapping of requestOptions to send along with the request.
+ description: Request options to send with the API call.
+ example: >
+ {timeouts:{read:20}}
items:
type: object
- description: Request Option.
+ description: Request option.
responses:
'200':
description: OK
diff --git a/specs/search/paths/search/browse.yml b/specs/search/paths/search/browse.yml
index e5de921406..973380c241 100644
--- a/specs/search/paths/search/browse.yml
+++ b/specs/search/paths/search/browse.yml
@@ -2,13 +2,14 @@ post:
tags:
- Search
operationId: browse
- summary: Retrieve all index content.
+ summary: Get all records from an index.
description: >
- This method allows you to retrieve all index content. It can retrieve up to 1,000 records per call and supports full text search and filters.
+ Retrieve up to 1,000 records per call.
- For performance reasons, some features are not supported, including `distinct`, sorting by `typos`, `words` or `geo distance`.
-
- When there is more content to be browsed, the response contains a cursor field. This cursor has to be passed to the subsequent call to browse in order to get the next page of results. When the end of the index has been reached, the cursor field is absent from the response.
+ Supports full-text search and filters. For better performance, it doesn't support:
+
+ - The `distinct` query parameter
+ - Sorting by typos, proximity, words, or geographical distance.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
diff --git a/specs/search/paths/search/search.yml b/specs/search/paths/search/search.yml
index e802954e4d..8809d383d4 100644
--- a/specs/search/paths/search/search.yml
+++ b/specs/search/paths/search/search.yml
@@ -6,10 +6,10 @@ post:
x-cacheable: true
x-legacy-signature: true
summary: Search multiple indices.
- description: Perform a search operation targeting one or many indices.
+ description: Send multiple search queries to one or more indices.
requestBody:
required: true
- description: The `search` requests and strategy.
+ description: Query requests and strategies. Results will be received in the same order as the queries.
content:
application/json:
schema:
diff --git a/specs/search/paths/search/searchForFacetValues.yml b/specs/search/paths/search/searchForFacetValues.yml
index a3cf7cd664..6a7a184bad 100644
--- a/specs/search/paths/search/searchForFacetValues.yml
+++ b/specs/search/paths/search/searchForFacetValues.yml
@@ -4,12 +4,15 @@ post:
operationId: searchForFacetValues
x-use-read-transporter: true
x-cacheable: true
- summary: Search for values of a given facet.
- description: Search for values of a given facet, optionally restricting the returned values to those contained in objects matching other search criteria.
+ summary: Search for facet values.
+ description: >
+ [Search for a facet's values](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#search-for-facet-values), optionally restricting the returned values to those contained in records matching other search criteria.
+
+ > **Note**: Pagination isn't supported (`page` and `hitsPerPage` are ignored). By default, the engine returns a maximum of 10 values but you can adjust this with `maxFacetHits`.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- name: facetName
- description: The facet name.
+ description: Facet name.
in: path
required: true
schema:
@@ -52,12 +55,13 @@ post:
- count
properties:
value:
- description: Raw value of the facet.
+ description: Facet value.
+ example: 'Mobile phone'
type: string
highlighted:
$ref: '../../common/schemas/Hit.yml#/highlightedValue'
count:
- description: How many objects contain this facet value. This takes into account the extra search parameters specified in the query. Like for a regular search query, the counts may not be exhaustive.
+ description: Number of records containing this facet value. This takes into account the extra search parameters specified in the query. Like for a regular search query, the [counts may not be exhaustive](https://support.algolia.com/hc/en-us/articles/4406975248145-Why-are-my-facet-and-hit-counts-not-accurate-).
type: integer
'400':
$ref: '../../../common/responses/BadRequest.yml'
diff --git a/specs/search/paths/search/searchSingleIndex.yml b/specs/search/paths/search/searchSingleIndex.yml
index ede7152d24..33a0ecb77d 100644
--- a/specs/search/paths/search/searchSingleIndex.yml
+++ b/specs/search/paths/search/searchSingleIndex.yml
@@ -4,8 +4,8 @@ post:
operationId: searchSingleIndex
x-use-read-transporter: true
x-cacheable: true
- summary: Search in a single index.
- description: Perform a search operation targeting one specific index.
+ summary: Search an index.
+ description: Return records that match the query.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
diff --git a/specs/search/paths/settings/settings.yml b/specs/search/paths/settings/settings.yml
index 129b900be2..b64525ebb1 100644
--- a/specs/search/paths/settings/settings.yml
+++ b/specs/search/paths/settings/settings.yml
@@ -2,8 +2,8 @@ get:
tags:
- Indices
operationId: getSettings
- description: Retrieve settings of an index.
- summary: Retrieve settings of an index.
+ description: Return an object containing an index's [configuration settings](https://www.algolia.com/doc/api-reference/settings-api-parameters/).
+ summary: Get index settings.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
responses:
@@ -26,8 +26,8 @@ put:
tags:
- Indices
operationId: setSettings
- description: Update settings of an index. Only specified settings are overridden; unspecified settings are left unchanged. Specifying null for a setting resets it to its default value.
- summary: Update settings of an index.
+ description: Update the specified [index settings](https://www.algolia.com/doc/api-reference/settings-api-parameters/). Specifying null for a setting resets it to its default value.
+ summary: Update index settings.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ForwardToReplicas'
diff --git a/specs/search/paths/synonyms/clearAllSynonyms.yml b/specs/search/paths/synonyms/clearAllSynonyms.yml
index ad5346dca6..6fcb793d95 100644
--- a/specs/search/paths/synonyms/clearAllSynonyms.yml
+++ b/specs/search/paths/synonyms/clearAllSynonyms.yml
@@ -2,8 +2,8 @@ post:
tags:
- Synonyms
operationId: clearAllSynonyms
- summary: Clear all synonyms.
- description: Remove all synonyms from an index.
+ summary: Delete all synonyms.
+ description: Delete all synonyms in the index.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ForwardToReplicas'
diff --git a/specs/search/paths/synonyms/common/parameters.yml b/specs/search/paths/synonyms/common/parameters.yml
index 2cb06504ba..9b0c680ae4 100644
--- a/specs/search/paths/synonyms/common/parameters.yml
+++ b/specs/search/paths/synonyms/common/parameters.yml
@@ -3,12 +3,12 @@ ReplaceExistingSynonyms:
name: replaceExistingSynonyms
schema:
type: boolean
- description: Replace all synonyms of the index with the ones sent with this request.
+ description: Indicates whether to replace all synonyms in the index with the ones sent with this request.
Query:
in: query
name: query
- description: Search for specific synonyms matching this string.
+ description: Search for synonyms that match this string.
schema:
type: string
default: ''
@@ -16,16 +16,26 @@ Query:
Type:
in: query
name: type
- description: Only search for specific types of synonyms.
+ description: Search for specific [types of synonyms](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/#the-different-types-of-synonyms).
schema:
$ref: '#/SynonymType'
SynonymType:
type: string
- description: Type of the synonym object.
+ description: Synonym type.
+ example: onewaysynonym
enum:
- synonym
- onewaysynonym
- altcorrection1
- altcorrection2
- placeholder
+
+ObjectID:
+ name: objectID
+ in: path
+ description: Unique identifier of a synonym object.
+ required: true
+ schema:
+ type: string
+ example: 'synonymID'
diff --git a/specs/search/paths/synonyms/common/schemas.yml b/specs/search/paths/synonyms/common/schemas.yml
index f82714d8c0..32b9668f4e 100644
--- a/specs/search/paths/synonyms/common/schemas.yml
+++ b/specs/search/paths/synonyms/common/schemas.yml
@@ -1,6 +1,6 @@
synonymHits:
type: array
- description: Array of synonym objects.
+ description: Synonym objects.
items:
$ref: '#/synonymHit'
@@ -11,7 +11,8 @@ synonymHit:
properties:
objectID:
type: string
- description: Unique identifier of the synonym object to be created or updated.
+ description: Unique identifier of a synonym object.
+ example: 'synonymID'
type:
$ref: './parameters.yml#/SynonymType'
@@ -19,26 +20,33 @@ synonymHit:
type: array
items:
type: string
- description: Words or phrases to be considered equivalent.
+ description: Words or phrases considered equivalent.
+ example: ['vehicle','auto']
input:
type: string
- description: Word or phrase to appear in query strings (for onewaysynonym).
+ description: Word or phrase to appear in query strings (for [`onewaysynonym`s](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/in-depth/one-way-synonyms/)).
+ example: 'car'
word:
type: string
- description: Word or phrase to appear in query strings (for altcorrection1 and altcorrection2).
+ description: Word or phrase to appear in query strings (for [`altcorrection1` and `altcorrection2`](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/in-depth/synonyms-alternative-corrections/)).
+ example: 'car'
corrections:
type: array
items:
type: string
description: Words to be matched in records.
+ example: ['vehicle','auto']
placeholder:
type: string
- description: Token to be put inside records.
+ description: >
+ [Placeholder token](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/in-depth/synonyms-placeholders/) to be put inside records.
+ example: ''
replacements:
type: array
items:
type: string
- description: List of query words that will match the token.
+ description: Query words that will match the [placeholder token](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/in-depth/synonyms-placeholders/).
+ example: ['street','st']
required:
- objectID
- type
diff --git a/specs/search/paths/synonyms/saveSynonyms.yml b/specs/search/paths/synonyms/saveSynonyms.yml
index cee4c98c9b..650ed0a00d 100644
--- a/specs/search/paths/synonyms/saveSynonyms.yml
+++ b/specs/search/paths/synonyms/saveSynonyms.yml
@@ -3,7 +3,7 @@ post:
- Synonyms
operationId: saveSynonyms
summary: Save a batch of synonyms.
- description: Create/update multiple synonym objects at once, potentially replacing the entire list of synonyms if replaceExistingSynonyms is true.
+ description: Create or update multiple synonyms.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ForwardToReplicas'
diff --git a/specs/search/paths/synonyms/searchSynonyms.yml b/specs/search/paths/synonyms/searchSynonyms.yml
index 6e3ea3a730..f544e63cd5 100644
--- a/specs/search/paths/synonyms/searchSynonyms.yml
+++ b/specs/search/paths/synonyms/searchSynonyms.yml
@@ -4,15 +4,15 @@ post:
operationId: searchSynonyms
x-use-read-transporter: true
x-cacheable: true
- summary: Search synonyms.
- description: Search or browse all synonyms, optionally filtering them by type.
+ summary: Search for synonyms.
+ description: Search for synonyms in your index. You can control and filter the search with parameters. To get all synonyms, send an empty request body.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: './common/parameters.yml#/Type'
- $ref: '../../../common/parameters.yml#/PageDefault0'
- $ref: '../../../common/parameters.yml#/HitsPerPage'
requestBody:
- description: The body of the the `searchSynonyms` method.
+ description: Body of the `searchSynonyms` operation.
content:
application/json:
schema:
diff --git a/specs/search/paths/synonyms/synonym.yml b/specs/search/paths/synonyms/synonym.yml
index 975061477e..31c3831ed7 100644
--- a/specs/search/paths/synonyms/synonym.yml
+++ b/specs/search/paths/synonyms/synonym.yml
@@ -2,11 +2,11 @@ get:
tags:
- Synonyms
operationId: getSynonym
- summary: Get synonym.
- description: Fetch a synonym object identified by its objectID.
+ summary: Get a synonym object.
+ description: Get a syonym by its `objectID`. To find the object IDs for your synonyms, use the [`search` operation](#tag/Synonyms/operation/searchSynonyms).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- - $ref: '../../../common/parameters.yml#/ObjectID'
+ - $ref: 'common/parameters.yml#/ObjectID'
responses:
'200':
description: OK
@@ -27,11 +27,18 @@ put:
tags:
- Synonyms
operationId: saveSynonym
- summary: Save synonym.
- description: Create a new synonym object or update the existing synonym object with the given object ID.
+ summary: Save a synonym.
+ description: >
+ Add a [synonym](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/#the-different-types-of-synonyms) to an index or replace it.
+
+ If the synonym `objectID` doesn't exist, Algolia adds a new one.
+
+ If you use an existing synonym `objectID`, the existing synonym is replaced with the new one.
+
+ To add multiple synonyms in a single API request, use the [`batch` operation](#tag/Synonyms/operation/saveSynonyms).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- - $ref: '../../../common/parameters.yml#/ObjectID'
+ - $ref: 'common/parameters.yml#/ObjectID'
- $ref: '../../../common/parameters.yml#/ForwardToReplicas'
requestBody:
required: true
@@ -72,11 +79,11 @@ delete:
tags:
- Synonyms
operationId: deleteSynonym
- summary: Delete synonym.
- description: Delete a single synonyms set, identified by the given objectID.
+ summary: Delete a synonym.
+ description: Delete a synonym by its `objectID`. To find the object IDs of your synonyms, use the [`search` operation](#tag/Synonyms/operation/searchSynonyms).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- - $ref: '../../../common/parameters.yml#/ObjectID'
+ - $ref: 'common/parameters.yml#/ObjectID'
- $ref: '../../../common/parameters.yml#/ForwardToReplicas'
responses:
'200':
diff --git a/specs/search/paths/vault/appendSource.yml b/specs/search/paths/vault/appendSource.yml
index 4b322da799..c6ac4a3894 100644
--- a/specs/search/paths/vault/appendSource.yml
+++ b/specs/search/paths/vault/appendSource.yml
@@ -2,11 +2,11 @@ post:
tags:
- Vaults
operationId: appendSource
- description: Add a single source to the list of allowed sources.
- summary: Add a single source.
+ description: Add a source to the list of allowed sources.
+ summary: Add a source.
requestBody:
required: true
- description: The source to add.
+ description: Source to add.
content:
application/json:
schema:
diff --git a/specs/search/paths/vault/common/schemas.yml b/specs/search/paths/vault/common/schemas.yml
index b82c37a5f9..dcbdd426fc 100644
--- a/specs/search/paths/vault/common/schemas.yml
+++ b/specs/search/paths/vault/common/schemas.yml
@@ -1,18 +1,19 @@
sources:
- description: A list of sources.
+ description: Sources.
type: array
items:
$ref: '#/source'
source:
- description: The source.
+ description: Source.
required:
- source
properties:
source:
- description: The IP range of the source.
+ description: IP address range of the source.
type: string
example: 10.0.0.1/32
description:
- description: The description of the source.
+ description: Source description.
type: string
+ example: 'Server subnet'
diff --git a/specs/search/paths/vault/deleteSource.yml b/specs/search/paths/vault/deleteSource.yml
index 34ec0283d6..4039de36da 100644
--- a/specs/search/paths/vault/deleteSource.yml
+++ b/specs/search/paths/vault/deleteSource.yml
@@ -2,13 +2,13 @@ delete:
tags:
- Vaults
operationId: deleteSource
- description: Remove a single source from the list of allowed sources.
- summary: Remove a single source.
+ description: Remove a source from the list of allowed sources.
+ summary: Remove a source.
parameters:
- name: source
in: path
required: true
- description: The IP range of the source.
+ description: IP address range of the source.
schema:
type: string
example: 10.0.0.1/32
diff --git a/specs/search/paths/vault/vaultSources.yml b/specs/search/paths/vault/vaultSources.yml
index 29f7277869..aa8af836ce 100644
--- a/specs/search/paths/vault/vaultSources.yml
+++ b/specs/search/paths/vault/vaultSources.yml
@@ -2,8 +2,8 @@ get:
tags:
- Vaults
operationId: getSources
- description: List all allowed sources.
- summary: List all allowed sources.
+ description: Get all allowed sources (IP addresses).
+ summary: Get all allowed IP addresses.
responses:
'200':
description: OK
@@ -25,10 +25,10 @@ put:
- Vaults
operationId: replaceSources
description: Replace all allowed sources.
- summary: Replace all allowed sources.
+ summary: Replace all sources.
requestBody:
required: true
- description: The sources to allow.
+ description: Allowed sources.
content:
application/json:
schema:
diff --git a/specs/search/spec.yml b/specs/search/spec.yml
index 3f3c4f8cfc..3ce2d3536a 100644
--- a/specs/search/spec.yml
+++ b/specs/search/spec.yml
@@ -1,7 +1,11 @@
openapi: 3.0.2
info:
title: Search API
- description: API powering the Search feature of Algolia.
+ description: |-
+ Use the Search REST API to manage your data (indices and records), implement search, and improve relevance (with Rules, synonyms, and language dictionaries).
+
+ Although Algolia provides a REST API, you should use the official open source API [clients, libraries, and tools](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem/) instead.
+ There's no [SLA](https://www.algolia.com/policies/sla/) if you use the REST API directly.
version: 1.0.0
components:
securitySchemes:
@@ -37,29 +41,44 @@ tags:
- name: Advanced
description: Advanced operations.
- name: Api Keys
- description: Manage your Api Keys.
+ description: Manage your API keys.
- name: Clusters
- description: Clusters operations.
+ description: >
+ Multi-cluster operations.
+
+ Algolia no longer offers [multi-cluster management](https://www.algolia.com/doc/guides/scaling/managing-multiple-clusters-mcm/).
+
+ - If you want to partition your data per user, use facets and secured API keys instead.
+ - If you need more data, consider upgrading to a bigger cluster to suit your needs. Contact [Algolia's support team](https://support.algolia.com/hc/en-us/requests/new) for details.
- name: Dictionaries
- description: Dictionaries operations.
+ description: Dictionary operations allow you to customize linguistic features such as [stop words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/), [plurals](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-plurals-and-other-declensions/), and [segmentation (compounds)](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-segmentation/).
- name: Indices
- description: Manage indices.
+ description: Manage indices, including listing them, checking and updating settings, deleting, copying, and renaming.
- name: Records
- description: Records operations.
+ description: Record operations.
- name: Rules
description: Rules operations.
- name: Search
- description: Perform search operations.
+ description: Search operations.
- name: Synonyms
- description: Synonyms operations.
+ description: Synonym operations.
- name: Vaults
- description: Vault operations.
+ description: >
+ Vault operations.
+
+ Algolia Vault allows you to restrict network-level access to your cluster to a specific set of IP addresses: for non-authorized IP addresses, the cluster is invisible.
+
+ You should authorize the IP addresses of team members who need to access the Alglolia dashboard, as it's also affected by the restricted list you set up.
+
+ To access this feature, [Algolia Vault](https://www.algolia.com/doc/guides/security/algolia-vault/) must be enabled on your server. Contact [Algolia's support team](https://support.algolia.com/hc/en-us/requests/new) for details.
+
+ > **Note**: The maximum number of allowed sources is 1,000.
- name: _model_index_settings
- x-displayName: Index Settings
+ x-displayName: Index settings
description: |
.
x-tagGroups:
- - name: Search and Indexing
+ - name: Search and indexing
tags:
- Indices
- Records
diff --git a/tests/CTS/methods/requests/abtesting/addABTests.json b/tests/CTS/methods/requests/abtesting/addABTests.json
index 715e965c17..2c25924d4b 100644
--- a/tests/CTS/methods/requests/abtesting/addABTests.json
+++ b/tests/CTS/methods/requests/abtesting/addABTests.json
@@ -4,7 +4,7 @@
"parameters": {
"endAt": "2022-12-31T00:00:00.000Z",
"name": "myABTest",
- "variant": [
+ "variants": [
{
"index": "AB_TEST_1",
"trafficPercentage": 30
@@ -21,7 +21,7 @@
"body": {
"endAt": "2022-12-31T00:00:00.000Z",
"name": "myABTest",
- "variant": [
+ "variants": [
{
"index": "AB_TEST_1",
"trafficPercentage": 30
diff --git a/tests/CTS/methods/requests/recommend/deleteRecommendRule.json b/tests/CTS/methods/requests/recommend/deleteRecommendRule.json
new file mode 100644
index 0000000000..3ee0f0912c
--- /dev/null
+++ b/tests/CTS/methods/requests/recommend/deleteRecommendRule.json
@@ -0,0 +1,13 @@
+[
+ {
+ "parameters": {
+ "indexName": "indexName",
+ "model": "related-products",
+ "objectID": "objectID"
+ },
+ "request": {
+ "path": "/1/indexes/indexName/related-products/recommend/rules/objectID",
+ "method": "DELETE"
+ }
+ }
+]
diff --git a/tests/CTS/methods/requests/recommend/getRecommendRule.json b/tests/CTS/methods/requests/recommend/getRecommendRule.json
new file mode 100644
index 0000000000..86fe45318a
--- /dev/null
+++ b/tests/CTS/methods/requests/recommend/getRecommendRule.json
@@ -0,0 +1,13 @@
+[
+ {
+ "parameters": {
+ "indexName": "indexName",
+ "model": "related-products",
+ "objectID": "objectID"
+ },
+ "request": {
+ "path": "/1/indexes/indexName/related-products/recommend/rules/objectID",
+ "method": "GET"
+ }
+ }
+]
diff --git a/tests/CTS/methods/requests/recommend/getRecommendStatus.json b/tests/CTS/methods/requests/recommend/getRecommendStatus.json
new file mode 100644
index 0000000000..cb992260a6
--- /dev/null
+++ b/tests/CTS/methods/requests/recommend/getRecommendStatus.json
@@ -0,0 +1,13 @@
+[
+ {
+ "parameters": {
+ "indexName": "indexName",
+ "model": "related-products",
+ "taskID": 12345
+ },
+ "request": {
+ "path": "/1/indexes/indexName/related-products/task/12345",
+ "method": "GET"
+ }
+ }
+]
diff --git a/tests/CTS/methods/requests/recommend/searchRecommendRules.json b/tests/CTS/methods/requests/recommend/searchRecommendRules.json
new file mode 100644
index 0000000000..06d9ab5d5a
--- /dev/null
+++ b/tests/CTS/methods/requests/recommend/searchRecommendRules.json
@@ -0,0 +1,12 @@
+[
+ {
+ "parameters": {
+ "indexName": "indexName",
+ "model": "related-products"
+ },
+ "request": {
+ "path": "/1/indexes/indexName/related-products/recommend/rules/search",
+ "method": "POST"
+ }
+ }
+]
diff --git a/tests/CTS/methods/requests/search/listIndices.json b/tests/CTS/methods/requests/search/listIndices.json
index 5d56cd0e24..2825d5054a 100644
--- a/tests/CTS/methods/requests/search/listIndices.json
+++ b/tests/CTS/methods/requests/search/listIndices.json
@@ -10,13 +10,15 @@
{
"testName": "listIndices with parameters",
"parameters": {
- "page": 8
+ "page": 8,
+ "hitsPerPage": 3
},
"request": {
"path": "/1/indexes",
"method": "GET",
"queryParameters": {
- "page": "8"
+ "page": "8",
+ "hitsPerPage": "3"
}
}
}