From 25d69f3d5cd14f84321b49df4046db264fcd3c71 Mon Sep 17 00:00:00 2001 From: szaganek Date: Fri, 3 Jul 2026 13:59:21 +0200 Subject: [PATCH] docs(openapi): Add missing descriptions to Update Actor endpoint --- .../components/schemas/actors/BuildTag.yaml | 2 + .../actors/CreateOrUpdateVersionRequest.yaml | 22 ++++-- .../schemas/actors/UpdateActorRequest.yaml | 73 +++++++------------ .../openapi/paths/actors/acts@{actorId}.yaml | 73 ++++++++++++++----- 4 files changed, 100 insertions(+), 70 deletions(-) diff --git a/apify-api/openapi/components/schemas/actors/BuildTag.yaml b/apify-api/openapi/components/schemas/actors/BuildTag.yaml index a5cd6134fa..94f88327fc 100644 --- a/apify-api/openapi/components/schemas/actors/BuildTag.yaml +++ b/apify-api/openapi/components/schemas/actors/BuildTag.yaml @@ -1,7 +1,9 @@ title: BuildTag type: [object, "null"] +description: The name of the build tag. required: - buildId properties: buildId: type: string + description: The ID of the build to assign to the tag. diff --git a/apify-api/openapi/components/schemas/actors/CreateOrUpdateVersionRequest.yaml b/apify-api/openapi/components/schemas/actors/CreateOrUpdateVersionRequest.yaml index 9c150a254e..8202cb8e90 100644 --- a/apify-api/openapi/components/schemas/actors/CreateOrUpdateVersionRequest.yaml +++ b/apify-api/openapi/components/schemas/actors/CreateOrUpdateVersionRequest.yaml @@ -5,29 +5,37 @@ properties: type: [string, "null"] pattern: ^([0-9]|[1-9][0-9])\.([0-9]|[1-9][0-9])$ examples: ["0.0"] + description: The version number of the Actor. Must be a dot-separated sequence of numbers. sourceType: anyOf: - $ref: ./VersionSourceType.yaml - type: "null" + description: Where the source code of the version lives. envVars: - type: [array, "null"] - items: - $ref: ./EnvVarRequest.yaml - description: "" + anyOf: + - type: array + items: + $ref: ./EnvVar.yaml + - type: "null" + description: Environment variables for the version. applyEnvVarsToBuild: type: [boolean, "null"] examples: [false] + description: Whether to inject the environment variables at build time. buildTag: type: [string, "null"] examples: [latest] + description: The tag name to apply to a successful build of this version. Can be `null` when the version has no build tag. sourceFiles: $ref: ./VersionSourceFiles.yaml + description: Applies when the `sourceType` is `SOURCE_FILES`. Represents the Actor's + file structure as an array of files and folders. gitRepoUrl: type: [string, "null"] - description: URL of the Git repository when sourceType is GIT_REPO. + description: URL of the Git repository to clone the source code from. Applies when the `sourceType` is `GIT_REPO`. tarballUrl: type: [string, "null"] - description: URL of the tarball when sourceType is TARBALL. + description: URL of the tarball to download the source code from. Applies when the `sourceType` is `TARBALL`. gitHubGistUrl: type: [string, "null"] - description: URL of the GitHub Gist when sourceType is GITHUB_GIST. + description: URL of the GitHub Gist to clone the source code from. Applies when the `sourceType` is `GITHUB_GIST`. diff --git a/apify-api/openapi/components/schemas/actors/UpdateActorRequest.yaml b/apify-api/openapi/components/schemas/actors/UpdateActorRequest.yaml index fe7ef33ff6..c0f7328803 100644 --- a/apify-api/openapi/components/schemas/actors/UpdateActorRequest.yaml +++ b/apify-api/openapi/components/schemas/actors/UpdateActorRequest.yaml @@ -3,26 +3,38 @@ type: object properties: name: type: string - examples: [MyActor] + examples: [instagram-scraper] + description: The identifier of the Actor. Use lowercase letters, numbers, and hyphens. + Spaces or special characters aren't allowed. Must be unique across your account. description: type: [string, "null"] - examples: [My favourite actor!] + examples: [This scraper extracts posts and comments from Instagram.] + description: Short description of the Actor, displayed in Apify Store and Console. isPublic: type: boolean examples: [false] + description: Whether the Actor is available to users in Apify Store. If `false`, the Actor is private + and only visible to you. actorPermissionLevel: anyOf: - $ref: ./ActorPermissionLevel.yaml - type: "null" seoTitle: type: [string, "null"] - examples: [My actor] + examples: [Free Instagram 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. Recommended length is 40-50 characters. seoDescription: type: [string, "null"] - examples: [My actor is the best] + examples: [The best scraper for Instagram] + description: Description of the Actor to display by search engines such as Google. + Recommended length is 140-156 characters. title: type: [string, "null"] - examples: [My Actor] + examples: [Instagram scraper] + description: Human-readable name of the Actor, displayed in Apify Store and Console. + Can contain spaces and capital letters. Recommended length is 40-50 characters. + You can change this title without affecting the Actor's URL or SEO. restartOnError: type: boolean examples: [false] @@ -31,61 +43,26 @@ properties: type: array items: $ref: ./CreateOrUpdateVersionRequest.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: $ref: ../actor-pricing-info/ActorRunPricingInfo.yaml categories: type: [array, "null"] + examples: [["SOCIAL_MEDIA"]] items: type: string - description: "" + description: A list of categories that best define the Actor. Reflected in Apify Store's search and filtering options. defaultRunOptions: anyOf: - $ref: ./DefaultRunOptions.yaml - type: "null" + description: The default settings applied to an Actor run. Can be overridden by the user. taggedBuilds: type: [object, "null"] - description: | - An object to modify tags on the Actor's builds. The key is the tag name (e.g., _latest_), and the value is either an object with a `buildId` or `null`. - - This operation is a patch; any existing tags that you omit from this object will be preserved. - - - **To create or reassign a tag**, provide the tag name with a `buildId`. e.g., to assign the _latest_ tag: - -   - - ```json - { - "latest": { - "buildId": "z2EryhbfhgSyqj6Hn" - } - } - ``` - - - **To remove a tag**, provide the tag name with a `null` value. e.g., to remove the _beta_ tag: - -   - - ```json - { - "beta": null - } - ``` - - - **To perform multiple operations**, combine them. The following reassigns _latest_ and removes _beta_, while preserving any other existing tags. - -   - - ```json - { - "latest": { - "buildId": "z2EryhbfhgSyqj6Hn" - }, - "beta": null - } - ``` + description: A dictionary that maps tag names to specific builds. For details, see [Update build tags](#update-build-tags). additionalProperties: $ref: ./BuildTag.yaml example: @@ -96,9 +73,13 @@ properties: anyOf: - $ref: ./ActorStandby.yaml - type: "null" + description: The configuration of the Actor's standby mode. For details, see [Standby mode](https://docs.apify.com/platform/actors/development/programming-interface/standby). exampleRunInput: anyOf: - $ref: ./ExampleRunInput.yaml - type: "null" + description: Sample input payload that demonstrates what a typical run input for an Actor + looks like. Used when no explicit input for a run is provided. isDeprecated: type: [boolean, "null"] + description: Whether the Actor is deprecated. diff --git a/apify-api/openapi/paths/actors/acts@{actorId}.yaml b/apify-api/openapi/paths/actors/acts@{actorId}.yaml index 0aa034385f..3b038be178 100644 --- a/apify-api/openapi/paths/actors/acts@{actorId}.yaml +++ b/apify-api/openapi/paths/actors/acts@{actorId}.yaml @@ -102,26 +102,65 @@ put: - Actors summary: Update Actor description: | - Updates settings of an Actor using values specified by an Actor object - passed as JSON in the POST payload. - If the object does not define a specific property, its value will not be - updated. + Updates an Actor's settings with the values specified in an `Actor` object + passed as JSON in the POST payload. Only the fields specified in the request body are updated. - The response is the full Actor object as returned by the - [Get Actor](#/reference/actors/actor-object/get-actor) endpoint. + Returns the full `Actor` object, the same as the + [Get Actor](/api/v2/act-get) endpoint. - The request needs to specify the `Content-Type: application/json` HTTP header! + In the HTTP request, set the `Content-Type` header to `application/json`. - When providing your API authentication token, we recommend using the - request's `Authorization` header, rather than the URL. ([More - info](#/introduction/authentication)). + ### Authentication + + To provide the authentication token, we recommend using the request's + `Authorization` header, rather than the URL. For details, + see [Authentication](/api/v2/getting-started#authentication). + + ### Make an Actor public + + To make your Actor [public](https://docs.apify.com/platform/actors/publishing): + - Set `isPublic` to `true`. + - Provide `title` and `categories`. For reference, see [constants from the `apify-shared-js` + package](https://github.com/apify/apify-shared-js/blob/2d43ebc41ece9ad31cd6525bd523fb86939bf860/packages/consts/src/consts.ts#L452-L471) + + ### Update build tags + + To change tags assigned to Actor builds, use the `taggedBuilds` object. It's a dictionary that maps tag names + to specific builds, where: + - the key is the tag name, for example `latest` or `beta` + - the value is either `null` or an object with a build ID + + Changing tags is a patch operation. Only the tags that you provide in this object are updated. + + Note that you can assign multiple tags to a single build, but you can't assign the same tag to multiple builds. + + - To create or reassign a tag, provide the tag name with a build ID. For example, to assign + the `latest` tag to a build, use: + + ```json + { + "latest": { "buildId": "z2EryhbfhgSyqj6Hn" } + } + ``` + + - To remove a tag from a build, provide the tag name with a `null` value. For example, to remove the `beta` tag, use: + + ```json + { + "beta": null + } + ``` + + - You can perform multiple actions at once. The following example reassigns `latest` + and removes `beta`, while preserving other existing tags: + + ```json + { + "latest": { "buildId": "z2EryhbfhgSyqj6Hn" }, + "beta": null + } + ``` - If you want to make your Actor - [public](https://docs.apify.com/platform/actors/publishing) using `isPublic: - true`, you will need to provide the Actor's `title` and the `categories` - under which that Actor will be classified in Apify Store. For this, it's - best to use the [constants from our `apify-shared-js` - package](https://github.com/apify/apify-shared-js/blob/2d43ebc41ece9ad31cd6525bd523fb86939bf860/packages/consts/src/consts.ts#L452-L471). operationId: act_put parameters: - $ref: "../../components/parameters/runAndBuildParameters.yaml#/actorId" @@ -289,7 +328,7 @@ delete: tags: - Actors summary: Delete Actor - description: Deletes an Actor. + description: Deletes an Actor with the specified ID. operationId: act_delete parameters: - $ref: "../../components/parameters/runAndBuildParameters.yaml#/actorId"