fix(specs): update links and descriptions

kai687 · kai687 · commit b2d7a6244975 · 2025-09-26T14:21:39.000+02:00
diff --git a/specs/analytics/paths/search/getTopFiltersNoResults.yml b/specs/analytics/paths/search/getTopFiltersNoResults.yml
@@ -8,7 +8,7 @@ get:
   description: |
     Retrieves the 1,000 most frequently used filters for a search that didn't return any results.
 
-    To get the most frequent searches without results, use the [Retrieve searches without results](#tag/search/operation/getSearchesNoResults) operation.
+    To get the most frequent searches without results, use the [Retrieve searches without results](https://www.algolia.com/doc/rest-api/analytics/get-searches-no-results) operation.
   parameters:
     - $ref: '../../../common/parameters.yml#/Index'
     - $ref: '../../common/parameters.yml#/Search'
diff --git a/specs/common/responses/common.yml b/specs/common/responses/common.yml
@@ -5,8 +5,9 @@ taskID:
   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](#tag/Indices/operation/getTask) and this `taskID`.
-
+    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](https://www.algolia.com/doc/rest-api/search/get-task) and this task ID.
 objectIDs:
   type: array
   items:
diff --git a/specs/composition/paths/rules/rule.yml b/specs/composition/paths/rules/rule.yml
@@ -8,8 +8,8 @@ get:
   summary: Retrieve a rule
   description: |
     Retrieves a rule by its ID.
-    To find the object ID of rules, use the [`search` operation](#tag/Rules/operation/searchRules).
 
+    To find the object ID of a rule, use the [`search` operation](https://www.algolia.com/doc/rest-api/composition/search-composition-rules).
   parameters:
     - $ref: '../urlParams.yml#/compositionID'
     - $ref: './parameters.yml#/ObjectIDRule'
@@ -35,9 +35,10 @@ put:
   operationId: putCompositionRule
   x-acl:
     - editSettings
-  summary: Upsert a composition rule
+  summary: Add or update a composition rule
   description: |
-    Upsert a Composition Rule for the specified composition ID.
+    If a composition rule with the provided ID already exists,
+    it's replaced. Otherwise, a new one is added.
   parameters:
     - $ref: '../urlParams.yml#/compositionID'
     - $ref: './parameters.yml#/ObjectIDRule'
diff --git a/specs/crawler/common/schemas/getCrawlerResponse.yml b/specs/crawler/common/schemas/getCrawlerResponse.yml
@@ -26,7 +26,7 @@ BaseResponse:
         Whether this crawler is currently blocked.
 
         If `true`, you can unblock it from the [Crawler page](https://dashboard.algolia.com/crawler) in the Algolia dashboard
-        or by [cancelling the blocking task](#tag/tasks/operation/cancelBlockingAction).
+        or by [cancelling the blocking task](https://www.algolia.com/doc/rest-api/crawler/cancel-blocking-action).
     blockingError:
       type: string
       description: Reason why the crawler is blocked.
diff --git a/specs/crawler/paths/crawler.yml b/specs/crawler/paths/crawler.yml
@@ -27,15 +27,19 @@ get:
       $ref: '../common/schemas/responses.yml#/NoRightsOnCrawler'
 patch:
   operationId: patchCrawler
-  summary: Change crawler name
+  summary: Replace crawler configuration
   description: |
-    Change the crawler's name.
+    Replaces the crawler configuration with a new one.
 
-    While you _could_ use this endpoint to replace the crawler configuration,
-    you should [update it](#tag/config/operation/patchConfig) instead since configuration changes made here aren't [versioned](#tag/config/operation/listConfigVersions).
+    If you only want to change the crawler's name, you can use this operation.
+    For other configuration changes, use the "Update configuration" endpoint instead instead,
+    because changes made here aren't versioned.
 
-    If you replace the configuration, you must provide the full configuration,
+    When replacing the configuration, you must provide the full configuration,
     including any settings you want to keep.
+  externalDocs:
+    url: https://www.algolia.com/doc/rest-api/crawler/patch-config
+    description: Update configuration.
   tags:
     - crawlers
   parameters:
diff --git a/specs/crawler/paths/crawlerConfigVersions.yml b/specs/crawler/paths/crawlerConfigVersions.yml
@@ -3,8 +3,7 @@ get:
   summary: List configuration versions
   description: |
     Lists previous versions of the specified crawler's configuration, including who authored the change.
-    Every time you update a crawler's [configuration](#tag/config/operation/patchConfig),
-    a new version is added.
+    Every time you update a crawler's configuration, a new version is added.
   tags:
     - config
   parameters:
diff --git a/specs/crawler/spec.yml b/specs/crawler/spec.yml
@@ -78,7 +78,7 @@ tags:
   - name: crawlers
     x-displayName: Manage
     description: |
-      A crawler is an object with a name and a [configuration](#tag/config).
+      A crawler is an object with a name and a configuration.
       Use these endpoints to create, rename, and delete crawlers.
   - name: domains
     x-displayName: Domains
diff --git a/specs/monitoring/spec.yml b/specs/monitoring/spec.yml
@@ -14,7 +14,7 @@ info:
 
     ## Availability and authentication
 
-    Access to the [Infrastructure](#tag/infrastructure) endpoints
+    Access to the Infrastructure endpoints
     is available as part of the [Premium or Elevate plans](https://www.algolia.com/pricing).
 
     To authenticate requests to the Infrastructure endpoints, add these headers:
diff --git a/specs/search/paths/objects/deleteBy.yml b/specs/search/paths/objects/deleteBy.yml
@@ -11,8 +11,8 @@ post:
 
     This operation is resource-intensive.
     You should only use it if you can't get the object IDs of the records you want to delete.
-    It's more efficient to get a list of object IDs with the [`browse` operation](#tag/Search/operation/browse),
-    and then delete the records using the [`batch` operation](#tag/Records/operation/batch).
+    It's more efficient to get a list of object IDs with the [`browse` operation](https://www.algolia.com/doc/rest-api/search/browse),
+    and then delete the records using the [`batch` operation](https://www.algolia.com/doc/rest-api/search/batch).
 
     This operation is subject to [indexing rate limits](https://support.algolia.com/hc/en-us/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
   externalDocs:
diff --git a/specs/search/paths/objects/object.yml b/specs/search/paths/objects/object.yml
@@ -8,7 +8,7 @@ get:
   description: |
     Retrieves one record by its object ID.
 
-    To retrieve more than one record, use the [`objects` operation](#tag/Records/operation/getObjects).
+    To retrieve more than one record, use the [`objects` operation](https://www.algolia.com/doc/rest-api/search/get-objects).
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - $ref: '../../../common/parameters.yml#/ObjectID'
@@ -55,9 +55,9 @@ put:
     If a record with the specified object ID exists, the existing record is replaced.
     Otherwise, a new record is added to the index.
 
-    If you want to use auto-generated object IDs, use the [`saveObject` operation](#tag/Records/operation/saveObject).
-    To update _some_ attributes of an existing record, use the [`partial` operation](#tag/Records/operation/partialUpdateObject) instead.
-    To add, update, or replace multiple records, use the [`batch` operation](#tag/Records/operation/batch).
+    If you want to use auto-generated object IDs, use the [`saveObject` operation](https://www.algolia.com/doc/rest-api/search/save-object).
+    To update _some_ attributes of an existing record, use the [`partial` operation](https://www.algolia.com/doc/rest-api/search/partial-update-object) instead.
+    To add, update, or replace multiple records, use the [`batch` operation](https://www.algolia.com/doc/rest-api/search/batch).
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - $ref: '../../../common/parameters.yml#/ObjectID'
@@ -95,8 +95,8 @@ delete:
   description: |
     Deletes a record by its object ID.
 
-    To delete more than one record, use the [`batch` operation](#tag/Records/operation/batch).
-    To delete records matching a query, use the [`deleteBy` operation](#tag/Records/operation/deleteBy).
+    To delete more than one record, use the [`batch` operation](https://www.algolia.com/doc/rest-api/search/batch).
+    To delete records matching a query, use the [`deleteBy` operation](https://www.algolia.com/doc/rest-api/search/delete-by).
 
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
diff --git a/specs/search/paths/objects/objects.yml b/specs/search/paths/objects/objects.yml
@@ -13,8 +13,8 @@ post:
     - If a record with the specified object ID doesn't exist, a new record is added to your index.
     - If you add a record to an index that doesn't exist yet, a new index is created.
 
-    To update _some_ attributes of a record, use the [`partial` operation](#tag/Records/operation/partialUpdateObject).
-    To add, update, or replace multiple records, use the [`batch` operation](#tag/Records/operation/batch).
+    To update _some_ attributes of a record, use the [`partial` operation](https://www.algolia.com/doc/rest-api/search/partial-update-object).
+    To add, update, or replace multiple records, use the [`batch` operation](https://www.algolia.com/doc/rest-api/search/batch).
 
     This operation is subject to [indexing rate limits](https://support.algolia.com/hc/en-us/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
   summary: Add a new record (with auto-generated object ID)
diff --git a/specs/search/paths/rules/rule.yml b/specs/search/paths/rules/rule.yml
@@ -7,7 +7,7 @@ get:
   summary: Retrieve a rule
   description: |
     Retrieves a rule by its ID.
-    To find the object ID of rules, use the [`search` operation](#tag/Rules/operation/searchRules).
+    To find the object ID of rules, use the [`search` operation](https://www.algolia.com/doc/rest-api/search/search-rules).
 
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
@@ -39,7 +39,7 @@ put:
     If a rule with the specified object ID doesn't exist, it's created.
     Otherwise, the existing rule is replaced.
 
-    To create or update more than one rule, use the [`batch` operation](#tag/Rules/operation/saveRules).
+    To create or update more than one rule, use the [`batch` operation](https://www.algolia.com/doc/rest-api/search/save-rules).
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - $ref: 'common/parameters.yml#/ObjectIDRule'
@@ -72,7 +72,7 @@ delete:
   description: |
     Deletes a rule by its ID.
     To find the object ID for rules,
-    use the [`search` operation](#tag/Rules/operation/searchRules).
+    use the [`search` operation](https://www.algolia.com/doc/rest-api/search/search-rules).
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - $ref: 'common/parameters.yml#/ObjectIDRule'
diff --git a/specs/search/paths/search/searchSingleIndex.yml b/specs/search/paths/search/searchSingleIndex.yml
@@ -9,10 +9,10 @@ post:
     - search
   summary: Search an index
   description: |
-    Searches a single index and returns matching search results (_hits_).
+    Searches a single index and returns matching search results as hits.
 
     This method lets you retrieve up to 1,000 hits.
-    If you need more, use the [`browse` operation](#tag/Search/operation/browse) or increase the `paginatedLimitedTo` index setting.
+    If you need more, use the [`browse` operation](https://www.algolia.com/doc/rest-api/search/browse) or increase the `paginatedLimitedTo` index setting.
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
   requestBody:
diff --git a/specs/search/paths/synonyms/synonym.yml b/specs/search/paths/synonyms/synonym.yml
@@ -8,7 +8,7 @@ get:
   description: |
     Retrieves a synonym by its ID.
     To find the object IDs for your synonyms,
-    use the [`search` operation](#tag/Synonyms/operation/searchSynonyms).
+    use the [`search` operation](https://www.algolia.com/doc/rest-api/search/search-synonyms).
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - $ref: 'common/parameters.yml#/ObjectID'
@@ -38,7 +38,7 @@ put:
   description: |
     If a synonym with the specified object ID doesn't exist, Algolia adds a new one.
     Otherwise, the existing synonym is replaced.
-    To add multiple synonyms in a single API request, use the [`batch` operation](#tag/Synonyms/operation/saveSynonyms).
+    To add multiple synonyms in a single API request, use the [`batch` operation](https://www.algolia.com/doc/rest-api/search/save-synonyms).
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - $ref: 'common/parameters.yml#/ObjectID'
@@ -87,7 +87,7 @@ delete:
   summary: Delete a synonym
   description: |
     Deletes a synonym by its ID.
-    To find the object IDs of your synonyms, use the [`search` operation](#tag/Synonyms/operation/searchSynonyms).
+    To find the object IDs of your synonyms, use the [`search` operation](https://www.algolia.com/doc/rest-api/search/search-synonyms).
   parameters:
     - $ref: '../../../common/parameters.yml#/IndexName'
     - $ref: 'common/parameters.yml#/ObjectID'
