From 23e790461dcb4f4e26d1b544264af758c334427c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Trunk=C3=A1t?= Date: Tue, 12 May 2026 11:06:13 +0200 Subject: [PATCH 01/11] =?UTF-8?q?docs(api):=20rename=20/v2/acts/=20?= =?UTF-8?q?=E2=86=92=20/v2/actors/=20path=20keys=20in=20OpenAPI=20root=20s?= =?UTF-8?q?pec?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirrors apify/apify-core#27780 in the published spec. The server keeps /v2/acts/ working as an undocumented alias, so existing clients are unaffected. This is the first of several commits closing §1 and §12 of the API-inconsistencies audit. https://claude.ai/code/session_015MYkSfTz4CsX3Y4LatpSGf --- apify-api/openapi/openapi.yaml | 77 +++++++++++++++++----------------- 1 file changed, 39 insertions(+), 38 deletions(-) diff --git a/apify-api/openapi/openapi.yaml b/apify-api/openapi/openapi.yaml index 54e44f9e9b..2e6833b8dc 100644 --- a/apify-api/openapi/openapi.yaml +++ b/apify-api/openapi/openapi.yaml @@ -67,7 +67,7 @@ info: Actor ID code (e.g. `vKg4IjxZbEYTYeW8T`) or its name (e.g. `janedoe~my-actor`): - `https://api.apify.com/v2/acts/[actor_id]/runs` + `https://api.apify.com/v2/actors/[actor_id]/runs` 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). @@ -480,79 +480,79 @@ servers: - url: "https://api.apify.com" variables: {} paths: - /v2/acts: + /v2/actors: $ref: paths/actors/acts.yaml - "/v2/acts/{actorId}": + "/v2/actors/{actorId}": $ref: "paths/actors/acts@{actorId}.yaml" - "/v2/acts/{actorId}/versions": + "/v2/actors/{actorId}/versions": $ref: "paths/actors/acts@{actorId}@versions.yaml" - "/v2/acts/{actorId}/versions/{versionNumber}": + "/v2/actors/{actorId}/versions/{versionNumber}": $ref: "paths/actors/acts@{actorId}@versions@{versionNumber}.yaml" - "/v2/acts/{actorId}/versions/{versionNumber}/env-vars": + "/v2/actors/{actorId}/versions/{versionNumber}/env-vars": $ref: "paths/actors/acts@{actorId}@versions@{versionNumber}@env-vars.yaml" - "/v2/acts/{actorId}/versions/{versionNumber}/env-vars/{envVarName}": + "/v2/actors/{actorId}/versions/{versionNumber}/env-vars/{envVarName}": $ref: "paths/actors/acts@{actorId}@versions@{versionNumber}@env-vars@{envVarName}.yaml" - "/v2/acts/{actorId}/webhooks": + "/v2/actors/{actorId}/webhooks": $ref: "paths/actors/acts@{actorId}@webhooks.yaml" - "/v2/acts/{actorId}/builds": + "/v2/actors/{actorId}/builds": $ref: "paths/actors/acts@{actorId}@builds.yaml" - "/v2/acts/{actorId}/builds/default": + "/v2/actors/{actorId}/builds/default": $ref: "paths/actors/acts@{actorId}@builds@default.yaml" - "/v2/acts/{actorId}/builds/{buildId}/openapi.json": + "/v2/actors/{actorId}/builds/{buildId}/openapi.json": $ref: "paths/actors/acts@{actorId}@builds@{buildId}@openapi.json.yaml" - "/v2/acts/{actorId}/builds/{buildId}": + "/v2/actors/{actorId}/builds/{buildId}": $ref: "paths/actors/acts@{actorId}@builds@{buildId}.yaml" - "/v2/acts/{actorId}/builds/{buildId}/abort": + "/v2/actors/{actorId}/builds/{buildId}/abort": $ref: "paths/actors/acts@{actorId}@builds@{buildId}@abort.yaml" - "/v2/acts/{actorId}/runs": + "/v2/actors/{actorId}/runs": $ref: "paths/actors/acts@{actorId}@runs.yaml" - "/v2/acts/{actorId}/run-sync": + "/v2/actors/{actorId}/run-sync": $ref: "paths/actors/acts@{actorId}@run-sync.yaml" - "/v2/acts/{actorId}/run-sync-get-dataset-items": + "/v2/actors/{actorId}/run-sync-get-dataset-items": $ref: "paths/actors/acts@{actorId}@run-sync-get-dataset-items.yaml" - "/v2/acts/{actorId}/validate-input": + "/v2/actors/{actorId}/validate-input": $ref: "paths/actors/acts@{actorId}@validate-input.yaml" - "/v2/acts/{actorId}/runs/{runId}/resurrect": + "/v2/actors/{actorId}/runs/{runId}/resurrect": $ref: "paths/actors/acts@{actorId}@runs@{runId}@resurrect.yaml" - "/v2/acts/{actorId}/runs/last": + "/v2/actors/{actorId}/runs/last": $ref: "paths/actors/acts@{actorId}@runs@last.yaml" - "/v2/acts/{actorId}/runs/last/dataset": + "/v2/actors/{actorId}/runs/last/dataset": $ref: "paths/actors/acts@{actorId}@runs@last@dataset.yaml" - "/v2/acts/{actorId}/runs/last/dataset/items": + "/v2/actors/{actorId}/runs/last/dataset/items": $ref: "paths/actors/acts@{actorId}@runs@last@dataset@items.yaml" - "/v2/acts/{actorId}/runs/last/dataset/statistics": + "/v2/actors/{actorId}/runs/last/dataset/statistics": $ref: "paths/actors/acts@{actorId}@runs@last@dataset@statistics.yaml" - "/v2/acts/{actorId}/runs/last/key-value-store": + "/v2/actors/{actorId}/runs/last/key-value-store": $ref: "paths/actors/acts@{actorId}@runs@last@key-value-store.yaml" - "/v2/acts/{actorId}/runs/last/key-value-store/keys": + "/v2/actors/{actorId}/runs/last/key-value-store/keys": $ref: "paths/actors/acts@{actorId}@runs@last@key-value-store@keys.yaml" - "/v2/acts/{actorId}/runs/last/key-value-store/records": + "/v2/actors/{actorId}/runs/last/key-value-store/records": $ref: "paths/actors/acts@{actorId}@runs@last@key-value-store@records.yaml" - "/v2/acts/{actorId}/runs/last/key-value-store/records/{recordKey}": + "/v2/actors/{actorId}/runs/last/key-value-store/records/{recordKey}": $ref: "paths/actors/acts@{actorId}@runs@last@key-value-store@records@{recordKey}.yaml" - "/v2/acts/{actorId}/runs/last/request-queue": + "/v2/actors/{actorId}/runs/last/request-queue": $ref: "paths/actors/acts@{actorId}@runs@last@request-queue.yaml" - "/v2/acts/{actorId}/runs/last/request-queue/requests": + "/v2/actors/{actorId}/runs/last/request-queue/requests": $ref: "paths/actors/acts@{actorId}@runs@last@request-queue@requests.yaml" - "/v2/acts/{actorId}/runs/last/request-queue/requests/batch": + "/v2/actors/{actorId}/runs/last/request-queue/requests/batch": $ref: "paths/actors/acts@{actorId}@runs@last@request-queue@requests@batch.yaml" - "/v2/acts/{actorId}/runs/last/request-queue/requests/unlock": + "/v2/actors/{actorId}/runs/last/request-queue/requests/unlock": $ref: "paths/actors/acts@{actorId}@runs@last@request-queue@requests@unlock.yaml" - "/v2/acts/{actorId}/runs/last/request-queue/requests/{requestId}": + "/v2/actors/{actorId}/runs/last/request-queue/requests/{requestId}": $ref: "paths/actors/acts@{actorId}@runs@last@request-queue@requests@{requestId}.yaml" - "/v2/acts/{actorId}/runs/last/request-queue/requests/{requestId}/lock": + "/v2/actors/{actorId}/runs/last/request-queue/requests/{requestId}/lock": $ref: "paths/actors/acts@{actorId}@runs@last@request-queue@requests@{requestId}@lock.yaml" - "/v2/acts/{actorId}/runs/last/request-queue/head": + "/v2/actors/{actorId}/runs/last/request-queue/head": $ref: "paths/actors/acts@{actorId}@runs@last@request-queue@head.yaml" - "/v2/acts/{actorId}/runs/last/request-queue/head/lock": + "/v2/actors/{actorId}/runs/last/request-queue/head/lock": $ref: "paths/actors/acts@{actorId}@runs@last@request-queue@head@lock.yaml" - "/v2/acts/{actorId}/runs/last/log": + "/v2/actors/{actorId}/runs/last/log": $ref: "paths/actors/acts@{actorId}@runs@last@log.yaml" - "/v2/acts/{actorId}/runs/{runId}": + "/v2/actors/{actorId}/runs/{runId}": $ref: "paths/actors/acts@{actorId}@runs@{runId}.yaml" - "/v2/acts/{actorId}/runs/{runId}/abort": + "/v2/actors/{actorId}/runs/{runId}/abort": $ref: "paths/actors/acts@{actorId}@runs@{runId}@abort.yaml" - "/v2/acts/{actorId}/runs/{runId}/metamorph": + "/v2/actors/{actorId}/runs/{runId}/metamorph": $ref: "paths/actors/acts@{actorId}@runs@{runId}@metamorph.yaml" /v2/actor-tasks: $ref: paths/actor-tasks/actor-tasks.yaml @@ -741,5 +741,6 @@ security: - apiKey: [] tags: $ref: components/tags.yaml + x-tagGroups: $ref: components/x-tag-groups.yaml From c599c4056ccd052b93d52e57f21f08e7f291069e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Trunk=C3=A1t?= Date: Tue, 12 May 2026 11:08:12 +0200 Subject: [PATCH 02/11] docs(api): update inline /v2/acts/ example URLs in actors path YAMLs Flips the inline example URLs (Location headers, prose like "`/v2/acts/{actorId}/runs/last`") inside the actors/* path YAML files to /v2/actors/ for consistency with the spec's new path keys. https://claude.ai/code/session_015MYkSfTz4CsX3Y4LatpSGf --- apify-api/openapi/paths/actors/acts.yaml | 2 +- apify-api/openapi/paths/actors/acts@{actorId}@builds.yaml | 2 +- apify-api/openapi/paths/actors/acts@{actorId}@runs.yaml | 2 +- apify-api/openapi/paths/actors/acts@{actorId}@runs@last.yaml | 2 +- apify-api/openapi/paths/actors/acts@{actorId}@versions.yaml | 2 +- .../acts@{actorId}@versions@{versionNumber}@env-vars.yaml | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/apify-api/openapi/paths/actors/acts.yaml b/apify-api/openapi/paths/actors/acts.yaml index 19ad3f7fa9..da7ad1249b 100644 --- a/apify-api/openapi/paths/actors/acts.yaml +++ b/apify-api/openapi/paths/actors/acts.yaml @@ -152,7 +152,7 @@ post: text/plain: schema: type: string - example: https://api.apify.com/v2/acts/zdc3Pyhyz3m8vjDeM + example: https://api.apify.com/v2/actors/zdc3Pyhyz3m8vjDeM content: application/json: schema: diff --git a/apify-api/openapi/paths/actors/acts@{actorId}@builds.yaml b/apify-api/openapi/paths/actors/acts@{actorId}@builds.yaml index 5a54607a31..6529f0df7d 100644 --- a/apify-api/openapi/paths/actors/acts@{actorId}@builds.yaml +++ b/apify-api/openapi/paths/actors/acts@{actorId}@builds.yaml @@ -111,7 +111,7 @@ post: schema: type: string example: >- - https://api.apify.com/v2/acts/zdc3Pyhyz3m8vjDeM/runs/HG7ML7M8z78YcAPEB + https://api.apify.com/v2/actors/zdc3Pyhyz3m8vjDeM/runs/HG7ML7M8z78YcAPEB content: application/json: schema: diff --git a/apify-api/openapi/paths/actors/acts@{actorId}@runs.yaml b/apify-api/openapi/paths/actors/acts@{actorId}@runs.yaml index 5e8578d773..ea63847dab 100644 --- a/apify-api/openapi/paths/actors/acts@{actorId}@runs.yaml +++ b/apify-api/openapi/paths/actors/acts@{actorId}@runs.yaml @@ -130,7 +130,7 @@ post: schema: type: string example: >- - https://api.apify.com/v2/acts/zdc3Pyhyz3m8vjDeM/runs/HG7ML7M8z78YcAPEB + https://api.apify.com/v2/actors/zdc3Pyhyz3m8vjDeM/runs/HG7ML7M8z78YcAPEB content: application/json: schema: diff --git a/apify-api/openapi/paths/actors/acts@{actorId}@runs@last.yaml b/apify-api/openapi/paths/actors/acts@{actorId}@runs@last.yaml index f147a1ce02..ba9c9c3cad 100644 --- a/apify-api/openapi/paths/actors/acts@{actorId}@runs@last.yaml +++ b/apify-api/openapi/paths/actors/acts@{actorId}@runs@last.yaml @@ -9,7 +9,7 @@ get: The base path represents the last Actor run object is: - `/v2/acts/{actorId}/runs/last{?token,status}` + `/v2/actors/{actorId}/runs/last{?token,status}` Using the `status` query parameter you can ensure to only get a run with a certain status (e.g. `status=SUCCEEDED`). The output of this endpoint and other query parameters diff --git a/apify-api/openapi/paths/actors/acts@{actorId}@versions.yaml b/apify-api/openapi/paths/actors/acts@{actorId}@versions.yaml index c25ab792aa..8524e50722 100644 --- a/apify-api/openapi/paths/actors/acts@{actorId}@versions.yaml +++ b/apify-api/openapi/paths/actors/acts@{actorId}@versions.yaml @@ -122,7 +122,7 @@ post: text/plain: schema: type: string - example: https://api.apify.com/v2/acts/zdc3Pyhyz3m8vjDeM/versions/0.0 + example: https://api.apify.com/v2/actors/zdc3Pyhyz3m8vjDeM/versions/0.0 content: application/json: schema: diff --git a/apify-api/openapi/paths/actors/acts@{actorId}@versions@{versionNumber}@env-vars.yaml b/apify-api/openapi/paths/actors/acts@{actorId}@versions@{versionNumber}@env-vars.yaml index 9742ded5b6..77f95fcc59 100644 --- a/apify-api/openapi/paths/actors/acts@{actorId}@versions@{versionNumber}@env-vars.yaml +++ b/apify-api/openapi/paths/actors/acts@{actorId}@versions@{versionNumber}@env-vars.yaml @@ -84,7 +84,7 @@ post: schema: type: string example: >- - https://api.apify.com/v2/acts/zdc3Pyhyz3m8vjDeM/versions/1.0/env-vars/ENV_VAR_NAME + https://api.apify.com/v2/actors/zdc3Pyhyz3m8vjDeM/versions/1.0/env-vars/ENV_VAR_NAME content: application/json: schema: From f17e0d37e25ca0a1067ff8822dd4112b643d0bbc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Trunk=C3=A1t?= Date: Tue, 12 May 2026 11:10:32 +0200 Subject: [PATCH 03/11] =?UTF-8?q?docs(api):=20sweep=20/v2/acts/=20?= =?UTF-8?q?=E2=86=92=20/v2/actors/=20in=20academy=20and=20api=20getting-st?= =?UTF-8?q?arted?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updates user-facing curl/code examples in the academy lessons and the api/getting-started.mdx landing page to use the canonical /v2/actors/ prefix introduced by apify/apify-core#27780. Part of §12 doc-site sweep. https://claude.ai/code/session_015MYkSfTz4CsX3Y4LatpSGf --- .../solutions/integrating_webhooks.md | 4 ++-- .../academy/platform/getting_started/apify_api.md | 6 +++--- .../api/run_actor_and_retrieve_data_via_api.md | 12 ++++++------ .../tutorials/node_js/apify_free_google_serp_api.md | 2 +- sources/api/getting-started.mdx | 4 ++-- 5 files changed, 14 insertions(+), 14 deletions(-) diff --git a/sources/academy/platform/expert_scraping_with_apify/solutions/integrating_webhooks.md b/sources/academy/platform/expert_scraping_with_apify/solutions/integrating_webhooks.md index 4f4bd6bda5..dfde6252f0 100644 --- a/sources/academy/platform/expert_scraping_with_apify/solutions/integrating_webhooks.md +++ b/sources/academy/platform/expert_scraping_with_apify/solutions/integrating_webhooks.md @@ -183,13 +183,13 @@ Success: Actor was deployed to Apify cloud and built there. The URLs tell us that our Actor's ID is `Yk1bieximsduYDydP`. With this `actorId`, and our `token`, which is retrievable through **Settings > API & Integrations** in Apify Console, we can construct a link which will call the Actor: ```text -https://api.apify.com/v2/acts/Yk1bieximsduYDydP/runs?token=YOUR_TOKEN_HERE +https://api.apify.com/v2/actors/Yk1bieximsduYDydP/runs?token=YOUR_TOKEN_HERE ``` We can also use our username and the name of the Actor like this: ```text -https://api.apify.com/v2/acts/USERNAME~filter-actor/runs?token=YOUR_TOKEN_HERE +https://api.apify.com/v2/actors/USERNAME~filter-actor/runs?token=YOUR_TOKEN_HERE ``` Whichever one you choose is totally up to your preference. diff --git a/sources/academy/platform/getting_started/apify_api.md b/sources/academy/platform/getting_started/apify_api.md index 9c719b0fbf..56ceb5cf6c 100644 --- a/sources/academy/platform/getting_started/apify_api.md +++ b/sources/academy/platform/getting_started/apify_api.md @@ -22,7 +22,7 @@ Within one of your Actors on the [Apify Console](https://console.apify.com?asrc= You should see a long list of API endpoints that you can copy and paste elsewhere, or even test right within the **API** modal. Go ahead and copy the endpoint labeled **Run Actor synchronously and get dataset items**. It should look something like this: ```text -https://api.apify.com/v2/acts/YOUR_USERNAME~adding-actor/run-sync?token=YOUR_TOKEN +https://api.apify.com/v2/actors/YOUR_USERNAME~adding-actor/run-sync?token=YOUR_TOKEN ``` :::note Single endpoint @@ -44,7 +44,7 @@ Our **adding-actor** takes in two input values (`num1` and `num2`). When using t Let's say we want to run our **adding-actor** via API and view its results in CSV format at the end. We'll achieve this by passing the **format** parameter with a value of **csv** to change the output format: ```text -https://api.apify.com/v2/acts/YOUR_USERNAME~adding-actor/run-sync-get-dataset-items?token=YOUR_TOKEN_HERE&format=csv +https://api.apify.com/v2/actors/YOUR_USERNAME~adding-actor/run-sync-get-dataset-items?token=YOUR_TOKEN_HERE&format=csv ``` Additional parameters can be passed to this endpoint. You can learn about them in our [API documentation](/api/v2/act-run-sync-get-dataset-items-post) @@ -60,7 +60,7 @@ Network components can record visited URLs, so it's more secure to send the toke If you're not using an HTTP client, you can send the request through your terminal with this command: ```curl -curl -d '{"num1":1, "num2":8}' -H "Content-Type: application/json" -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~adding-actor/run-sync-get-dataset-items?token=YOUR_TOKEN_HERE&format=csv" +curl -d '{"num1":1, "num2":8}' -H "Content-Type: application/json" -X POST "https://api.apify.com/v2/actors/YOUR_USERNAME~adding-actor/run-sync-get-dataset-items?token=YOUR_TOKEN_HERE&format=csv" ``` Here's the response we got: diff --git a/sources/academy/tutorials/api/run_actor_and_retrieve_data_via_api.md b/sources/academy/tutorials/api/run_actor_and_retrieve_data_via_api.md index bf182d06b6..06ba1119d0 100644 --- a/sources/academy/tutorials/api/run_actor_and_retrieve_data_via_api.md +++ b/sources/academy/tutorials/api/run_actor_and_retrieve_data_via_api.md @@ -42,7 +42,7 @@ To run, or **call**, an Actor/task, you will need a few things: The URL of [POST request](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) to run an Actor looks like this: ```cURL -https://api.apify.com/v2/acts/ACTOR_NAME_OR_ID/runs?token=YOUR_TOKEN +https://api.apify.com/v2/actors/ACTOR_NAME_OR_ID/runs?token=YOUR_TOKEN ``` For tasks, we can switch the path from **acts** to **actor-tasks** and keep the rest the same: @@ -58,7 +58,7 @@ If we send a correct POST request to one of these endpoints, the Actor or task w We can also add settings for the Actor (which will override the default settings) as additional query parameters. For example, if we wanted to change how much memory the Actor's run should be allocated and which build to run, we could add the `memory` and `build` parameters separated by `&`. ```cURL -https://api.apify.com/v2/acts/ACTOR_NAME_OR_ID/runs?token=YOUR_TOKEN&memory=8192&build=beta +https://api.apify.com/v2/actors/ACTOR_NAME_OR_ID/runs?token=YOUR_TOKEN&memory=8192&build=beta ``` This works in almost exactly the same way for both Actors and tasks; however, for tasks, there is no reason to specify a [`build`](/platform/actors/development/builds-and-runs/builds) parameter, as a task already has only one specific Actor build which cannot be changed with query parameters. @@ -74,7 +74,7 @@ Good Actors have reasonable defaults for most input fields, so if you want to ru Via API, let's quickly try to run [Web Scraper](https://apify.com/apify/web-scraper), which is the most popular Actor on Apify Store at the moment. The full input with all possible fields is [pretty long and ugly](https://apify.com/apify/web-scraper?section=example-run), so we will not show it here. Because it has default values for most fields, we can provide a JSON input containing only the fields we'd like to customize. We will send a POST request to the endpoint below and add the JSON as the **body** of the request: ```cURL -https://api.apify.com/v2/acts/apify~web-scraper/runs?token=YOUR_TOKEN +https://api.apify.com/v2/actors/apify~web-scraper/runs?token=YOUR_TOKEN ``` Here is how it looks in [Postman](https://www.postman.com/): @@ -164,7 +164,7 @@ const myToken = ''; // Start apify/google-search-scraper Actor // and pass some queries into the JSON body const response = await got({ - url: `https://api.apify.com/v2/acts/apify~google-search-scraper/run-sync-get-dataset-items?token=${myToken}`, + url: `https://api.apify.com/v2/actors/apify~google-search-scraper/run-sync-get-dataset-items?token=${myToken}`, method: 'POST', json: { queries: 'web scraping\nweb crawling', @@ -209,7 +209,7 @@ There may be cases where we need to run the Actor and go away. But in any kind o This solution is quite similar to the synchronous flow. To make the POST request wait, add the `waitForFinish` parameter. It can have a value from `0` to `60`, which is the maximum time in seconds to wait (the max value for `waitForFinish` is 1 minute). Knowing this, we can extend the example URL like this: ```cURL -https://api.apify.com/v2/acts/apify~web-scraper/runs?token=YOUR_TOKEN&waitForFinish=60 +https://api.apify.com/v2/actors/apify~web-scraper/runs?token=YOUR_TOKEN&waitForFinish=60 ``` You can also use the `waitForFinish` parameter with the [**GET Run** endpoint](/api/v2/actor-run-get) to implement a smarter [polling](#polling) system. @@ -239,7 +239,7 @@ When we run the Actor with the [usual API call](#run-an-actor-or-task) shown abo Replace the `RUN_ID` in the following URL with the ID you extracted earlier: ```cURL -https://api.apify.com/v2/acts/ACTOR_NAME_OR_ID/runs/RUN_ID +https://api.apify.com/v2/actors/ACTOR_NAME_OR_ID/runs/RUN_ID ``` Once a status of `SUCCEEDED` or `FAILED` has been received, we know the run has finished and can cancel the interval and finally [collect the data](#collect-the-data). diff --git a/sources/academy/tutorials/node_js/apify_free_google_serp_api.md b/sources/academy/tutorials/node_js/apify_free_google_serp_api.md index ac643b365b..ceafc6177a 100644 --- a/sources/academy/tutorials/node_js/apify_free_google_serp_api.md +++ b/sources/academy/tutorials/node_js/apify_free_google_serp_api.md @@ -12,6 +12,6 @@ You need to regularly grab SERP data about your target keywords? Apify provides Hit `Save & Run` and you'll have the downloaded data as soon as the query finishes. To have it run at a regular frequency, you can set up the task to run on an [automatic schedule](/platform/schedules#setting-up-a-new-schedule). -To run from the API, send a [synchronous POST request](/api/v2/actor-task-run-sync-get-dataset-items-post) to an endpoint such as `https://api.apify.com/v2/acts/TASK_NAME_OR_ID/runs?token=YOUR_TOKEN`. Include any required input in a JSON object in the request's body. +To run from the API, send a [synchronous POST request](/api/v2/actor-task-run-sync-get-dataset-items-post) to an endpoint such as `https://api.apify.com/v2/actors/TASK_NAME_OR_ID/runs?token=YOUR_TOKEN`. Include any required input in a JSON object in the request's body. Keep in mind that, as Google search uses a non-deterministic algorithm, output results may vary even if the input settings are exactly the same. diff --git a/sources/api/getting-started.mdx b/sources/api/getting-started.mdx index 8005a1a6ca..62d4dd9dc0 100644 --- a/sources/api/getting-started.mdx +++ b/sources/api/getting-started.mdx @@ -65,7 +65,7 @@ The most common workflow involving Apify API consists of the following steps: For shorter runs where you need immediate results: ```http title="Endpoint" -POST https://api.apify.com/v2/acts/:actorId/run-sync +POST https://api.apify.com/v2/actors/:actorId/run-sync ``` Expected response codes: @@ -79,7 +79,7 @@ Expected response codes: For longer-running operations or when you don't need immediate results. ```http title="Endpoint" -POST https://api.apify.com/v2/acts/:actorId/runs +POST https://api.apify.com/v2/actors/:actorId/runs ``` Expected response codes: From 4c5dad09c13361d86cfca2e42aaecbe1da6119fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Trunk=C3=A1t?= Date: Tue, 12 May 2026 11:12:50 +0200 Subject: [PATCH 04/11] =?UTF-8?q?docs(api):=20sweep=20/v2/acts/=20?= =?UTF-8?q?=E2=86=92=20/v2/actors/=20in=20platform/integrations=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updates user-facing API URLs in deployment CI, permissions migration, running, integrating-via-API, Skyfire, x402, and ad-hoc-webhooks docs. Part of §12 doc-site sweep mirroring apify/apify-core#27780. https://claude.ai/code/session_015MYkSfTz4CsX3Y4LatpSGf --- .../actors/development/deployment/continuous_integration.md | 4 ++-- .../actors/development/permissions/migration_guide.md | 2 +- sources/platform/actors/running/index.md | 2 +- .../integrations/actors/integrating_actors_via_api.md | 2 +- sources/platform/integrations/ai/skyfire.md | 2 +- sources/platform/integrations/ai/x402.md | 4 ++-- .../integrations/programming/webhooks/ad_hoc_webhooks.md | 2 +- 7 files changed, 9 insertions(+), 9 deletions(-) diff --git a/sources/platform/actors/development/deployment/continuous_integration.md b/sources/platform/actors/development/deployment/continuous_integration.md index 7bf0995881..3c3775e0cf 100644 --- a/sources/platform/actors/development/deployment/continuous_integration.md +++ b/sources/platform/actors/development/deployment/continuous_integration.md @@ -38,7 +38,7 @@ Choose the method that best fits your workflow. 1. Go to your Actor's detail page in Apify Console, click on the API tab in the top right, then select API Endpoints. Copy the **Build Actor** API endpoint URL. The format is as follows: ```cURL - https://api.apify.com/v2/acts/YOUR-ACTOR-NAME/builds?token=YOUR-TOKEN-HERE&version=0.0&tag=beta&waitForFinish=60 + https://api.apify.com/v2/actors/YOUR-ACTOR-NAME/builds?token=YOUR-TOKEN-HERE&version=0.0&tag=beta&waitForFinish=60 ``` :::note API token @@ -78,7 +78,7 @@ Now your Actor will automatically rebuild on every push to the GitHub repository ::: ```cURL - https://api.apify.com/v2/acts/YOUR-ACTOR-NAME/builds?token=YOUR-TOKEN-HERE&version=0.0&tag=latest&waitForFinish=60 + https://api.apify.com/v2/actors/YOUR-ACTOR-NAME/builds?token=YOUR-TOKEN-HERE&version=0.0&tag=latest&waitForFinish=60 ``` 1. Name the secret & paste in your API endpoint diff --git a/sources/platform/actors/development/permissions/migration_guide.md b/sources/platform/actors/development/permissions/migration_guide.md index 524ac6c857..313063cf2e 100644 --- a/sources/platform/actors/development/permissions/migration_guide.md +++ b/sources/platform/actors/development/permissions/migration_guide.md @@ -39,7 +39,7 @@ await apifyClient.actor(actorId).call(input, { Or using the API: ```tsx - POST https://api.apify.com/v2/acts//runs?forcePermissionLevel=LIMITED_PERMISSIONS + POST https://api.apify.com/v2/actors//runs?forcePermissionLevel=LIMITED_PERMISSIONS ``` ## Common migration paths diff --git a/sources/platform/actors/running/index.md b/sources/platform/actors/running/index.md index e3f19b2626..f5eea28382 100644 --- a/sources/platform/actors/running/index.md +++ b/sources/platform/actors/running/index.md @@ -62,7 +62,7 @@ Now you can go back to the **Input** tab and try again with different settings, To invoke Actors with the Apify API, send an HTTP POST request to the [Run Actor](/api/v2/act-runs-post) endpoint. For example: ```text -https://api.apify.com/v2/acts/compass~crawler-google-places/runs?token= +https://api.apify.com/v2/actors/compass~crawler-google-places/runs?token= ``` An Actor's input and its content type can be passed as a payload of the POST request, and additional options can be specified using URL query parameters. To learn more, see [Run an Actor and retrieve data via API](/academy/api/run-actor-and-retrieve-data-via-api). diff --git a/sources/platform/integrations/actors/integrating_actors_via_api.md b/sources/platform/integrations/actors/integrating_actors_via_api.md index 6d3afb988b..6cf77bec4b 100644 --- a/sources/platform/integrations/actors/integrating_actors_via_api.md +++ b/sources/platform/integrations/actors/integrating_actors_via_api.md @@ -25,7 +25,7 @@ The webhook should look something like this: ```json5 { - "requestUrl": "https://api.apify.com/v2/acts//runs", + "requestUrl": "https://api.apify.com/v2/actors//runs", "eventTypes": ["ACTOR.RUN.SUCCEEDED"], "condition": { "actorId": "", diff --git a/sources/platform/integrations/ai/skyfire.md b/sources/platform/integrations/ai/skyfire.md index 606f1590a6..5d41186e35 100644 --- a/sources/platform/integrations/ai/skyfire.md +++ b/sources/platform/integrations/ai/skyfire.md @@ -163,7 +163,7 @@ Make a standard Actor run request to the [run Actor endpoint](https://docs.apify ```bash title="Example of using the synchronous run endpoint" curl -X POST \ - 'https://api.apify.com/v2/acts/ACTOR_ID/run-sync' \ + 'https://api.apify.com/v2/actors/ACTOR_ID/run-sync' \ -H 'skyfire-pay-id: YOUR_SKYFIRE_PAY_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ diff --git a/sources/platform/integrations/ai/x402.md b/sources/platform/integrations/ai/x402.md index bf3b06c31b..40b51266cb 100644 --- a/sources/platform/integrations/ai/x402.md +++ b/sources/platform/integrations/ai/x402.md @@ -93,7 +93,7 @@ When using the API, replace the `/` in the Actor name with `~` (for example, `ap # Step 1: Discover payment requirements curl -si \ -H "X-APIFY-PAYMENT-PROTOCOL: X402" \ - "https://api.apify.com/v2/acts/apify~instagram-post-scraper/run-sync-get-dataset-items" + "https://api.apify.com/v2/actors/apify~instagram-post-scraper/run-sync-get-dataset-items" # → HTTP 402 + PAYMENT-REQUIRED header value # Step 2: Sign the payment with mcpc @@ -106,7 +106,7 @@ curl -s \ -H "PAYMENT-SIGNATURE: " \ -H "Content-Type: application/json" \ -d '{"username": ["natgeo"], "resultsLimit": 3}' \ - "https://api.apify.com/v2/acts/apify~instagram-post-scraper/run-sync-get-dataset-items" + "https://api.apify.com/v2/actors/apify~instagram-post-scraper/run-sync-get-dataset-items" # → JSON array with the scraped Instagram posts ``` diff --git a/sources/platform/integrations/programming/webhooks/ad_hoc_webhooks.md b/sources/platform/integrations/programming/webhooks/ad_hoc_webhooks.md index 7e2dea158b..ec4842bcdd 100644 --- a/sources/platform/integrations/programming/webhooks/ad_hoc_webhooks.md +++ b/sources/platform/integrations/programming/webhooks/ad_hoc_webhooks.md @@ -15,7 +15,7 @@ import TabItem from '@theme/TabItem'; An ad-hoc webhook is a single-use webhook created for a specific Actor run when starting the run using the [Apify API](/api/v2). The webhook triggers once when the run transitions to the specified state. Define ad-hoc webhooks using the `webhooks` URL parameter added to the API endpoint that starts an Actor or Actor task: ```text -https://api.apify.com/v2/acts/[ACTOR_ID]/runs?token=[YOUR_API_TOKEN]&webhooks=[AD_HOC_WEBHOOKS] +https://api.apify.com/v2/actors/[ACTOR_ID]/runs?token=[YOUR_API_TOKEN]&webhooks=[AD_HOC_WEBHOOKS] ``` replace `AD_HOC_WEBHOOKS` with a base64 encoded stringified JSON array of webhook definitions: From b3e3957cc541eee7df73f3b8b195871affe42508 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Trunk=C3=A1t?= Date: Tue, 12 May 2026 11:13:34 +0200 Subject: [PATCH 05/11] docs(api): flip /v2/acts/ curl example to /v2/actors/ on the api landing page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Last file in the §12 doc-site sweep — the cURL snippet on the /api page header is the most prominent user-facing example in the docs site. https://claude.ai/code/session_015MYkSfTz4CsX3Y4LatpSGf --- src/pages/api/index.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/api/index.tsx b/src/pages/api/index.tsx index 776ebeb4af..b94108602b 100644 --- a/src/pages/api/index.tsx +++ b/src/pages/api/index.tsx @@ -141,7 +141,7 @@ echo '{ "searchStringsArray": ["Apify"] }' | curl -X POST -d @- \\ -H 'Content-Type: application/json' \\ -H 'Authorization: Bearer ' \\ - -L 'https://api.apify.com/v2/acts/compass~crawler-google-places/run-sync-get-dataset-items' + -L 'https://api.apify.com/v2/actors/compass~crawler-google-places/run-sync-get-dataset-items' `} From 7e57634870e654ca02e3d3def9c5690f7a3e4dab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Trunk=C3=A1t?= Date: Tue, 12 May 2026 12:15:12 +0200 Subject: [PATCH 06/11] docs(api): document that legacy /v2/acts/ paths are deprecated but still work Addresses PR review feedback: surface the backward-compatibility status of the legacy /v2/acts/ prefix in the user-facing docs so the change doesn't surprise existing API users. - openapi.yaml: new "Legacy /v2/acts/ URL prefix" subsection in the API introduction, placed right after "Basic usage" so it appears at the top of every reader's tour through the spec. Renders as a deep-link section (#/introduction/legacy-acts-prefix) in the Redocly reference. - sources/api/getting-started.mdx: admonition callout right after the "Run an Actor" endpoints so the legacy prefix's status is on the first page new API users land on. Both call out: same handler, same response, same rate-limit bucket, same usage counter; new code should use /v2/actors/ but old clients (SDKs, persisted webhooks, saved snippets) need no changes. https://claude.ai/code/session_015MYkSfTz4CsX3Y4LatpSGf --- apify-api/openapi/openapi.yaml | 12 +++++++++++- sources/api/getting-started.mdx | 6 ++++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/apify-api/openapi/openapi.yaml b/apify-api/openapi/openapi.yaml index 2e6833b8dc..e710ec0405 100644 --- a/apify-api/openapi/openapi.yaml +++ b/apify-api/openapi/openapi.yaml @@ -111,6 +111,17 @@ info: minutes) for the run to finish and returns its output. If the run takes longer, the request will time out and throw an error. + ## Legacy `/v2/acts/` URL prefix + + + Actor-scoped endpoints previously lived under `/v2/acts/`. That prefix is + **deprecated but continues to work** for backward compatibility — every + `/v2/acts/...` URL routes to the same handler as its `/v2/actors/...` + counterpart, returns the same response, and shares the same rate-limit bucket + and API usage counter. New integrations should use the canonical + `/v2/actors/` prefix, but existing clients (older SDK versions, persisted + webhook `requestUrl`s, saved cURL snippets) keep working without any changes. + ## Response structure @@ -741,6 +752,5 @@ security: - apiKey: [] tags: $ref: components/tags.yaml - x-tagGroups: $ref: components/x-tag-groups.yaml diff --git a/sources/api/getting-started.mdx b/sources/api/getting-started.mdx index 62d4dd9dc0..6e09e16da9 100644 --- a/sources/api/getting-started.mdx +++ b/sources/api/getting-started.mdx @@ -86,6 +86,12 @@ Expected response codes: * `201` +:::note Legacy `/v2/acts/` paths + +Actor-scoped endpoints previously lived under `/v2/acts/`. That prefix is **deprecated but continues to work** — `/v2/acts/...` routes to the same handler as `/v2/actors/...`, returns the same response, and shares the same rate-limit bucket. New integrations should use the canonical `/v2/actors/` prefix, but existing clients (older SDK versions, persisted webhook URLs, saved cURL snippets) keep working without any changes. + +::: + ### 2. Retrieve results #### From a Dataset From fe4d278901b9bfdf3773a2a6c40a78a6952254f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Trunk=C3=A1t?= Date: Tue, 12 May 2026 12:19:09 +0200 Subject: [PATCH 07/11] Update getting-started.mdx --- sources/api/getting-started.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/sources/api/getting-started.mdx b/sources/api/getting-started.mdx index 6e09e16da9..c60464964c 100644 --- a/sources/api/getting-started.mdx +++ b/sources/api/getting-started.mdx @@ -86,10 +86,6 @@ Expected response codes: * `201` -:::note Legacy `/v2/acts/` paths - -Actor-scoped endpoints previously lived under `/v2/acts/`. That prefix is **deprecated but continues to work** — `/v2/acts/...` routes to the same handler as `/v2/actors/...`, returns the same response, and shares the same rate-limit bucket. New integrations should use the canonical `/v2/actors/` prefix, but existing clients (older SDK versions, persisted webhook URLs, saved cURL snippets) keep working without any changes. - ::: ### 2. Retrieve results From 35f7be08605f16d803f84fd8591e625b4f37e03b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Trunk=C3=A1t?= Date: Wed, 13 May 2026 13:52:51 +0200 Subject: [PATCH 08/11] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- apify-api/openapi/openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apify-api/openapi/openapi.yaml b/apify-api/openapi/openapi.yaml index e710ec0405..f0638704c1 100644 --- a/apify-api/openapi/openapi.yaml +++ b/apify-api/openapi/openapi.yaml @@ -115,7 +115,7 @@ info: Actor-scoped endpoints previously lived under `/v2/acts/`. That prefix is - **deprecated but continues to work** for backward compatibility — every + **deprecated but continues to work** for backward compatibility - every `/v2/acts/...` URL routes to the same handler as its `/v2/actors/...` counterpart, returns the same response, and shares the same rate-limit bucket and API usage counter. New integrations should use the canonical From 41aeeb7fb2776addba9c51a1635ce12cdb703ec1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Trunk=C3=A1t?= Date: Wed, 13 May 2026 13:54:07 +0200 Subject: [PATCH 09/11] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- sources/api/getting-started.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/sources/api/getting-started.mdx b/sources/api/getting-started.mdx index c60464964c..62d4dd9dc0 100644 --- a/sources/api/getting-started.mdx +++ b/sources/api/getting-started.mdx @@ -86,8 +86,6 @@ Expected response codes: * `201` -::: - ### 2. Retrieve results #### From a Dataset From a309bf5720fb77c41c02d7630ef78ee0b39a9fcf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Trunk=C3=A1t?= Date: Fri, 15 May 2026 10:15:37 +0200 Subject: [PATCH 10/11] Update openapi.yaml --- apify-api/openapi/openapi.yaml | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/apify-api/openapi/openapi.yaml b/apify-api/openapi/openapi.yaml index f0638704c1..b26536b9cb 100644 --- a/apify-api/openapi/openapi.yaml +++ b/apify-api/openapi/openapi.yaml @@ -114,13 +114,9 @@ info: ## Legacy `/v2/acts/` URL prefix - Actor-scoped endpoints previously lived under `/v2/acts/`. That prefix is - **deprecated but continues to work** for backward compatibility - every - `/v2/acts/...` URL routes to the same handler as its `/v2/actors/...` - counterpart, returns the same response, and shares the same rate-limit bucket - and API usage counter. New integrations should use the canonical - `/v2/actors/` prefix, but existing clients (older SDK versions, persisted - webhook `requestUrl`s, saved cURL snippets) keep working without any changes. + Older Actor endpoints use the /v2/acts/ URL prefix. This prefix is deprecated + but backward compatible. In new integrations, use /v2/actors/. + Existing URLs and clients don't require changes. ## Response structure From 2898e1b0a9e165000b7277df3b4217e638333b0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Trunk=C3=A1t?= Date: Fri, 15 May 2026 10:19:08 +0200 Subject: [PATCH 11/11] Update openapi.yaml --- apify-api/openapi/openapi.yaml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/apify-api/openapi/openapi.yaml b/apify-api/openapi/openapi.yaml index b26536b9cb..f6e1151717 100644 --- a/apify-api/openapi/openapi.yaml +++ b/apify-api/openapi/openapi.yaml @@ -114,9 +114,10 @@ info: ## Legacy `/v2/acts/` URL prefix - Older Actor endpoints use the /v2/acts/ URL prefix. This prefix is deprecated - but backward compatible. In new integrations, use /v2/actors/. - Existing URLs and clients don't require changes. + The `/v2/acts/` prefix is deprecated but still fully functional, and + such endpoint routes to the same handler as its `/v2/actors/...` counterpart. + New integrations should use the canonical /v2/actors/ prefix, + but existing clients keep working without changes. ## Response structure