From 60b7eb902d482d2489d5765b7d9cb4accedd9279 Mon Sep 17 00:00:00 2001 From: Marek Honzal Date: Wed, 29 Jul 2026 11:11:18 +0200 Subject: [PATCH 1/4] docs: replace legacy /v2/acts routes with canonical /v2/actors paths Agent-facing docs taught /v2/acts, absent from the public OpenAPI contract. Also fix the operationId convention docs, which documented act_runs_post and would re-seed the drift on the next endpoint. --- .agents/skills/api-doc/references/openapi-patterns.md | 10 +++++++--- CONTRIBUTING.md | 4 +++- ...sions@{versionNumber}@env-vars@{envVarName}put.yaml | 2 +- .../acts@{actorId}@versions@{versionNumber}put.yaml | 2 +- .../api/run_actor_and_retrieve_data_via_api.md | 4 ++-- sources/academy/tutorials/api/using_apify_from_php.md | 8 ++++---- sources/platform/get-started/agent-onboarding.md | 6 +++--- sources/platform/integrations/programming/github.md | 2 +- 8 files changed, 22 insertions(+), 16 deletions(-) diff --git a/.agents/skills/api-doc/references/openapi-patterns.md b/.agents/skills/api-doc/references/openapi-patterns.md index 30817e9903..ca09893c64 100644 --- a/.agents/skills/api-doc/references/openapi-patterns.md +++ b/.agents/skills/api-doc/references/openapi-patterns.md @@ -85,9 +85,13 @@ Rules: | `/request-queues` | GET | `requestQueues_get` | | `/request-queues/{queueId}` | GET | `requestQueue_get` | | `/request-queues/{queueId}` | PUT | `requestQueue_put` | -| `/acts/{actorId}/runs` | POST | `act_runs_post` | -| `/acts/{actorId}/runs` | GET | `act_runs_get` | -| `/acts/{actorId}/runs/{runId}` | GET | `act_run_get` | +| `/actors/{actorId}/runs` | POST | `actors_runs_post` | +| `/actors/{actorId}/runs` | GET | `actors_runs_get` | +| `/actors/{actorId}/runs/{runId}` | GET | `actors_run_get` | + +An Actor's own `/runs` and `/builds` sub-resources keep the plural `actors_` prefix, because the account-wide `/actor-runs` and `/actor-builds` paths already own the singular `actorRun_` and `actorBuild_` prefixes. + +Never use the legacy `/acts` prefix in paths or operation IDs. The canonical prefixes are `/actors`, `/actor-runs`, and `/actor-builds`. ## Code sample examples diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ccdcb69ac4..5787a5d236 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -272,7 +272,9 @@ Examples: - `/requests-queues` GET -> `requestQueues_get` - `/requests-queues/{queueId}` PUT -> `requestQueue_put` -- `/acts/{actorId}/runs` POST -> `act_runs_post` +- `/actors/{actorId}/runs` POST -> `actors_runs_post` + +An Actor's own `/runs` and `/builds` sub-resources keep the plural `actors_` prefix, because the account-wide `/actor-runs` and `/actor-builds` paths already own the singular `actorRun_` and `actorBuild_` prefixes. #### Code samples diff --git a/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}@env-vars@{envVarName}put.yaml b/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}@env-vars@{envVarName}put.yaml index 2d11bc6f66..7d985c1825 100644 --- a/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}@env-vars@{envVarName}put.yaml +++ b/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}@env-vars@{envVarName}put.yaml @@ -90,7 +90,7 @@ post: Updates Actor environment variable using values specified by a [EnvVar object](#/reference/actors/environment-variable-object) passed as JSON in the POST payload. - This endpoint is an alias for the [`PUT` update environment variable](#tag/ActorsEnvironment-variable-object/operation/act_version_envVar_put) method and behaves identically. + This endpoint is an alias for the [`PUT` update environment variable](#tag/ActorsEnvironment-variable-object/operation/actor_version_envVar_put) method and behaves identically. operationId: actor_version_envVar_post x-legacy-doc-urls: - https://docs.apify.com/api/v2#/reference/actors/environment-variable-object/update-environment-variable diff --git a/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}put.yaml b/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}put.yaml index d27decd93e..52a74a8bdd 100644 --- a/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}put.yaml +++ b/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}put.yaml @@ -82,7 +82,7 @@ post: summary: Update version (POST) description: | Updates Actor version using values specified by a [Version object](#/reference/actors/version-object) passed as JSON in the POST payload. - This endpoint is an alias for the [`PUT` update version](#tag/ActorsVersion-object/operation/act_version_put) method and behaves identically. + This endpoint is an alias for the [`PUT` update version](#tag/ActorsVersion-object/operation/actor_version_put) method and behaves identically. operationId: actor_version_post x-legacy-doc-urls: - https://docs.apify.com/api/v2#/reference/actors/version-object/update-version 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 98520d5e3f..0ad7ea6878 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 @@ -27,7 +27,7 @@ If the Actor being run via API takes 5 minutes or less to complete a typical run > If you are unsure about the differences between an Actor and a task, you can read about them in the [tasks](/actors/running/tasks) documentation. In brief, tasks are pre-configured inputs for Actors. -The API endpoints and usage (for both sync and async) for [Actors](/api/v2#tag/ActorsRun-collection/operation/act_runs_post) and [tasks](/api/v2/actor-task-runs-post) are essentially the same. +The API endpoints and usage (for both sync and async) for [Actors](/api/v2/actors-runs-post) and [tasks](/api/v2/actor-task-runs-post) are essentially the same. To run, or **call**, an Actor/task, you will need a few things: @@ -45,7 +45,7 @@ The URL of [POST request](https://developer.mozilla.org/en-US/docs/Web/HTTP/Meth 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: +For tasks, we can switch the path from **actors** to **actor-tasks** and keep the rest the same: ```cURL https://api.apify.com/v2/actor-tasks/TASK_NAME_OR_ID/runs?token=YOUR_TOKEN diff --git a/sources/academy/tutorials/api/using_apify_from_php.md b/sources/academy/tutorials/api/using_apify_from_php.md index bb366e5e0d..4799b4a26c 100644 --- a/sources/academy/tutorials/api/using_apify_from_php.md +++ b/sources/academy/tutorials/api/using_apify_from_php.md @@ -59,7 +59,7 @@ The [API reference](/api/v2/actors-runs-post) states that an Actor's input shoul // To identify the Actor, you can use its ID, but you can also pass // the full Actor name [username]~[actorName] or just ~[actorName] for // your own Actors -$response = $client->post('acts/vdrmota~contact-info-scraper/runs', [ +$response = $client->post('actors/vdrmota~contact-info-scraper/runs', [ // Actors usually accept JSON as input. When using the `json` key in // a POST request's options, guzzle sets proper request headers // and serializes the array we pass in @@ -128,7 +128,7 @@ All the available parameters are described in [our API reference](/api/v2/datase Datasets are great for structured data, but are not suited for binary files like images or PDFs. In these cases, Actors store their output in [key-value stores](/storage/key-value-store). One such Actor is the **HTML String To PDF** ([mhamas/html-string-to-pdf](https://apify.com/mhamas/html-string-to-pdf)) converter. Let's run it. ```php -$response = $client->post('acts/mhamas~html-string-to-pdf/runs', [ +$response = $client->post('actors/mhamas~html-string-to-pdf/runs', [ 'json' => [ 'htmlString' => '

Hello World

' ], @@ -183,7 +183,7 @@ It takes some time for an Actor to generate its output. Some even have Actors th For Actors that are expected to be quick, we can use the `waitForFinish` parameter. Then, the running Actor's endpoint does not respond immediately but waits until the run finishes (up to the given limit). Let's try this with the HTML String to PDF Actor. ```php -$response = $client->post('acts/mhamas~html-string-to-pdf/runs', [ +$response = $client->post('actors/mhamas~html-string-to-pdf/runs', [ 'json' => [ 'htmlString' => '

Hi World

' ], @@ -217,7 +217,7 @@ $webhooks = \base64_encode(\json_encode([ 'requestUrl' => '', ], ])); -$response = $client->post('acts/mhamas~html-string-to-pdf/runs', [ +$response = $client->post('actors/mhamas~html-string-to-pdf/runs', [ 'json' => [ 'htmlString' => '

Hello World

' ], diff --git a/sources/platform/get-started/agent-onboarding.md b/sources/platform/get-started/agent-onboarding.md index 7fa94453bf..069f884fdd 100644 --- a/sources/platform/get-started/agent-onboarding.md +++ b/sources/platform/get-started/agent-onboarding.md @@ -255,9 +255,9 @@ For HTTP-native integrations or languages without a dedicated client. Base URL: | Action | Method | Endpoint | | :--- | :--- | :--- | | [Search Actors in Store](/api/v2/store-get) | `GET` | `/v2/store` | -| [Get Actor details](/api/v2/actor-get) | `GET` | `/v2/acts/{actorId}` | -| [Run an Actor](/api/v2/actors-runs-post) | `POST` | `/v2/acts/{actorId}/runs` | -| [Run Actor (sync, get results)](/api/v2/actor-run-sync-get-dataset-items-post) | `POST` | `/v2/acts/{actorId}/run-sync-get-dataset-items` | +| [Get Actor details](/api/v2/actor-get) | `GET` | `/v2/actors/{actorId}` | +| [Run an Actor](/api/v2/actors-runs-post) | `POST` | `/v2/actors/{actorId}/runs` | +| [Run Actor (sync, get results)](/api/v2/actor-run-sync-get-dataset-items-post) | `POST` | `/v2/actors/{actorId}/run-sync-get-dataset-items` | | [Get run status](/api/v2/actor-run-get) | `GET` | `/v2/actor-runs/{runId}` | | [Get dataset items](/api/v2/dataset-items-get) | `GET` | `/v2/datasets/{datasetId}/items` | diff --git a/sources/platform/integrations/programming/github.md b/sources/platform/integrations/programming/github.md index 90b3d62a01..2c3fc41684 100644 --- a/sources/platform/integrations/programming/github.md +++ b/sources/platform/integrations/programming/github.md @@ -55,7 +55,7 @@ After you link an Actor to a GitHub repository, add a webhook in GitHub to trigg 1. In Apify Console, open the Actor's **API** dropdown and select **API endpoints**. Copy the **Build Actor** endpoint URL. It has this format: ```text - https://api.apify.com/v2/acts/YOUR-ACTOR-NAME/builds?token=YOUR-TOKEN&version=0.0&tag=latest&waitForFinish=60 + https://api.apify.com/v2/actors/YOUR-ACTOR-NAME/builds?token=YOUR-TOKEN&version=0.0&tag=latest&waitForFinish=60 ``` :::note API token From a09fbc7ba688aad89a2892c8173930a7772b34d8 Mon Sep 17 00:00:00 2001 From: Marek Honzal Date: Wed, 29 Jul 2026 14:04:56 +0200 Subject: [PATCH 2/4] fix: restore legacy API doc anchors and correct operation ID conventions --- .../api-doc/references/openapi-patterns.md | 19 ++++++++++++++++--- CONTRIBUTING.md | 6 ++++-- ...rsionNumber}@env-vars@{envVarName}put.yaml | 2 +- ...{actorId}@versions@{versionNumber}put.yaml | 2 +- .../integrations/programming/github.md | 4 +++- 5 files changed, 25 insertions(+), 8 deletions(-) diff --git a/.agents/skills/api-doc/references/openapi-patterns.md b/.agents/skills/api-doc/references/openapi-patterns.md index ca09893c64..b772ca3224 100644 --- a/.agents/skills/api-doc/references/openapi-patterns.md +++ b/.agents/skills/api-doc/references/openapi-patterns.md @@ -76,7 +76,7 @@ Format: `{objectName}_{httpMethod}` Rules: - Use camelCase for object names -- Singular for paths with `{id}`, plural otherwise +- Singular for paths with `{id}`, plural otherwise - except for the Actor `/runs` and `/builds` collections, see the exception below - Underscore separator between object name and method - Method name in lowercase @@ -88,10 +88,23 @@ Rules: | `/actors/{actorId}/runs` | POST | `actors_runs_post` | | `/actors/{actorId}/runs` | GET | `actors_runs_get` | | `/actors/{actorId}/runs/{runId}` | GET | `actors_run_get` | +| `/actors/{actorId}/runs/last` | GET | `actor_runs_last_get` | +| `/actors/{actorId}/builds/default` | GET | `actor_build_default_get` | -An Actor's own `/runs` and `/builds` sub-resources keep the plural `actors_` prefix, because the account-wide `/actor-runs` and `/actor-builds` paths already own the singular `actorRun_` and `actorBuild_` prefixes. +### Actor runs and builds exception -Never use the legacy `/acts` prefix in paths or operation IDs. The canonical prefixes are `/actors`, `/actor-runs`, and `/actor-builds`. +Operations on an Actor's own `/runs` and `/builds` collections and their direct members keep the plural `actors_` prefix. The complete list is `actors_runs_get`, `actors_runs_post`, `actors_run_get`, `actors_run_abort_post`, `actors_run_metamorph_post`, `actors_builds_get`, `actors_builds_post`, `actors_build_get`, and `actors_build_abort_post`. The reason is that the account-wide `/actor-runs` and `/actor-builds` paths already own the singular `actorRun_` and `actorBuild_` prefixes. + +Deeper scoped sub-resources use the singular `actor_` prefix: `runs/last`, `run-sync`, `builds/default`, versions, and webhooks. The same split is encoded in the redirect rules in `nginx.conf`. + +### Legacy `/acts` prefix + +Never use the legacy `/acts` or `act_` prefix in user-facing URLs, in `paths` keys, or in new operation IDs. The canonical prefixes are `/actors`, `/actor-runs`, and `/actor-builds`. + +Two internal uses are intentional and must stay: + +- Source filenames under `openapi/paths/` and `openapi/components/objects/` use the `acts@{actorId}…` form. The filename is not the served path, so don't rename them. +- `x-legacy-doc-urls` entries keep their historical `act_*` fragments, and so do in-description links that point at those fragments. The fragments are the anchors the decorator emits for backward compatibility - rewriting them to `actor_*` breaks the exact links they exist to preserve. ## Code sample examples diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5787a5d236..8439787ec1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -264,7 +264,7 @@ Operation IDs must follow this format: - Generated from path structure and HTTP method - Use camelCase for object names -- Single object for paths with {id}, plural otherwise +- Single object for paths with {id}, plural otherwise - except for the Actor `/runs` and `/builds` collections, see the note below - Underscore separator between object name and action - Method name in lowercase at the end @@ -274,7 +274,9 @@ Examples: - `/requests-queues/{queueId}` PUT -> `requestQueue_put` - `/actors/{actorId}/runs` POST -> `actors_runs_post` -An Actor's own `/runs` and `/builds` sub-resources keep the plural `actors_` prefix, because the account-wide `/actor-runs` and `/actor-builds` paths already own the singular `actorRun_` and `actorBuild_` prefixes. +Operations on an Actor's own `/runs` and `/builds` collections and their direct members keep the plural `actors_` prefix - `actors_runs_get`, `actors_runs_post`, `actors_run_get`, `actors_run_abort_post`, `actors_run_metamorph_post`, `actors_builds_get`, `actors_builds_post`, `actors_build_get`, `actors_build_abort_post`. That is the complete list. The reason is that the account-wide `/actor-runs` and `/actor-builds` paths already own the singular `actorRun_` and `actorBuild_` prefixes. + +Deeper scoped sub-resources use the singular `actor_` prefix: `runs/last` (`actor_runs_last_get`), `run-sync` (`actor_runSync_post`), `builds/default` (`actor_build_default_get`), versions, and webhooks. The same split is encoded in the redirect rules in `nginx.conf`. #### Code samples diff --git a/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}@env-vars@{envVarName}put.yaml b/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}@env-vars@{envVarName}put.yaml index 7d985c1825..2d11bc6f66 100644 --- a/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}@env-vars@{envVarName}put.yaml +++ b/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}@env-vars@{envVarName}put.yaml @@ -90,7 +90,7 @@ post: Updates Actor environment variable using values specified by a [EnvVar object](#/reference/actors/environment-variable-object) passed as JSON in the POST payload. - This endpoint is an alias for the [`PUT` update environment variable](#tag/ActorsEnvironment-variable-object/operation/actor_version_envVar_put) method and behaves identically. + This endpoint is an alias for the [`PUT` update environment variable](#tag/ActorsEnvironment-variable-object/operation/act_version_envVar_put) method and behaves identically. operationId: actor_version_envVar_post x-legacy-doc-urls: - https://docs.apify.com/api/v2#/reference/actors/environment-variable-object/update-environment-variable diff --git a/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}put.yaml b/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}put.yaml index 52a74a8bdd..d27decd93e 100644 --- a/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}put.yaml +++ b/apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}put.yaml @@ -82,7 +82,7 @@ post: summary: Update version (POST) description: | Updates Actor version using values specified by a [Version object](#/reference/actors/version-object) passed as JSON in the POST payload. - This endpoint is an alias for the [`PUT` update version](#tag/ActorsVersion-object/operation/actor_version_put) method and behaves identically. + This endpoint is an alias for the [`PUT` update version](#tag/ActorsVersion-object/operation/act_version_put) method and behaves identically. operationId: actor_version_post x-legacy-doc-urls: - https://docs.apify.com/api/v2#/reference/actors/version-object/update-version diff --git a/sources/platform/integrations/programming/github.md b/sources/platform/integrations/programming/github.md index 2c3fc41684..c030bd77db 100644 --- a/sources/platform/integrations/programming/github.md +++ b/sources/platform/integrations/programming/github.md @@ -52,12 +52,14 @@ For private repositories, configure a [deployment key](/actors/development/deplo After you link an Actor to a GitHub repository, add a webhook in GitHub to trigger a new build on every push: -1. In Apify Console, open the Actor's **API** dropdown and select **API endpoints**. Copy the **Build Actor** endpoint URL. It has this format: +1. In Apify Console, open the Actor's **API** dropdown and select **API endpoints**. Copy the **Build Actor** endpoint URL: ```text https://api.apify.com/v2/actors/YOUR-ACTOR-NAME/builds?token=YOUR-TOKEN&version=0.0&tag=latest&waitForFinish=60 ``` + Console may give you the same endpoint with the legacy `/v2/acts/` prefix. Both prefixes work, so use the URL as copied. + :::note API token Select the correct API token in the dropdown before copying the URL. From 34b021f63105fe372a2056cc3556e26e4921f258 Mon Sep 17 00:00:00 2001 From: Marek Honzal Date: Wed, 29 Jul 2026 14:44:45 +0200 Subject: [PATCH 3/4] docs: trim operation ID convention notes to the essential rule --- .../api-doc/references/openapi-patterns.md | 19 +++---------------- CONTRIBUTING.md | 6 +----- 2 files changed, 4 insertions(+), 21 deletions(-) diff --git a/.agents/skills/api-doc/references/openapi-patterns.md b/.agents/skills/api-doc/references/openapi-patterns.md index b772ca3224..806aaf5c9c 100644 --- a/.agents/skills/api-doc/references/openapi-patterns.md +++ b/.agents/skills/api-doc/references/openapi-patterns.md @@ -76,7 +76,7 @@ Format: `{objectName}_{httpMethod}` Rules: - Use camelCase for object names -- Singular for paths with `{id}`, plural otherwise - except for the Actor `/runs` and `/builds` collections, see the exception below +- Singular for paths with `{id}`, plural otherwise - Underscore separator between object name and method - Method name in lowercase @@ -86,25 +86,12 @@ Rules: | `/request-queues/{queueId}` | GET | `requestQueue_get` | | `/request-queues/{queueId}` | PUT | `requestQueue_put` | | `/actors/{actorId}/runs` | POST | `actors_runs_post` | -| `/actors/{actorId}/runs` | GET | `actors_runs_get` | | `/actors/{actorId}/runs/{runId}` | GET | `actors_run_get` | | `/actors/{actorId}/runs/last` | GET | `actor_runs_last_get` | -| `/actors/{actorId}/builds/default` | GET | `actor_build_default_get` | -### Actor runs and builds exception +Uniqueness beats the singular rule, because the operation ID becomes the page slug. `/actors/{actorId}/runs` can't be `actor_runs_post` - the account-wide `/actor-runs` family owns that slug and the two are different scopes. So Actor-scoped `/runs` and `/builds` use plural `actors_`, while `runs/last` has no clash and stays singular. Matching redirects: `nginx.conf`. -Operations on an Actor's own `/runs` and `/builds` collections and their direct members keep the plural `actors_` prefix. The complete list is `actors_runs_get`, `actors_runs_post`, `actors_run_get`, `actors_run_abort_post`, `actors_run_metamorph_post`, `actors_builds_get`, `actors_builds_post`, `actors_build_get`, and `actors_build_abort_post`. The reason is that the account-wide `/actor-runs` and `/actor-builds` paths already own the singular `actorRun_` and `actorBuild_` prefixes. - -Deeper scoped sub-resources use the singular `actor_` prefix: `runs/last`, `run-sync`, `builds/default`, versions, and webhooks. The same split is encoded in the redirect rules in `nginx.conf`. - -### Legacy `/acts` prefix - -Never use the legacy `/acts` or `act_` prefix in user-facing URLs, in `paths` keys, or in new operation IDs. The canonical prefixes are `/actors`, `/actor-runs`, and `/actor-builds`. - -Two internal uses are intentional and must stay: - -- Source filenames under `openapi/paths/` and `openapi/components/objects/` use the `acts@{actorId}…` form. The filename is not the served path, so don't rename them. -- `x-legacy-doc-urls` entries keep their historical `act_*` fragments, and so do in-description links that point at those fragments. The fragments are the anchors the decorator emits for backward compatibility - rewriting them to `actor_*` breaks the exact links they exist to preserve. +Never rewrite the `act_*` fragments in `x-legacy-doc-urls` or in-description links pointing at them. They're backward-compatibility anchors, not operation ID references - nginx can't see URL fragments, so they're the only thing keeping old anchor links alive. ## Code sample examples diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8439787ec1..f2511f2cfc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -264,7 +264,7 @@ Operation IDs must follow this format: - Generated from path structure and HTTP method - Use camelCase for object names -- Single object for paths with {id}, plural otherwise - except for the Actor `/runs` and `/builds` collections, see the note below +- Single object for paths with {id}, plural otherwise - Underscore separator between object name and action - Method name in lowercase at the end @@ -274,10 +274,6 @@ Examples: - `/requests-queues/{queueId}` PUT -> `requestQueue_put` - `/actors/{actorId}/runs` POST -> `actors_runs_post` -Operations on an Actor's own `/runs` and `/builds` collections and their direct members keep the plural `actors_` prefix - `actors_runs_get`, `actors_runs_post`, `actors_run_get`, `actors_run_abort_post`, `actors_run_metamorph_post`, `actors_builds_get`, `actors_builds_post`, `actors_build_get`, `actors_build_abort_post`. That is the complete list. The reason is that the account-wide `/actor-runs` and `/actor-builds` paths already own the singular `actorRun_` and `actorBuild_` prefixes. - -Deeper scoped sub-resources use the singular `actor_` prefix: `runs/last` (`actor_runs_last_get`), `run-sync` (`actor_runSync_post`), `builds/default` (`actor_build_default_get`), versions, and webhooks. The same split is encoded in the redirect rules in `nginx.conf`. - #### Code samples 1. Navigate to the `openapi/code_samples` folder From 8290b0b17bea2ec91571ef39d0737a75256445b6 Mon Sep 17 00:00:00 2001 From: Marek Honzal Date: Wed, 29 Jul 2026 15:31:25 +0200 Subject: [PATCH 4/4] docs: correct Console endpoint note and operation ID slug examples --- .agents/skills/api-doc/references/openapi-patterns.md | 6 +++--- sources/platform/integrations/programming/github.md | 4 +--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/.agents/skills/api-doc/references/openapi-patterns.md b/.agents/skills/api-doc/references/openapi-patterns.md index 806aaf5c9c..83ca28e0e8 100644 --- a/.agents/skills/api-doc/references/openapi-patterns.md +++ b/.agents/skills/api-doc/references/openapi-patterns.md @@ -86,12 +86,12 @@ Rules: | `/request-queues/{queueId}` | GET | `requestQueue_get` | | `/request-queues/{queueId}` | PUT | `requestQueue_put` | | `/actors/{actorId}/runs` | POST | `actors_runs_post` | -| `/actors/{actorId}/runs/{runId}` | GET | `actors_run_get` | +| `/actors/{actorId}/builds` | GET | `actors_builds_get` | | `/actors/{actorId}/runs/last` | GET | `actor_runs_last_get` | -Uniqueness beats the singular rule, because the operation ID becomes the page slug. `/actors/{actorId}/runs` can't be `actor_runs_post` - the account-wide `/actor-runs` family owns that slug and the two are different scopes. So Actor-scoped `/runs` and `/builds` use plural `actors_`, while `runs/last` has no clash and stays singular. Matching redirects: `nginx.conf`. +Uniqueness beats the singular rule, because the operation ID becomes the page slug. GET `/actors/{actorId}/runs` can't be `actor_runs_get` - the account-wide GET `/actor-runs` already owns the `actor-runs-get` slug and the two are different scopes. So Actor-scoped `/runs` and `/builds` use plural `actors_`, while `runs/last` has no clash and stays singular. Matching redirects: `nginx.conf`. -Never rewrite the `act_*` fragments in `x-legacy-doc-urls` or in-description links pointing at them. They're backward-compatibility anchors, not operation ID references - nginx can't see URL fragments, so they're the only thing keeping old anchor links alive. +Never rewrite the `act_*` fragments in `x-legacy-doc-urls` or in-description links pointing at them. They're backward-compatibility anchors, not operation ID references. `docusaurus.config.js` turns every `x-legacy-doc-urls` hash into a `data-altids` sidebar attribute, and `redirectOpenApiDocs()` in `apify-docs-theme/static/js/custom.js` matches an incoming `#tag/` or `#/reference/` hash against those altids - an unmatched hash hard-bounces to `/search?...¬-found=1`. Rewrite `act_version_put` to `actor_version_put` and the old link breaks, because no page carries the new id. ## Code sample examples diff --git a/sources/platform/integrations/programming/github.md b/sources/platform/integrations/programming/github.md index c030bd77db..2c3fc41684 100644 --- a/sources/platform/integrations/programming/github.md +++ b/sources/platform/integrations/programming/github.md @@ -52,14 +52,12 @@ For private repositories, configure a [deployment key](/actors/development/deplo After you link an Actor to a GitHub repository, add a webhook in GitHub to trigger a new build on every push: -1. In Apify Console, open the Actor's **API** dropdown and select **API endpoints**. Copy the **Build Actor** endpoint URL: +1. In Apify Console, open the Actor's **API** dropdown and select **API endpoints**. Copy the **Build Actor** endpoint URL. It has this format: ```text https://api.apify.com/v2/actors/YOUR-ACTOR-NAME/builds?token=YOUR-TOKEN&version=0.0&tag=latest&waitForFinish=60 ``` - Console may give you the same endpoint with the legacy `/v2/acts/` prefix. Both prefixes work, so use the URL as copied. - :::note API token Select the correct API token in the dropdown before copying the URL.