From 20ed6be9d13bbce68759e25e07ba379dac851c7f Mon Sep 17 00:00:00 2001 From: szaganek Date: Mon, 3 Aug 2026 09:32:09 +0200 Subject: [PATCH 1/4] docs(openapi): Add missing descriptions to Get Actor endpoint --- .../parameters/runAndBuildParameters.yaml | 4 +- .../components/schemas/actors/Actor.yaml | 46 +++++++++++++++---- .../components/schemas/actors/ActorStats.yaml | 23 +++++++++- apify-api/openapi/components/tags.yaml | 10 ++-- .../openapi/paths/actors/acts@{actorId}.yaml | 8 ++-- 5 files changed, 72 insertions(+), 19 deletions(-) diff --git a/apify-api/openapi/components/parameters/runAndBuildParameters.yaml b/apify-api/openapi/components/parameters/runAndBuildParameters.yaml index 37d98fb581..fe351a8dfe 100644 --- a/apify-api/openapi/components/parameters/runAndBuildParameters.yaml +++ b/apify-api/openapi/components/parameters/runAndBuildParameters.yaml @@ -1,12 +1,12 @@ actorId: name: actorId in: path - description: Actor ID or a tilde-separated owner's username and Actor name. + description: Actor ID or the username of the Actor owner and the Actor name, separated by a tilde (`~`). required: true style: simple schema: type: string - example: janedoe~my-actor + example: compass~google-maps-extractor actorTaskId: name: actorTaskId diff --git a/apify-api/openapi/components/schemas/actors/Actor.yaml b/apify-api/openapi/components/schemas/actors/Actor.yaml index 6d609ab92d..5fba308704 100644 --- a/apify-api/openapi/components/schemas/actors/Actor.yaml +++ b/apify-api/openapi/components/schemas/actors/Actor.yaml @@ -15,18 +15,23 @@ properties: id: type: string examples: [zdc3Pyhyz3m8vjDeM] + description: The ID of the Actor. userId: type: string examples: [wRsJZtadYvn4mBZmm] + description: The ID of the user who owns the Actor. name: type: string - examples: [MyActor] + examples: [google-search-extractor] + description: The name of the Actor. username: type: string - examples: [jane35] + examples: [compass] + description: The username of the Actor owner. description: type: [string, "null"] - examples: [My favourite actor!] + examples: [Extract data from hundreds of places fast.] + description: Short description of the Actor, displayed in Apify Store and Console. restartOnError: type: boolean examples: [false] @@ -34,23 +39,27 @@ properties: isPublic: type: boolean examples: [false] + description: Whether the Actor is available to users in Apify Store. actorPermissionLevel: $ref: ./ActorPermissionLevel.yaml createdAt: type: string format: date-time examples: ["2019-07-08T11:27:57.401Z"] + description: The date and time the Actor was created. modifiedAt: type: string format: date-time examples: ["2019-07-08T14:01:05.546Z"] + description: The date and time the Actor was last modified. stats: $ref: ./ActorStats.yaml versions: type: array items: $ref: ./Version.yaml - description: "" + description: "An array of `Version` objects. Each object represents a specific version of the + Actor's source code: its location, builds, and environment configuration." pricingInfos: type: array items: @@ -64,12 +73,15 @@ properties: isDeprecated: type: [boolean, "null"] examples: [false] + description: Whether the Actor is deprecated. deploymentKey: type: string examples: [ssh-rsa AAAA ...] + description: The Actor's public SSH key, used as a deployment key for private Git repositories. title: type: [string, "null"] - examples: [My Actor] + examples: [Google Search Extractor] + description: Human-readable name of the Actor, displayed in Apify Store and Console. taggedBuilds: anyOf: - $ref: ./TaggedBuilds.yaml @@ -80,36 +92,54 @@ properties: - type: "null" readmeSummary: type: string - description: A brief, LLM-generated readme summary + description: An AI-generated Markdown summary of the Actor's README, optimized for search and + AI agents. Contains an overview and a list of use cases. Generated only for public Actors. seoTitle: type: [string, "null"] examples: [Web Scraper] + description: Name of the Actor to display by search engines such as Google. + Can be different from the Actor's name displayed in Apify Store and Console. seoDescription: type: [string, "null"] examples: ["Crawls websites using Chrome and extracts data from pages using JavaScript."] + description: Description of the Actor to display by search engines such as Google. pictureUrl: type: [string, "null"] examples: ["https://apify-image-uploads-prod.s3.amazonaws.com/.../actor-picture.png"] + description: URL of the Actor's icon, displayed on the Actor's page in Apify Store and Console. standbyUrl: type: [string, "null"] - examples: ["https://my-actor.apify.actor"] + examples: ["https://jane35--my-actor.apify.actor"] + description: | + URL for sending requests to the Actor in Standby mode. + `null` if the Standby mode isn't enabled. notice: type: [string, "null"] + enum: [NONE, RESIDENTIAL_PROXY_REQUIRED, UNDER_MAINTENANCE] + default: NONE examples: [NONE] + description: A warning displayed on the Actor's page in Apify Store and Console. + Can be set by the Actor's developer or automatically by Apify's quality checks. categories: type: array items: type: string examples: [["DEVELOPER_TOOLS", "OPEN_SOURCE"]] + description: A list of categories that best define the Actor. Reflected in Apify Store's search and filtering options. isCritical: type: boolean examples: [false] + description: Whether the Actor is maintained by Apify. isGeneric: type: boolean examples: [false] + description: Whether the Actor is intended for developers. Set by Apify. isSourceCodeHidden: type: boolean - examples: [false] + default: true + examples: [true] + description: Whether the Actor's source files are hidden on its detail page. hasNoDataset: type: boolean examples: [false] + description: Whether the Actor stores results in a dataset. Set by Apify. diff --git a/apify-api/openapi/components/schemas/actors/ActorStats.yaml b/apify-api/openapi/components/schemas/actors/ActorStats.yaml index e23b67ab8b..ffed53b2a4 100644 --- a/apify-api/openapi/components/schemas/actors/ActorStats.yaml +++ b/apify-api/openapi/components/schemas/actors/ActorStats.yaml @@ -1,56 +1,77 @@ title: ActorStats type: object +description: Usage statistics and Apify Store metrics for the Actor. properties: totalBuilds: type: integer examples: [9] + description: The total number of builds of the Actor. totalRuns: type: integer examples: [16] + description: The total number of runs of the Actor. totalUsers: type: integer examples: [6] + description: The total number of Actor users, including its owner. totalUsers7Days: type: integer examples: [2] + description: The number of active users of the Actor in the last 7 days. totalUsers30Days: type: integer examples: [6] + description: The number of active users of the Actor in the last 30 days. totalUsers90Days: type: integer examples: [6] + description: The number of active users of the Actor in the last 90 days. totalMetamorphs: type: integer examples: [2] + description: The total number of times a run of another Actor was + [metamorphed](https://docs.apify.com/platform/actors/development/programming-interface/metamorph) + into this Actor. lastRunStartedAt: type: string format: date-time examples: ["2019-07-08T14:01:05.546Z"] + description: The date and time the most recent run of the Actor started. actorReviewCount: type: integer examples: [69] + description: The number of reviews the Actor has received in Apify Store. actorReviewRating: type: number examples: [4.7] + description: The average rating of the Actor in Apify Store. bookmarkCount: type: integer examples: [1269] + description: The number of users who bookmarked the Actor in Apify Store. publicActorRunStats30Days: type: object - description: Run status counts over the past 30 days. + description: | + Run status counts from the last 30 days. Only for public Actors. + Excludes runs started by the Actor's owner. properties: ABORTED: type: integer examples: [2542] + description: The number of runs that were aborted. FAILED: type: integer examples: [1234] + description: The number of runs that failed. SUCCEEDED: type: integer examples: [732805] + description: The number of runs that succeeded. "TIMED-OUT": type: integer examples: [12556] + description: The number of runs that timed out. TOTAL: type: integer examples: [749137] + description: The total number of runs. diff --git a/apify-api/openapi/components/tags.yaml b/apify-api/openapi/components/tags.yaml index 6de3451ca5..f18ef179d4 100644 --- a/apify-api/openapi/components/tags.yaml +++ b/apify-api/openapi/components/tags.yaml @@ -8,11 +8,13 @@ - "#/reference/actors/actor-object" - "#tag/ActorsActor-object" description: | - The API endpoints in this section allow you to manage Apify Actors. For more details about Actors, refer to the [Actor documentation](https://docs.apify.com/platform/actors). + The API endpoints in this section allow you to manage [Apify Actors](https://docs.apify.com/platform/actors). - For API endpoints that require the `actorId` parameter to identify an Actor, you can provide either: - - The Actor ID (e.g., `HG7ML7M8z78YcAPEB`), or - - A tilde-separated combination of the Actor owner's username and the Actor name (e.g., `janedoe~my-actor`). + ## Indentify an Actor + + For API endpoints that require the `actorId` parameter, provide one of the following: + - The Actor ID. It's part of the Actor's URL in Apify Console: `https://console.apify.com/actors/`. For example, `reGe1ST3OBgYZSsZJ`. + - The username of the Actor owner plus the Actor name, separated by a tilde (`~`). For example, `apify~instagram-scraper`. - name: Actors/Actor versions x-displayName: Actor versions diff --git a/apify-api/openapi/paths/actors/acts@{actorId}.yaml b/apify-api/openapi/paths/actors/acts@{actorId}.yaml index 94c7803069..9e8be28120 100644 --- a/apify-api/openapi/paths/actors/acts@{actorId}.yaml +++ b/apify-api/openapi/paths/actors/acts@{actorId}.yaml @@ -2,7 +2,7 @@ get: tags: - Actors summary: Get Actor - description: Gets an object that contains all the details about a specific Actor. + description: Gets an object that contains all the details about the Actor with the specified ID. operationId: actor_get parameters: - $ref: "../../components/parameters/runAndBuildParameters.yaml#/actorId" @@ -18,9 +18,9 @@ get: data: id: zdc3Pyhyz3m8vjDeM userId: wRsJZtadYvn4mBZmm - name: MyActor + name: instagram-scraper username: jane35 - description: My favourite Actor! + description: Extract data from Instagram. isPublic: false createdAt: "2019-07-08T11:27:57.401Z" modifiedAt: "2019-07-08T14:01:05.546Z" @@ -68,7 +68,7 @@ get: contentType: application/json; charset=utf-8 isDeprecated: false deploymentKey: ssh-rsa AAAA ... - title: My Actor + title: Instagram Scraper taggedBuilds: latest: buildId: z2EryhbfhgSyqj6Hn From 231113ddecc6907c36c15ca31a6eb2652bc38720 Mon Sep 17 00:00:00 2001 From: szaganek Date: Mon, 3 Aug 2026 09:42:31 +0200 Subject: [PATCH 2/4] fix spelling --- apify-api/openapi/components/tags.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apify-api/openapi/components/tags.yaml b/apify-api/openapi/components/tags.yaml index f18ef179d4..a3da5d5718 100644 --- a/apify-api/openapi/components/tags.yaml +++ b/apify-api/openapi/components/tags.yaml @@ -10,7 +10,7 @@ description: | The API endpoints in this section allow you to manage [Apify Actors](https://docs.apify.com/platform/actors). - ## Indentify an Actor + ## Identify an Actor For API endpoints that require the `actorId` parameter, provide one of the following: - The Actor ID. It's part of the Actor's URL in Apify Console: `https://console.apify.com/actors/`. For example, `reGe1ST3OBgYZSsZJ`. From 6cbaecd244f12da46e10c36167e80365d07ffdb5 Mon Sep 17 00:00:00 2001 From: szaganek Date: Mon, 3 Aug 2026 12:46:35 +0200 Subject: [PATCH 3/4] extract an reuse ActorNotice --- apify-api/openapi/components/schemas/actors/Actor.yaml | 7 +------ .../openapi/components/schemas/actors/ActorNotice.yaml | 9 +++++++++ .../openapi/components/schemas/store/StoreListActor.yaml | 2 +- 3 files changed, 11 insertions(+), 7 deletions(-) create mode 100644 apify-api/openapi/components/schemas/actors/ActorNotice.yaml diff --git a/apify-api/openapi/components/schemas/actors/Actor.yaml b/apify-api/openapi/components/schemas/actors/Actor.yaml index 5fba308704..e183606852 100644 --- a/apify-api/openapi/components/schemas/actors/Actor.yaml +++ b/apify-api/openapi/components/schemas/actors/Actor.yaml @@ -114,12 +114,7 @@ properties: URL for sending requests to the Actor in Standby mode. `null` if the Standby mode isn't enabled. notice: - type: [string, "null"] - enum: [NONE, RESIDENTIAL_PROXY_REQUIRED, UNDER_MAINTENANCE] - default: NONE - examples: [NONE] - description: A warning displayed on the Actor's page in Apify Store and Console. - Can be set by the Actor's developer or automatically by Apify's quality checks. + $ref: ./ActorNotice.yaml categories: type: array items: diff --git a/apify-api/openapi/components/schemas/actors/ActorNotice.yaml b/apify-api/openapi/components/schemas/actors/ActorNotice.yaml new file mode 100644 index 0000000000..5966379f0c --- /dev/null +++ b/apify-api/openapi/components/schemas/actors/ActorNotice.yaml @@ -0,0 +1,9 @@ +title: ActorNotice +type: [string, "null"] +description: A warning displayed on the Actor's page in Apify Store and Console. + Can be set by the Actor's developer or automatically by Apify's quality checks. +enum: + - NONE + - RESIDENTIAL_PROXY_REQUIRED + - UNDER_MAINTENANCE +examples: [UNDER_MAINTENANCE] diff --git a/apify-api/openapi/components/schemas/store/StoreListActor.yaml b/apify-api/openapi/components/schemas/store/StoreListActor.yaml index f988b492b5..4164e3e5bc 100644 --- a/apify-api/openapi/components/schemas/store/StoreListActor.yaml +++ b/apify-api/openapi/components/schemas/store/StoreListActor.yaml @@ -33,7 +33,7 @@ properties: - MARKETING - LEAD_GENERATION notice: - type: [string, "null"] + $ref: ../actors/ActorNotice.yaml pictureUrl: type: [string, "null"] format: uri From 5cce38c9e651352610dd0d9c31d2d1ffc3a1daf9 Mon Sep 17 00:00:00 2001 From: szaganek Date: Mon, 3 Aug 2026 12:54:43 +0200 Subject: [PATCH 4/4] indicate ISO format --- apify-api/openapi/components/schemas/actors/Actor.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apify-api/openapi/components/schemas/actors/Actor.yaml b/apify-api/openapi/components/schemas/actors/Actor.yaml index e183606852..8adc3624f4 100644 --- a/apify-api/openapi/components/schemas/actors/Actor.yaml +++ b/apify-api/openapi/components/schemas/actors/Actor.yaml @@ -46,12 +46,12 @@ properties: type: string format: date-time examples: ["2019-07-08T11:27:57.401Z"] - description: The date and time the Actor was created. + description: The date and time the Actor was created. Follows the ISO 8601 format. modifiedAt: type: string format: date-time examples: ["2019-07-08T14:01:05.546Z"] - description: The date and time the Actor was last modified. + description: The date and time the Actor was last modified. Follows the ISO 8601 format. stats: $ref: ./ActorStats.yaml versions: