docs(api): rename /v2/acts/ → /v2/actors/ in OpenAPI spec and sweep doc-site references by mtrunkat · Pull Request #2522 · apify/apify-docs

mtrunkat · 2026-05-12T09:13:56Z

Mirrors apify/apify-core#27780 on the documentation side. The server PR keeps /v2/acts/... as an undocumented alias, but the canonical, documented path family is now /v2/actors/.... This PR updates the published OpenAPI spec and the docs-site code samples accordingly.

Intentionally out of scope

acts-get page slug references in integrate_with_apify.md and bubble.md. These URLs (e.g. https://docs.apify.com/api/v2/acts-get) are derived from the OpenAPI operationIds (acts_get, act_runs_post, etc.), which §5 of the audit covers separately. Until the operationIds are renamed, the acts-get URLs remain valid, so leaving them is correct for this PR.
"actId": example payload in webhooks/actions.md (§12 fine-print). That's a payload field, which is §2 of the audit.
Renaming the path YAML files themselves from paths/actors/acts@*.yaml to actors@*.yaml. The internal file names don't show up in the published spec; the $ref targets in openapi.yaml resolve them at build time. Worth a separate cleanup PR if desired.

…ill 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

Copilot

Pull request overview

Updates the Apify API documentation to use /v2/actors/... as the canonical URL prefix (replacing /v2/acts/...) across the OpenAPI spec and doc-site code samples, while documenting that /v2/acts/... remains a deprecated-but-working alias.

Changes:

Renames Actor-scoped OpenAPI path keys from /v2/acts/... to /v2/actors/... and adds a legacy-prefix note in the spec introduction.
Updates OpenAPI path-file inline examples (e.g., Location headers and prose path snippets) to the /v2/actors/... prefix.
Sweeps docs-site markdown/MDX/TSX snippets to replace /v2/acts/... with /v2/actors/... in examples.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/pages/api/index.tsx	Updates the API landing page hero cURL snippet to `/v2/actors/`.
sources/platform/integrations/programming/webhooks/ad_hoc_webhooks.md	Updates ad-hoc webhook example URL to `/v2/actors/`.
sources/platform/integrations/ai/x402.md	Updates example API calls to `/v2/actors/` for X402 flow.
sources/platform/integrations/ai/skyfire.md	Updates synchronous run example to `/v2/actors/`.
sources/platform/integrations/actors/integrating_actors_via_api.md	Updates webhook `requestUrl` example to `/v2/actors/`.
sources/platform/actors/running/index.md	Updates “invoke via API” example URL to `/v2/actors/`.
sources/platform/actors/development/permissions/migration_guide.md	Updates API example URL to `/v2/actors/`.
sources/platform/actors/development/deployment/continuous_integration.md	Updates CI build endpoint examples to `/v2/actors/`.
sources/api/getting-started.mdx	Updates Getting started endpoints to `/v2/actors/`.
sources/academy/tutorials/node_js/apify_free_google_serp_api.md	Updates tutorial example URL to `/v2/actors/`.
sources/academy/tutorials/api/run_actor_and_retrieve_data_via_api.md	Updates tutorial API examples to `/v2/actors/`.
sources/academy/platform/getting_started/apify_api.md	Updates getting started examples to `/v2/actors/`.
sources/academy/platform/expert_scraping_with_apify/solutions/integrating_webhooks.md	Updates webhook integration examples to `/v2/actors/`.
apify-api/openapi/paths/actors/acts@{actorId}@versions@{versionNumber}@env-vars.yaml	Updates example URL to `/v2/actors/`.
apify-api/openapi/paths/actors/acts@{actorId}@versions.yaml	Updates example URL to `/v2/actors/`.
apify-api/openapi/paths/actors/acts@{actorId}@runs@last.yaml	Updates prose path snippet to `/v2/actors/`.
apify-api/openapi/paths/actors/acts@{actorId}@runs.yaml	Updates `Location` example to `/v2/actors/`.
apify-api/openapi/paths/actors/acts@{actorId}@builds.yaml	Updates `Location` example to `/v2/actors/`.
apify-api/openapi/paths/actors/acts.yaml	Updates example URL to `/v2/actors/`.
apify-api/openapi/openapi.yaml	Renames Actor path keys to `/v2/actors/` and documents the legacy `/v2/acts/` prefix.

                type: string
              example: >-
-                https://api.apify.com/v2/acts/zdc3Pyhyz3m8vjDeM/runs/HG7ML7M8z78YcAPEB
+                https://api.apify.com/v2/actors/zdc3Pyhyz3m8vjDeM/runs/HG7ML7M8z78YcAPEB


 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.


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

janbuchar · 2026-05-13T12:21:05Z

+    ## Legacy `/v2/acts/` URL prefix
+    <span id="/introduction/legacy-acts-prefix"></span>
+
+    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.


I'd shorten this warning to like 1 sentence, this simply doesn't deserve that much explanation.

I'd suggest something less verbose, like below:

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.

janbuchar · 2026-05-13T12:25:20Z

  - url: "https://api.apify.com"
    variables: {}
 paths:
-  /v2/acts:


It's not impossible to keep copies of the old versions with deprecated: true. We already have reusable operations for storage-handling operations (see components/objects) so there is precedent.

Of course, it might clutter the rendered docs quite a bit. But that's just speculation and it should be easy to try it.

I'd remove it from OpenAPI, to reduce token use for agents, space in docs etc. it really brings no value

tobice

The server PR keeps /v2/acts/... as an undocumented alias, but the canonical, documented path family is now /v2/actors/....

I guess we'll have to update the middleware that ensures that the spec is up to date, right? Because the specification for the legacy paths will be missing there and the middleware needs to be able to detect it.

--

Anyway, this looks like basically s/acts/actors/ for all paths 😄 Just like in the other PR, not sure if the PR description length is really justified here...

But there are plenty of reviewers here -> approve.

mtrunkat added 5 commits May 12, 2026 11:06

docs(api): flip /v2/acts/ curl example to /v2/actors/ on the api land…

b3e3957

…ing page 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

github-actions Bot assigned mtrunkat May 12, 2026

github-actions Bot added this to the 140th sprint - Management team milestone May 12, 2026

github-actions Bot added the t-management Issues with this label belong to the CTO or engineering managers. label May 12, 2026

mtrunkat added 2 commits May 12, 2026 12:15

Update getting-started.mdx

fe4d278

mtrunkat requested a review from tobice May 13, 2026 10:47

mtrunkat added the adhoc Ad-hoc unplanned task added during the sprint. label May 13, 2026

mtrunkat marked this pull request as ready for review May 13, 2026 10:50

Copilot AI review requested due to automatic review settings May 13, 2026 10:50

mtrunkat requested review from fnesveda, honzajavorek, janbuchar, marcel-rbro and szaganek as code owners May 13, 2026 10:50

Copilot started reviewing on behalf of mtrunkat May 13, 2026 10:51 View session

Copilot AI reviewed May 13, 2026

View reviewed changes

mtrunkat and others added 3 commits May 13, 2026 13:52

Potential fix for pull request finding

35f7be0

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Merge branch 'master' into claude/code-review-verification-nD81D

43570d1

Potential fix for pull request finding

41aeeb7

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

janbuchar reviewed May 13, 2026

View reviewed changes

tobice approved these changes May 13, 2026

View reviewed changes

fnesveda requested review from Pijukatel and removed request for fnesveda May 14, 2026 08:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(api): rename /v2/acts/ → /v2/actors/ in OpenAPI spec and sweep doc-site references#2522

docs(api): rename /v2/acts/ → /v2/actors/ in OpenAPI spec and sweep doc-site references#2522
mtrunkat wants to merge 10 commits into
masterfrom
claude/code-review-verification-nD81D

mtrunkat commented May 12, 2026 •

edited

Loading

Uh oh!

apify-service-account commented May 12, 2026 •

edited

Loading

Uh oh!

jancurn commented May 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

janbuchar May 13, 2026

Uh oh!

szaganek May 14, 2026

Uh oh!

janbuchar May 13, 2026

Uh oh!

jancurn May 13, 2026

Uh oh!

tobice left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Conversation

mtrunkat commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Intentionally out of scope

Related

Uh oh!

apify-service-account commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jancurn commented May 12, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

janbuchar May 13, 2026

Choose a reason for hiding this comment

Uh oh!

szaganek May 14, 2026

Choose a reason for hiding this comment

Uh oh!

janbuchar May 13, 2026

Choose a reason for hiding this comment

Uh oh!

jancurn May 13, 2026

Choose a reason for hiding this comment

Uh oh!

tobice left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

mtrunkat commented May 12, 2026 •

edited

Loading

apify-service-account commented May 12, 2026 •

edited

Loading