Skip to content

Commit d676859

Browse files
TC-MOTC-MO
authored
docs: reorganize api docs (#1445)
1 parent a808906 commit d676859

File tree

73 files changed

+713
-1279
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

73 files changed

+713
-1279
lines changed

‎apify-api/openapi/components/tags.yaml

Lines changed: 250 additions & 733 deletions
Large diffs are not rendered by default.

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

Lines changed: 16 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,114 +1,42 @@
11
- name: Actors
22
tags:
33
- Actors
4-
- Actors/Actor collection
5-
- Actors/Actor object
6-
- Actors/Version collection
7-
- Actors/Version object
8-
- Actors/Environment variable collection
9-
- Actors/Environment variable object
4+
- Actors/Actor versions
5+
- Actors/Actor builds
6+
- Actors/Actor runs
107
- Actors/Webhook collection
11-
- Actors/Build collection
12-
- Actors/Build object
13-
- Actors/Default build object
14-
- Actors/Abort build
15-
- Actors/Run collection
16-
- Actors/Run actor synchronously
17-
- Actors/Run Actor synchronously and get dataset items
18-
- Actors/Run object
19-
- Actors/Abort run
20-
- Actors/Metamorph run
21-
- Actors/Resurrect run
228
- Actors/Last run object and its storages
23-
- Actors/Get OpenAPI definition
24-
- name: Actor tasks
25-
tags:
26-
- Actor tasks
27-
- Actor tasks/Task collection
28-
- Actor tasks/Task object
29-
- Actor tasks/Task input object
30-
- Actor tasks/Webhook collection
31-
- Actor tasks/Run collection
32-
- Actor tasks/Run task synchronously
33-
- Actor tasks/Run task synchronously and get dataset items
34-
- Actor tasks/Last run object and its storages
35-
- name: Actor runs
36-
tags:
37-
- Actor runs
38-
- Actor runs/Run collection
39-
- Actor runs/Run object and its storages
40-
- Actor runs/Delete run
41-
- Actor runs/Abort run
42-
- Actor runs/Metamorph run
43-
- Actor runs/Reboot run
44-
- Actor runs/Resurrect run
45-
- Actor runs/Charge events in run
46-
- Actor runs/Update status message
479
- name: Actor builds
4810
tags:
4911
- Actor builds
50-
- Actor builds/Build collection
51-
- Actor builds/Build object
52-
- Actor builds/Delete build
53-
- Actor builds/Abort build
54-
- Actor builds/Build log
55-
- Actor builds/Get OpenAPI definition
56-
- name: Key-value stores
12+
- name: Actor runs
5713
tags:
58-
- Key-value stores
59-
- Key-value stores/Store collection
60-
- Key-value stores/Store object
61-
- Key-value stores/Key collection
62-
- Key-value stores/Record
63-
- name: Datasets
14+
- Actor runs
15+
- name: Actor tasks
6416
tags:
65-
- Datasets
66-
- Datasets/Dataset collection
67-
- Datasets/Dataset
68-
- Datasets/Item collection
69-
- Datasets/Statistics
70-
- name: Request queues
17+
- Actor tasks
18+
- name: Storage
7119
tags:
72-
- Request queues
73-
- Request queues/Queue collection
74-
- Request queues/Queue
75-
- Request queues/Request collection
76-
- Request queues/Request
77-
- Request queues/Request lock
78-
- Request queues/Queue head
79-
- Request queues/Queue head with locks
80-
- Request queues/Batch request operations
20+
- Storage/Datasets
21+
- Storage/Key-value stores
22+
- Storage/Request queues
23+
- Storage/Request queues/Requests
24+
- Storage/Request queues/Requests locks
8125
- name: Webhooks
8226
tags:
83-
- Webhooks
84-
- Webhooks/Webhook collection
85-
- Webhooks/Webhook object
86-
- Webhooks/Webhook test
87-
- Webhooks/Dispatches collection
88-
- name: Webhook dispatches
89-
tags:
90-
- Webhook dispatches
91-
- Webhook dispatches/Webhook dispatches collection
92-
- Webhook dispatches/Webhook dispatch object
27+
- Webhooks/Webhooks
28+
- Webhooks/Webhook dispatches
9329
- name: Schedules
9430
tags:
9531
- Schedules
96-
- Schedules/Schedules collection
97-
- Schedules/Schedule object
98-
- Schedules/Schedule log
9932
- name: Store
10033
tags:
10134
- Store
102-
- Store/Store Actors collection
10335
- name: Logs
10436
tags:
10537
- Logs
106-
- Logs/Log
10738
- name: Users
10839
tags:
10940
- Users
110-
- Users/Public data
111-
- Users/Private data
112-
- Users/Monthly usage
113-
- Users/Account and usage limits
41+
11442

‎apify-api/openapi/openapi.yaml

Lines changed: 32 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ info:
1010
The Apify API (version 2) provides programmatic access to the [Apify
1111
platform](https://docs.apify.com). The API is organized
1212
around [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer)
13-
HTTP endpoints.
14-
13+
HTTP endpoints.
14+
1515
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).
1616
1717
All requests and responses (including errors) are encoded in
@@ -66,39 +66,39 @@ info:
6666
## Basic usage
6767
<span id="/introduction/basic-usage"></span>
6868
69-
To run an actor, send a POST request to the [Run
70-
actor](#/reference/actors/run-collection/run-actor) endpoint using either the
71-
actor ID code (e.g. `vKg4IjxZbEYTYeW8T`) or its name (e.g.
69+
To run an Actor, send a POST request to the [Run
70+
Actor](#/reference/actors/run-collection/run-actor) endpoint using either the
71+
Actor ID code (e.g. `vKg4IjxZbEYTYeW8T`) or its name (e.g.
7272
`janedoe~my-actor`):
7373
7474
`https://api.apify.com/v2/acts/[actor_id]/runs`
7575
76-
If the actor is not runnable anonymously, you will receive a 401 or 403
76+
If the Actor is not runnable anonymously, you will receive a 401 or 403
7777
[response code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status).
7878
This means you need to add your [secret API
7979
token](https://console.apify.com/account#/integrations) to the request's
8080
`Authorization` header ([recommended](#/introduction/authentication)) or as a
8181
URL query parameter `?token=[your_token]` (less secure).
8282
8383
Optionally, you can include the query parameters described in the [Run
84-
actor](#/reference/actors/run-collection/run-actor) section to customize your
84+
Actor](#/reference/actors/run-collection/run-actor) section to customize your
8585
run.
8686
87-
If you're using Node.js, the best way to run an actor is using the
87+
If you're using Node.js, the best way to run an Actor is using the
8888
`Apify.call()` method from the [Apify
8989
SDK](https://sdk.apify.com/docs/api/apify#apifycallactid-input-options). It
90-
runs the actor using the account you are currently logged into (determined
90+
runs the Actor using the account you are currently logged into (determined
9191
by the [secret API token](https://console.apify.com/account#/integrations)).
92-
The result is an [actor run
92+
The result is an [Actor run
9393
object](https://sdk.apify.com/docs/typedefs/actor-run) and its output (if
9494
any).
9595
9696
A typical workflow is as follows:
9797
98-
1. Run an actor or task using the [Run
99-
actor](#/reference/actors/run-collection/run-actor) or [Run
98+
1. Run an Actor or task using the [Run
99+
Actor](#/reference/actors/run-collection/run-actor) or [Run
100100
task](#/reference/actor-tasks/run-collection/run-task) API endpoints.
101-
2. Monitor the actor run by periodically polling its progress using the [Get
101+
2. Monitor the Actor run by periodically polling its progress using the [Get
102102
run](#/reference/actor-runs/run-object-and-its-storages/get-run) API
103103
endpoint.
104104
3. Fetch the results from the [Get
@@ -109,7 +109,7 @@ info:
109109
using the `defaultKeyValueStoreId` and the store's `key`.
110110
111111
**Note**: Instead of periodic polling, you can also run your
112-
[actor](#/reference/actors/run-actor-synchronously) or
112+
[Actor](#/reference/actors/run-actor-synchronously) or
113113
[task](#/reference/actor-tasks/runs-collection/run-task-synchronously)
114114
synchronously. This will ensure that the request waits for 300 seconds (5
115115
minutes) for the run to finish and returns its output. If the run takes
@@ -151,7 +151,7 @@ info:
151151
152152
All API endpoints that return a list of records
153153
(e.g. [Get list of
154-
actors](#/reference/actors/actor-collection/get-list-of-actors))
154+
Actors](#/reference/actors/actor-collection/get-list-of-actors))
155155
enforce pagination in order to limit the size of their responses.
156156
157157
Most of these API endpoints are paginated using the `offset` and `limit`
@@ -417,10 +417,10 @@ info:
417417
operations on key-value store records
418418
419419
These endpoints have a rate limit of _200 requests per second per resource_:
420-
* [Run actor](#/reference/actors/run-collection/run-actor)
421-
* [Run actor task asynchronously](#/reference/actor-tasks/runs-collection/run-task-asynchronously)
422-
* [Run actor task synchronously](#/reference/actor-tasks/runs-collection/run-task-synchronously)
423-
* [Metamorph actor run](#/reference/actors/metamorph-run/metamorph-run)
420+
* [Run Actor](#/reference/actors/run-collection/run-actor)
421+
* [Run Actor task asynchronously](#/reference/actor-tasks/runs-collection/run-task-asynchronously)
422+
* [Run Actor task synchronously](#/reference/actor-tasks/runs-collection/run-task-synchronously)
423+
* [Metamorph Actor run](#/reference/actors/metamorph-run/metamorph-run)
424424
* [Push items](#/reference/datasets/item-collection/put-items) to dataset
425425
* CRUD
426426
([add](#/reference/request-queues/request-collection/add-request),
@@ -499,30 +499,30 @@ paths:
499499
$ref: 'paths/actors/acts@{actorId}@webhooks.yaml'
500500
'/v2/acts/{actorId}/builds':
501501
$ref: 'paths/actors/acts@{actorId}@builds.yaml'
502-
'/v2/acts/{actorId}/builds/{buildId}':
503-
$ref: 'paths/actors/acts@{actorId}@builds@{buildId}.yaml'
504502
'/v2/acts/{actorId}/builds/default':
505503
$ref: 'paths/actors/acts@{actorId}@[email protected]'
506-
'/v2/acts/{actorId}/builds/{buildId}/abort':
507-
$ref: 'paths/actors/acts@{actorId}@builds@{buildId}@abort.yaml'
508504
'/v2/acts/{actorId}/builds/{buildId}/openapi.json':
509505
$ref: 'paths/actors/acts@{actorId}@builds@{buildId}@openapi.json.yaml'
506+
'/v2/acts/{actorId}/builds/{buildId}':
507+
$ref: 'paths/actors/acts@{actorId}@builds@{buildId}.yaml'
508+
'/v2/acts/{actorId}/builds/{buildId}/abort':
509+
$ref: 'paths/actors/acts@{actorId}@builds@{buildId}@abort.yaml'
510510
'/v2/acts/{actorId}/runs':
511511
$ref: 'paths/actors/acts@{actorId}@runs.yaml'
512512
'/v2/acts/{actorId}/run-sync':
513513
$ref: 'paths/actors/acts@{actorId}@run-sync.yaml'
514514
'/v2/acts/{actorId}/run-sync-get-dataset-items':
515515
$ref: 'paths/actors/acts@{actorId}@run-sync-get-dataset-items.yaml'
516+
'/v2/acts/{actorId}/runs/{runId}/resurrect':
517+
$ref: 'paths/actors/acts@{actorId}@runs@{runId}@resurrect.yaml'
518+
'/v2/acts/{actorId}/runs/last':
519+
$ref: 'paths/actors/acts@{actorId}@[email protected]'
516520
'/v2/acts/{actorId}/runs/{runId}':
517521
$ref: 'paths/actors/acts@{actorId}@runs@{runId}.yaml'
518522
'/v2/acts/{actorId}/runs/{runId}/abort':
519523
$ref: 'paths/actors/acts@{actorId}@runs@{runId}@abort.yaml'
520524
'/v2/acts/{actorId}/runs/{runId}/metamorph':
521525
$ref: 'paths/actors/acts@{actorId}@runs@{runId}@metamorph.yaml'
522-
'/v2/acts/{actorId}/runs/{runId}/resurrect':
523-
$ref: 'paths/actors/acts@{actorId}@runs@{runId}@resurrect.yaml'
524-
'/v2/acts/{actorId}/runs/last':
525-
$ref: 'paths/actors/acts@{actorId}@[email protected]'
526526
/v2/actor-tasks:
527527
$ref: 'paths/actor-tasks/actor-tasks.yaml'
528528
'/v2/actor-tasks/{actorTaskId}':
@@ -581,18 +581,18 @@ paths:
581581
$ref: paths/request-queues/request-queues.yaml
582582
'/v2/request-queues/{queueId}':
583583
$ref: 'paths/request-queues/request-queues@{queueId}.yaml'
584+
'/v2/request-queues/{queueId}/requests/batch':
585+
$ref: 'paths/request-queues/request-queues@{queueId}@[email protected]'
584586
'/v2/request-queues/{queueId}/requests':
585587
$ref: 'paths/request-queues/request-queues@{queueId}@requests.yaml'
586588
'/v2/request-queues/{queueId}/requests/{requestId}':
587589
$ref: 'paths/request-queues/request-queues@{queueId}@requests@{requestId}.yaml'
588-
'/v2/request-queues/{queueId}/requests/{requestId}/lock':
589-
$ref: 'paths/request-queues/request-queues@{queueId}@requests@{requestId}@lock.yaml'
590590
'/v2/request-queues/{queueId}/head':
591591
$ref: 'paths/request-queues/request-queues@{queueId}@head.yaml'
592592
'/v2/request-queues/{queueId}/head/lock':
593593
$ref: 'paths/request-queues/request-queues@{queueId}@[email protected]'
594-
'/v2/request-queues/{queueId}/requests/batch':
595-
$ref: 'paths/request-queues/request-queues@{queueId}@requests@batch.yaml'
594+
'/v2/request-queues/{queueId}/requests/{requestId}/lock':
595+
$ref: 'paths/request-queues/request-queues@{queueId}@requests@{requestId}@lock.yaml'
596596
/v2/webhooks:
597597
$ref: paths/webhooks/webhooks.yaml
598598
'/v2/webhooks/{webhookId}':
@@ -602,7 +602,7 @@ paths:
602602
'/v2/webhooks/{webhookId}/dispatches':
603603
$ref: 'paths/webhooks/webhooks@{webhookId}@dispatches.yaml'
604604
/v2/webhook-dispatches:
605-
$ref: paths/webhook-dispatches/webhook-dispatches.yaml
605+
$ref: 'paths/webhook-dispatches/webhook-dispatches.yaml'
606606
'/v2/webhook-dispatches/{dispatchId}':
607607
$ref: 'paths/webhook-dispatches/webhook-dispatches@{dispatchId}.yaml'
608608
/v2/schedules:

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
get:
22
tags:
3-
- Actor builds/Build collection
3+
- Actor builds
44
summary: Get user builds list
55
x-legacy-doc-urls:
66
- 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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
get:
22
tags:
3-
- Actor builds/Build object
3+
- Actor builds
44
summary: Get build
55
description: |
66
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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
post:
22
tags:
3-
- Actor builds/Abort build
3+
- Actor builds
44
summary: Abort build
55
description: |
66
Aborts an Actor build and returns an object that contains all the details

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
get:
22
tags:
3-
- Actor builds/Build log
3+
- Actor builds
44
summary: Get log
55
# TODO: Fix description once /logs is cleaned up as well
66
description: 'Check out [Logs](#/reference/logs) for full reference.'

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

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,16 @@
11
get:
22
tags:
3-
- Actor builds/Get OpenAPI definition
3+
- Actor builds
44
summary: Get OpenAPI definition
55
description: |
6+
Get the OpenAPI definition for Actor builds. Two similar endpoints are available:
7+
8+
- [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.
9+
- [Second endpoint](/api/v2/actor-build-openapi-json-get): Requires only `buildId`.
10+
611
Get the OpenAPI definition for a specific Actor build.
712
Authentication is based on the build's unique ID. No authentication token is required.
8-
13+
914
**Note**: You can also use the `/api/v2/act-openapi-json-get` endpoint to get the OpenAPI definition for a build.
1015
operationId: actorBuild_openapi_json_get
1116
security:

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
get:
22
tags:
3-
- Actor runs/Run collection
3+
- Actor runs
44
summary: Get user runs list
55
description: |
66
Gets a list of all runs for a user. The response is a list of objects, where

0 commit comments

Comments
 (0)