docs(openapi): Add undocumented kvs endpoints (#2438)

### Description
- Add undocumented, but public API endpoints related to kvs:
  - Actor run  default kvs
  - last Actor run default kvs
- Abstract reusable parts of nearly duplicate endpoints and use
references.
- Create subgroups in `Convenience endpoints`, to avoid cluttering the
documentation.

(More undocumented endpoints will be added in follow-up PRs)

### Issues
Partially implements: #2286

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: Pijukatel

AGENTS.md

@@ -59,6 +59,8 @@ Add code samples by creating files in `apify-api/openapi/code_samples/{javascrip
   - Request parameters and path parameters defined in  `/openapi/components/parameters`
   - Request/response schemas defined in `/openapi/components/schemas`
   - Explicit non-automatic examples defined in `/openapi/components/examples`
+  - Objects that are not standardized in the OpenAPI specification defined in `/openapi/components/objects`
+- Objects that exist in several variants with only minor differences across different files can be extracted into file in `/openapi/components/objects`. Within one file the YAML anchor syntax can be used to define a shared and unique portion of such objects and avoid some code duplication. These objects will be used only during bundling process through references, but they will not be standalone entities in the generated specification.
 - When changing files in `/openapi/paths` look for opportunities to extract shared duplicate objects into re-usable components saved in `/openapi/components`.
 - When adding new endpoints, check first if any existing path is similar and if yes, try to re-use same components. If by adding new paths you create new duplication, try to extract it into a new components and reference it instead.
 - Prefer automatically generated examples from schema over explicit examples.

apify-api/openapi/components/objects/datasets/dataset-items.yaml

@@ -16,35 +16,35 @@ sharedTagById: &sharedTagById
 
 sharedTagDefault: &sharedTagDefault
   tags:
-    - Default storages
+    - Default dataset
 
 sharedTagLastRun: &sharedTagLastRun
   tags:
-    - Last Actor run
+    - Last Actor run's default dataset
 
 parametersGetHeadById: &parametersGetHeadById
   parameters:
-    - $ref: "../../parameters/storageParameters.yaml#/datasetId"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/format"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/clean"
+    - $ref: "../../parameters/datasetParameters.yaml#/datasetId"
+    - $ref: "../../parameters/datasetParameters.yaml#/format"
+    - $ref: "../../parameters/datasetParameters.yaml#/clean"
     - $ref: "../../parameters/paginationParameters.yaml#/offset"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/limit"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/fields"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/omit"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/unwind"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/flatten"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/descDataset"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/attachment"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/delimiter"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/bom"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/xmlRoot"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/xmlRow"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/skipHeaderRow"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/skipHidden"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/skipEmpty"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/simplified"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/view"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/skipFailedPages"
+    - $ref: "../../parameters/datasetParameters.yaml#/limit"
+    - $ref: "../../parameters/datasetParameters.yaml#/fields"
+    - $ref: "../../parameters/datasetParameters.yaml#/omit"
+    - $ref: "../../parameters/datasetParameters.yaml#/unwind"
+    - $ref: "../../parameters/datasetParameters.yaml#/flatten"
+    - $ref: "../../parameters/datasetParameters.yaml#/descDataset"
+    - $ref: "../../parameters/datasetParameters.yaml#/attachment"
+    - $ref: "../../parameters/datasetParameters.yaml#/delimiter"
+    - $ref: "../../parameters/datasetParameters.yaml#/bom"
+    - $ref: "../../parameters/datasetParameters.yaml#/xmlRoot"
+    - $ref: "../../parameters/datasetParameters.yaml#/xmlRow"
+    - $ref: "../../parameters/datasetParameters.yaml#/skipHeaderRow"
+    - $ref: "../../parameters/datasetParameters.yaml#/skipHidden"
+    - $ref: "../../parameters/datasetParameters.yaml#/skipEmpty"
+    - $ref: "../../parameters/datasetParameters.yaml#/simplified"
+    - $ref: "../../parameters/datasetParameters.yaml#/view"
+    - $ref: "../../parameters/datasetParameters.yaml#/skipFailedPages"
     - $ref: "../../parameters/storageParameters.yaml#/signature"
 
 sharedGet: &sharedGet
@@ -264,26 +264,26 @@ getDefault:
   operationId: actorRun_dataset_items_get
   parameters:
     - $ref: "../../parameters/runAndBuildParameters.yaml#/runId"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/format"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/clean"
+    - $ref: "../../parameters/datasetParameters.yaml#/format"
+    - $ref: "../../parameters/datasetParameters.yaml#/clean"
     - $ref: "../../parameters/paginationParameters.yaml#/offset"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/limit"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/fields"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/omit"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/unwind"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/flatten"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/descDataset"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/attachment"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/delimiter"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/bom"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/xmlRoot"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/xmlRow"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/skipHeaderRow"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/skipHidden"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/skipEmpty"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/simplified"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/view"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/skipFailedPages"
+    - $ref: "../../parameters/datasetParameters.yaml#/limit"
+    - $ref: "../../parameters/datasetParameters.yaml#/fields"
+    - $ref: "../../parameters/datasetParameters.yaml#/omit"
+    - $ref: "../../parameters/datasetParameters.yaml#/unwind"
+    - $ref: "../../parameters/datasetParameters.yaml#/flatten"
+    - $ref: "../../parameters/datasetParameters.yaml#/descDataset"
+    - $ref: "../../parameters/datasetParameters.yaml#/attachment"
+    - $ref: "../../parameters/datasetParameters.yaml#/delimiter"
+    - $ref: "../../parameters/datasetParameters.yaml#/bom"
+    - $ref: "../../parameters/datasetParameters.yaml#/xmlRoot"
+    - $ref: "../../parameters/datasetParameters.yaml#/xmlRow"
+    - $ref: "../../parameters/datasetParameters.yaml#/skipHeaderRow"
+    - $ref: "../../parameters/datasetParameters.yaml#/skipHidden"
+    - $ref: "../../parameters/datasetParameters.yaml#/skipEmpty"
+    - $ref: "../../parameters/datasetParameters.yaml#/simplified"
+    - $ref: "../../parameters/datasetParameters.yaml#/view"
+    - $ref: "../../parameters/datasetParameters.yaml#/skipFailedPages"
     - $ref: "../../parameters/storageParameters.yaml#/signature"
 
 getLastRun:
@@ -298,26 +298,26 @@ getLastRun:
   parameters:
     - $ref: "../../parameters/runAndBuildParameters.yaml#/actorId"
     - $ref: "../../parameters/runAndBuildParameters.yaml#/statusLastRun"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/format"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/clean"
+    - $ref: "../../parameters/datasetParameters.yaml#/format"
+    - $ref: "../../parameters/datasetParameters.yaml#/clean"
     - $ref: "../../parameters/paginationParameters.yaml#/offset"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/limit"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/fields"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/omit"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/unwind"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/flatten"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/descDataset"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/attachment"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/delimiter"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/bom"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/xmlRoot"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/xmlRow"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/skipHeaderRow"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/skipHidden"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/skipEmpty"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/simplified"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/view"
-    - $ref: "../../parameters/datasetItemsParameters.yaml#/skipFailedPages"
+    - $ref: "../../parameters/datasetParameters.yaml#/limit"
+    - $ref: "../../parameters/datasetParameters.yaml#/fields"
+    - $ref: "../../parameters/datasetParameters.yaml#/omit"
+    - $ref: "../../parameters/datasetParameters.yaml#/unwind"
+    - $ref: "../../parameters/datasetParameters.yaml#/flatten"
+    - $ref: "../../parameters/datasetParameters.yaml#/descDataset"
+    - $ref: "../../parameters/datasetParameters.yaml#/attachment"
+    - $ref: "../../parameters/datasetParameters.yaml#/delimiter"
+    - $ref: "../../parameters/datasetParameters.yaml#/bom"
+    - $ref: "../../parameters/datasetParameters.yaml#/xmlRoot"
+    - $ref: "../../parameters/datasetParameters.yaml#/xmlRow"
+    - $ref: "../../parameters/datasetParameters.yaml#/skipHeaderRow"
+    - $ref: "../../parameters/datasetParameters.yaml#/skipHidden"
+    - $ref: "../../parameters/datasetParameters.yaml#/skipEmpty"
+    - $ref: "../../parameters/datasetParameters.yaml#/simplified"
+    - $ref: "../../parameters/datasetParameters.yaml#/view"
+    - $ref: "../../parameters/datasetParameters.yaml#/skipFailedPages"
     - $ref: "../../parameters/storageParameters.yaml#/signature"
 
 headById:
@@ -391,7 +391,7 @@ postById:
     **IMPORTANT:** The limit of request payload size for the dataset is 5 MB. If the array exceeds the size, you'll need to split it into a number of smaller arrays.
   operationId: dataset_items_post
   parameters:
-    - $ref: "../../parameters/storageParameters.yaml#/datasetId"
+    - $ref: "../../parameters/datasetParameters.yaml#/datasetId"
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/datasets/item-collection/put-items
     - https://docs.apify.com/api/v2#/reference/datasets/put-items

apify-api/openapi/components/objects/datasets/dataset-statistics.yaml

@@ -31,12 +31,12 @@ getById:
 
   operationId: dataset_statistics_get
   parameters:
-    - $ref: "../../parameters/storageParameters.yaml#/datasetId"
+    - $ref: "../../parameters/datasetParameters.yaml#/datasetId"
 
 getDefault:
   <<: *sharedGet
   tags:
-    - Default storages
+    - Default dataset
   summary: Get default dataset statistics
   description: |
     Returns statistics for the Actor run's default dataset.
@@ -50,7 +50,7 @@ getDefault:
 getLastRun:
   <<: *sharedGet
   tags:
-    - Last Actor run
+    - Last Actor run's default dataset
   summary: Get last run's dataset statistics
   description: |
     Returns statistics for the last Actor run's default dataset.

apify-api/openapi/components/objects/datasets/dataset.yaml

@@ -25,17 +25,17 @@ sharedById: &sharedById
   tags:
     - Storage/Datasets
   parameters:
-    - $ref: "../../parameters/storageParameters.yaml#/datasetId"
+    - $ref: "../../parameters/datasetParameters.yaml#/datasetId"
 
 sharedDefault: &sharedDefault
   tags:
-    - Default storages
+    - Default dataset
   parameters:
     - $ref: "../../parameters/runAndBuildParameters.yaml#/runId"
 
 sharedLastRun: &sharedLastRun
   tags:
-    - Last Actor run
+    - Last Actor run's default dataset
   parameters:
     - $ref: "../../parameters/runAndBuildParameters.yaml#/actorId"
     - $ref: "../../parameters/runAndBuildParameters.yaml#/statusLastRun"

apify-api/openapi/components/objects/key-value-stores/key-value-store-keys.yaml

@@ -0,0 +1,100 @@
+commonErrors: &commonErrors
+  "400":
+    $ref: ../../responses/BadRequest.yaml
+  "401":
+    $ref: ../../responses/Unauthorized.yaml
+  "403":
+    $ref: ../../responses/Forbidden.yaml
+  "404":
+    $ref: ../../responses/NotFound.yaml
+  "405":
+    $ref: ../../responses/MethodNotAllowed.yaml
+  "429":
+    $ref: ../../responses/TooManyRequests.yaml
+
+sharedTagById: &sharedTagById
+  tags:
+    - Storage/Key-value stores
+
+sharedTagDefault: &sharedTagDefault
+  tags:
+    - Default key-value store
+
+sharedTagLastRun: &sharedTagLastRun
+  tags:
+    - Last Actor run's default key-value store
+
+sharedGet: &sharedGet
+  responses:
+    <<: *commonErrors
+    "200":
+      description: ""
+      headers: {}
+      content:
+        application/json:
+          schema:
+            $ref: ../../schemas/key-value-stores/ListOfKeysResponse.yaml
+  deprecated: false
+
+getById:
+  <<: [*sharedGet, *sharedTagById]
+  summary: Get list of keys
+  description: |
+    Returns a list of objects describing keys of a given key-value store, as
+    well as some information about the values (e.g. size).
+
+    This endpoint is paginated using `exclusiveStartKey` and `limit` parameters
+    - see [Pagination](/api/v2#using-key) for more details.
+  operationId: keyValueStore_keys_get
+  parameters:
+    - $ref: "../../parameters/keyValueStoreParameters.yaml#/storeId"
+    - $ref: "../../parameters/keyValueStoreParameters.yaml#/exclusiveStartKey"
+    - $ref: "../../parameters/keyValueStoreParameters.yaml#/limit"
+    - $ref: "../../parameters/keyValueStoreParameters.yaml#/collectionKeys"
+    - $ref: "../../parameters/keyValueStoreParameters.yaml#/prefixKeys"
+    - $ref: "../../parameters/storageParameters.yaml#/signature"
+  x-legacy-doc-urls:
+    - https://docs.apify.com/api/v2#/reference/key-value-stores/key-collection/get-list-of-keys
+    - https://docs.apify.com/api/v2#/reference/key-value-stores/get-list-of-keys
+    - https://docs.apify.com/api/v2#tag/Key-value-storesKey-collection/operation/keyValueStore_keys_get
+  x-js-parent: KeyValueStoreClient
+  x-js-name: listKeys
+  x-js-doc-url: https://docs.apify.com/api/client/js/reference/class/KeyValueStoreClient#listKeys
+  x-py-parent: KeyValueStoreClientAsync
+  x-py-name: list_keys
+  x-py-doc-url: https://docs.apify.com/api/client/python/reference/class/KeyValueStoreClientAsync#list_keys
+
+getDefault:
+  <<: [*sharedGet, *sharedTagDefault]
+  summary: Get default store's list of keys
+  description: |
+    Returns a list of keys for the default key-value store of the Actor run.
+
+    This endpoint is a shortcut for getting the run's `defaultKeyValueStoreId` and then using the
+    [Get list of keys](/api/v2/key-value-store-keys-get) endpoint.
+  operationId: actorRun_keyValueStore_keys_get
+  parameters:
+    - $ref: "../../parameters/runAndBuildParameters.yaml#/runId"
+    - $ref: "../../parameters/keyValueStoreParameters.yaml#/exclusiveStartKey"
+    - $ref: "../../parameters/keyValueStoreParameters.yaml#/limit"
+    - $ref: "../../parameters/keyValueStoreParameters.yaml#/collectionKeys"
+    - $ref: "../../parameters/keyValueStoreParameters.yaml#/prefixKeys"
+    - $ref: "../../parameters/storageParameters.yaml#/signature"
+
+getLastRun:
+  <<: [*sharedGet, *sharedTagLastRun]
+  summary: Get last run's default store's list of keys
+  description: |
+    Returns a list of keys for the default key-value store of the last Actor run.
+
+    This endpoint is a shortcut for getting the last run's `defaultKeyValueStoreId` and then using the
+    [Get list of keys](/api/v2/key-value-store-keys-get) endpoint.
+  operationId: act_runs_last_keyValueStore_keys_get
+  parameters:
+    - $ref: "../../parameters/runAndBuildParameters.yaml#/actorId"
+    - $ref: "../../parameters/runAndBuildParameters.yaml#/statusLastRun"
+    - $ref: "../../parameters/keyValueStoreParameters.yaml#/exclusiveStartKey"
+    - $ref: "../../parameters/keyValueStoreParameters.yaml#/limit"
+    - $ref: "../../parameters/keyValueStoreParameters.yaml#/collectionKeys"
+    - $ref: "../../parameters/keyValueStoreParameters.yaml#/prefixKeys"
+    - $ref: "../../parameters/storageParameters.yaml#/signature"