docs: reorganize api docs

apify-api/openapi/components/x-tag-groups.yaml

@@ -1,114 +1,42 @@
 - name: Actors
   tags:
   - Actors
-  - Actors/Actor collection
-  - Actors/Actor object
-  - Actors/Version collection
-  - Actors/Version object
-  - Actors/Environment variable collection
-  - Actors/Environment variable object
+  - Actors/Actor versions
+  - Actors/Actor builds
+  - Actors/Actor runs
   - Actors/Webhook collection
-  - Actors/Build collection
-  - Actors/Build object
-  - Actors/Default build object
-  - Actors/Abort build
-  - Actors/Run collection
-  - Actors/Run actor synchronously
-  - Actors/Run Actor synchronously and get dataset items
-  - Actors/Run object
-  - Actors/Abort run
-  - Actors/Metamorph run
-  - Actors/Resurrect run
   - Actors/Last run object and its storages
-  - Actors/Get OpenAPI definition
-- name: Actor tasks
-  tags:
-  - Actor tasks
-  - Actor tasks/Task collection
-  - Actor tasks/Task object
-  - Actor tasks/Task input object
-  - Actor tasks/Webhook collection
-  - Actor tasks/Run collection
-  - Actor tasks/Run task synchronously
-  - Actor tasks/Run task synchronously and get dataset items
-  - Actor tasks/Last run object and its storages
-- name: Actor runs
-  tags:
-  - Actor runs
-  - Actor runs/Run collection
-  - Actor runs/Run object and its storages
-  - Actor runs/Delete run
-  - Actor runs/Abort run
-  - Actor runs/Metamorph run
-  - Actor runs/Reboot run
-  - Actor runs/Resurrect run
-  - Actor runs/Charge events in run
-  - Actor runs/Update status message
 - name: Actor builds
   tags:
   - Actor builds
-  - Actor builds/Build collection
-  - Actor builds/Build object
-  - Actor builds/Delete build
-  - Actor builds/Abort build
-  - Actor builds/Build log
-  - Actor builds/Get OpenAPI definition
-- name: Key-value stores
+- name: Actor runs
   tags:
-  - Key-value stores
-  - Key-value stores/Store collection
-  - Key-value stores/Store object
-  - Key-value stores/Key collection
-  - Key-value stores/Record
-- name: Datasets
+  - Actor runs
+- name: Actor tasks
   tags:
-  - Datasets
-  - Datasets/Dataset collection
-  - Datasets/Dataset
-  - Datasets/Item collection
-  - Datasets/Statistics
-- name: Request queues
+  - Actor tasks
+- name: Storage
   tags:
-  - Request queues
-  - Request queues/Queue collection
-  - Request queues/Queue
-  - Request queues/Request collection
-  - Request queues/Request
-  - Request queues/Request lock
-  - Request queues/Queue head
-  - Request queues/Queue head with locks
-  - Request queues/Batch request operations
+  - Storage/Datasets
+  - Storage/Key-value stores
+  - Storage/Request queues
+  - Storage/Request queues/Requests
+  - Storage/Request queues/Requests locks
 - name: Webhooks
   tags:
-  - Webhooks
-  - Webhooks/Webhook collection
-  - Webhooks/Webhook object
-  - Webhooks/Webhook test
-  - Webhooks/Dispatches collection
-- name: Webhook dispatches
-  tags:
-  - Webhook dispatches
-  - Webhook dispatches/Webhook dispatches collection
-  - Webhook dispatches/Webhook dispatch object
+  - Webhooks/Webhooks
+  - Webhooks/Webhook dispatches
 - name: Schedules
   tags:
   - Schedules
-  - Schedules/Schedules collection
-  - Schedules/Schedule object
-  - Schedules/Schedule log
 - name: Store
   tags:
   - Store
-  - Store/Store Actors collection
 - name: Logs
   tags:
   - Logs
-  - Logs/Log
 - name: Users
   tags:
   - Users
-  - Users/Public data
-  - Users/Private data
-  - Users/Monthly usage
-  - Users/Account and usage limits
+
 

apify-api/openapi/openapi.yaml

@@ -10,8 +10,8 @@ info:
     The Apify API (version 2) provides programmatic access to the [Apify
     platform](https://docs.apify.com). The API is organized
     around [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer)
-    HTTP endpoints. 
-    
+    HTTP endpoints.
+
     You can download the complete OpenAPI schema of Apify API in the [YAML](http://docs.apify.com/api/openapi.yaml) or [JSON](http://docs.apify.com/api/openapi.json) formats. The source code is also available on [GitHub](https://github.com/apify/apify-docs/tree/master/apify-api/openapi).
 
     All requests and responses (including errors) are encoded in
@@ -66,39 +66,39 @@ info:
     ## Basic usage
     <span id="/introduction/basic-usage"></span>
 
-    To run an actor, send a POST request to the [Run
-    actor](#/reference/actors/run-collection/run-actor) endpoint using either the
-    actor ID code (e.g. `vKg4IjxZbEYTYeW8T`) or its name (e.g.
+    To run an Actor, send a POST request to the [Run
+    Actor](#/reference/actors/run-collection/run-actor) endpoint using either the
+    Actor ID code (e.g. `vKg4IjxZbEYTYeW8T`) or its name (e.g.
     `janedoe~my-actor`):
 
     `https://api.apify.com/v2/acts/[actor_id]/runs`
 
-    If the actor is not runnable anonymously, you will receive a 401 or 403
+    If the Actor is not runnable anonymously, you will receive a 401 or 403
     [response code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status).
     This means you need to add your [secret API
     token](https://console.apify.com/account#/integrations) to the request's
     `Authorization` header ([recommended](#/introduction/authentication)) or as a
     URL query parameter `?token=[your_token]` (less secure).
 
     Optionally, you can include the query parameters described in the [Run
-    actor](#/reference/actors/run-collection/run-actor) section to customize your
+    Actor](#/reference/actors/run-collection/run-actor) section to customize your
     run.
 
-    If you're using Node.js, the best way to run an actor is using the
+    If you're using Node.js, the best way to run an Actor is using the
     `Apify.call()` method from the [Apify
     SDK](https://sdk.apify.com/docs/api/apify#apifycallactid-input-options). It
-    runs the actor using the account you are currently logged into (determined
+    runs the Actor using the account you are currently logged into (determined
     by the [secret API token](https://console.apify.com/account#/integrations)).
-    The result is an [actor run
+    The result is an [Actor run
     object](https://sdk.apify.com/docs/typedefs/actor-run) and its output (if
     any).
 
     A typical workflow is as follows:
 
-    1. Run an actor or task using the [Run
-    actor](#/reference/actors/run-collection/run-actor) or [Run
+    1. Run an Actor or task using the [Run
+    Actor](#/reference/actors/run-collection/run-actor) or [Run
     task](#/reference/actor-tasks/run-collection/run-task) API endpoints.
-    2. Monitor the actor run by periodically polling its progress using the [Get
+    2. Monitor the Actor run by periodically polling its progress using the [Get
     run](#/reference/actor-runs/run-object-and-its-storages/get-run) API
     endpoint.
     3. Fetch the results from the [Get
@@ -109,7 +109,7 @@ info:
     using the `defaultKeyValueStoreId` and the store's `key`.
 
     **Note**: Instead of periodic polling, you can also run your
-    [actor](#/reference/actors/run-actor-synchronously) or
+    [Actor](#/reference/actors/run-actor-synchronously) or
     [task](#/reference/actor-tasks/runs-collection/run-task-synchronously)
     synchronously. This will ensure that the request waits for 300 seconds (5
     minutes) for the run to finish and returns its output. If the run takes
@@ -151,7 +151,7 @@ info:
 
     All API endpoints that return a list of records
     (e.g. [Get list of
-    actors](#/reference/actors/actor-collection/get-list-of-actors))
+    Actors](#/reference/actors/actor-collection/get-list-of-actors))
     enforce pagination in order to limit the size of their responses.
 
     Most of these API endpoints are paginated using the `offset` and `limit`
@@ -417,10 +417,10 @@ info:
       operations on key-value store records
 
     These endpoints have a rate limit of _200 requests per second per resource_:
-    * [Run actor](#/reference/actors/run-collection/run-actor)
-    * [Run actor task asynchronously](#/reference/actor-tasks/runs-collection/run-task-asynchronously)
-    * [Run actor task synchronously](#/reference/actor-tasks/runs-collection/run-task-synchronously)
-    * [Metamorph actor run](#/reference/actors/metamorph-run/metamorph-run)
+    * [Run Actor](#/reference/actors/run-collection/run-actor)
+    * [Run Actor task asynchronously](#/reference/actor-tasks/runs-collection/run-task-asynchronously)
+    * [Run Actor task synchronously](#/reference/actor-tasks/runs-collection/run-task-synchronously)
+    * [Metamorph Actor run](#/reference/actors/metamorph-run/metamorph-run)
     * [Push items](#/reference/datasets/item-collection/put-items) to dataset
     * CRUD
       ([add](#/reference/request-queues/request-collection/add-request),
@@ -499,30 +499,30 @@ paths:
     $ref: 'paths/actors/acts@{actorId}@webhooks.yaml'
   '/v2/acts/{actorId}/builds':
     $ref: 'paths/actors/acts@{actorId}@builds.yaml'
-  '/v2/acts/{actorId}/builds/{buildId}':
-    $ref: 'paths/actors/acts@{actorId}@builds@{buildId}.yaml'
   '/v2/acts/{actorId}/builds/default':
     $ref: 'paths/actors/acts@{actorId}@[email protected]'
-  '/v2/acts/{actorId}/builds/{buildId}/abort':
-    $ref: 'paths/actors/acts@{actorId}@builds@{buildId}@abort.yaml'
   '/v2/acts/{actorId}/builds/{buildId}/openapi.json':
     $ref: 'paths/actors/acts@{actorId}@builds@{buildId}@openapi.json.yaml'
+  '/v2/acts/{actorId}/builds/{buildId}':
+    $ref: 'paths/actors/acts@{actorId}@builds@{buildId}.yaml'
+  '/v2/acts/{actorId}/builds/{buildId}/abort':
+    $ref: 'paths/actors/acts@{actorId}@builds@{buildId}@abort.yaml'
   '/v2/acts/{actorId}/runs':
     $ref: 'paths/actors/acts@{actorId}@runs.yaml'
   '/v2/acts/{actorId}/run-sync':
     $ref: 'paths/actors/acts@{actorId}@run-sync.yaml'
   '/v2/acts/{actorId}/run-sync-get-dataset-items':
     $ref: 'paths/actors/acts@{actorId}@run-sync-get-dataset-items.yaml'
+  '/v2/acts/{actorId}/runs/{runId}/resurrect':
+    $ref: 'paths/actors/acts@{actorId}@runs@{runId}@resurrect.yaml'
+  '/v2/acts/{actorId}/runs/last':
+    $ref: 'paths/actors/acts@{actorId}@[email protected]'
   '/v2/acts/{actorId}/runs/{runId}':
     $ref: 'paths/actors/acts@{actorId}@runs@{runId}.yaml'
   '/v2/acts/{actorId}/runs/{runId}/abort':
     $ref: 'paths/actors/acts@{actorId}@runs@{runId}@abort.yaml'
   '/v2/acts/{actorId}/runs/{runId}/metamorph':
     $ref: 'paths/actors/acts@{actorId}@runs@{runId}@metamorph.yaml'
-  '/v2/acts/{actorId}/runs/{runId}/resurrect':
-    $ref: 'paths/actors/acts@{actorId}@runs@{runId}@resurrect.yaml'
-  '/v2/acts/{actorId}/runs/last':
-    $ref: 'paths/actors/acts@{actorId}@[email protected]'
   /v2/actor-tasks:
     $ref: 'paths/actor-tasks/actor-tasks.yaml'
   '/v2/actor-tasks/{actorTaskId}':
@@ -581,18 +581,18 @@ paths:
     $ref: paths/request-queues/request-queues.yaml
   '/v2/request-queues/{queueId}':
     $ref: 'paths/request-queues/request-queues@{queueId}.yaml'
+  '/v2/request-queues/{queueId}/requests/batch':
+    $ref: 'paths/request-queues/request-queues@{queueId}@[email protected]'
   '/v2/request-queues/{queueId}/requests':
     $ref: 'paths/request-queues/request-queues@{queueId}@requests.yaml'
   '/v2/request-queues/{queueId}/requests/{requestId}':
     $ref: 'paths/request-queues/request-queues@{queueId}@requests@{requestId}.yaml'
-  '/v2/request-queues/{queueId}/requests/{requestId}/lock':
-    $ref: 'paths/request-queues/request-queues@{queueId}@requests@{requestId}@lock.yaml'
   '/v2/request-queues/{queueId}/head':
     $ref: 'paths/request-queues/request-queues@{queueId}@head.yaml'
   '/v2/request-queues/{queueId}/head/lock':
     $ref: 'paths/request-queues/request-queues@{queueId}@[email protected]'
-  '/v2/request-queues/{queueId}/requests/batch':
-    $ref: 'paths/request-queues/request-queues@{queueId}@requests@batch.yaml'
+  '/v2/request-queues/{queueId}/requests/{requestId}/lock':
+    $ref: 'paths/request-queues/request-queues@{queueId}@requests@{requestId}@lock.yaml'
   /v2/webhooks:
     $ref: paths/webhooks/webhooks.yaml
   '/v2/webhooks/{webhookId}':
@@ -602,7 +602,7 @@ paths:
   '/v2/webhooks/{webhookId}/dispatches':
     $ref: 'paths/webhooks/webhooks@{webhookId}@dispatches.yaml'
   /v2/webhook-dispatches:
-    $ref: paths/webhook-dispatches/webhook-dispatches.yaml
+    $ref: 'paths/webhook-dispatches/webhook-dispatches.yaml'
   '/v2/webhook-dispatches/{dispatchId}':
     $ref: 'paths/webhook-dispatches/webhook-dispatches@{dispatchId}.yaml'
   /v2/schedules:

apify-api/openapi/paths/actor-builds/actor-builds.yaml

@@ -1,6 +1,6 @@
 get:
   tags:
-    - Actor builds/Build collection
+    - Actor builds
   summary: Get user builds list
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/actor-builds/build-collection/get-user-builds-list

apify-api/openapi/paths/actor-builds/actor-builds@{buildId}.yaml

@@ -1,6 +1,6 @@
 get:
   tags:
-    - Actor builds/Build object
+    - Actor builds
   summary: Get build
   description: |
     Gets an object that contains all the details about a specific build of an

apify-api/openapi/paths/actor-builds/actor-builds@{buildId}@abort.yaml

@@ -1,6 +1,6 @@
 post:
   tags:
-    - Actor builds/Abort build
+    - Actor builds
   summary: Abort build
   description: |
     Aborts an Actor build and returns an object that contains all the details

apify-api/openapi/paths/actor-builds/actor-builds@{buildId}@log.yaml

@@ -1,6 +1,6 @@
 get:
   tags:
-    - Actor builds/Build log
+    - Actor builds
   summary: Get log
   # TODO: Fix description once /logs is cleaned up as well
   description: 'Check out [Logs](#/reference/logs) for full reference.'

apify-api/openapi/paths/actor-builds/actor-builds@{buildId}@openapi.json.yaml

@@ -1,11 +1,16 @@
 get:
   tags:
-    - Actor builds/Get OpenAPI definition
+    - Actor builds
   summary: Get OpenAPI definition
   description: |
+    Get the OpenAPI definition for Actor builds. Two similar endpoints are available:
+
+    - [First endpoint](/api/v2/act-openapi-json-get): Requires both `actorId` and `buildId`. Use `default` as the `buildId` to get the OpenAPI schema for the default Actor build.
+    - [Second endpoint](/api/v2/actor-build-openapi-json-get): Requires only `buildId`.
+
     Get the OpenAPI definition for a specific Actor build.
     Authentication is based on the build's unique ID. No authentication token is required.
-    
+
     **Note**: You can also use the `/api/v2/act-openapi-json-get` endpoint to get the OpenAPI definition for a build.
   operationId: actorBuild_openapi_json_get
   security:

apify-api/openapi/paths/actor-runs/actor-runs.yaml

@@ -1,6 +1,6 @@
 get:
   tags:
-    - Actor runs/Run collection
+    - Actor runs
   summary: Get user runs list
   description: |
     Gets a list of all runs for a user. The response is a list of objects, where