feat: Rename legacy act-* API operationIds to actor-* for consistency by jancurn · Pull Request #2646 · apify/apify-docs

jancurn · 2026-06-16T14:10:41Z

Renames all legacy act_*/acts_* operationIds so API reference URLs match the canonical /v2/actors/ naming - e.g. https://docs.apify.com/api/v2/acts-post becomes /api/v2/actors-post, /api/v2/act-get becomes /api/v2/actor-get.

Because the account-wide /v2/actor-runs and /v2/actor-builds endpoints already own the actor-runs-*/actor-builds-* slugs, operations on an Actor's own /runs and /builds collections (including their deprecated per-item aliases) use the actors-* prefix instead, mirroring /v2/actors/{actorId}/... - e.g. /api/v2/act-runs-post becomes /api/v2/actors-runs-post. Deeper scoped sub-resources (runs/last, run-sync, versions, webhooks) keep the actor-* member prefix.

No act-* pages remain: every legacy slug 301-redirects via nginx (one explicit rule for the nine runs/builds slugs plus two catch-alls). Documentation links, code sample filenames, and the LLMs index exclusions are updated to match.

https://claude.ai/code/session_01Q4HrVBuRKYG46ztwLXQkHz

Rename the legacy `act_*`/`acts_*` operationIds in the OpenAPI source to `actor_*`/`actors_*` so the generated doc page slugs become `/api/v2/actor-*`, matching the canonical `/v2/actors/` naming. operationId only drives doc-slug generation and client method hints; the live API at api.apify.com/v2 is unchanged (paths, methods, parameters, and request/response schemas untouched). - 63 operations renamed; matching `code_samples/*` files renamed to keep their samples attached. - 7 deprecated actor-scoped build/run duplicates (act-build-get, act-builds-get, act-build-abort-post, act-run-get, act-runs-get, act-run-abort-post, act-run-metamorph-post) keep their operationIds; their legacy URLs 301-redirect to the canonical standalone actor-build*/actor-run* pages. - nginx: add 301 redirects `/api/v2/act-*` -> `/api/v2/actor-*` and `/api/v2/acts-*` -> `/api/v2/actors-*` covering every old slug. - Update internal doc links and the llms.txt index exclusion patterns. https://claude.ai/code/session_01Q4HrVBuRKYG46ztwLXQkHz

apify-service-account · 2026-06-16T14:11:25Z

✅ Preview for this PR (commit 1da9e276) is ready at https://pr-2646.preview.docs.apify.com (see action run).

jancurn · 2026-06-16T16:36:37Z

Sorry guys for this "drop". It's a lot of changes but should be fairly safe I think.

TC-MO · 2026-06-17T06:21:14Z

+    # Actor API reference operation pages: legacy `act-*`/`acts-*` slugs -> `actor-*`/`actors-*`.
+    # Each page slug is kebab-case(operationId); the `act_*`/`acts_*` operationIds were renamed to
+    # `actor_*`/`actors_*` to match the canonical `/v2/actors/` naming. The deprecated actor-scoped
+    # build/run duplicates (act-build-get, act-builds-get, act-build-abort-post, act-run-get,
+    # act-runs-get, act-run-abort-post, act-run-metamorph-post) resolve to their canonical
+    # standalone actor-build*/actor-run* pages via the same act- -> actor- rewrite.
+    rewrite ^/api/v2/acts-(.*)$ /api/v2/actors-$1 permanent;
+    rewrite ^/api/v2/act-(.*)$ /api/v2/actor-$1 permanent;
+


Just off the top of my head I think this is problematic, weird UX, and partly a bug.

The genuinely deprecated endpoints (act-build-get, act-run-get, abort, metamorph) are already marked deprecated: true in the spec, with an admonition that tells you they're deprecated and links to the canonical one. A silent 301 strips that context. You click the endpoint and inexplicably land on a different page with no explanation.

But act-builds-get and act-runs-get aren't deprecated at all. They're the Actor-scoped list endpoints (GET /v2/acts/{actorId}/builds, GET /v2/acts/{actorId}/runs). The broad rule at line 800 catches them and redirects to actor-builds-get / actor-runs-get, which are the account-wide "Get user builds/runs list" endpoints.

Different scope, no equivalent in the new namespace. So that's a straight regression: those pages serve correct content on prod today and would 301 away after this.

…irect The act-(.*) catch-all also matched 7 Actor-scoped build/run pages that were intentionally not renamed and still exist: it stripped the deprecation notice from the 5 deprecated pages (silent 301) and, worse, 301'd the two non-deprecated Actor-scoped list pages (act-builds-get, act-runs-get) to the account-wide actor-builds-get/actor-runs-get, which have a different scope and no equivalent. Add an exact-match guard that serves those 7 via `break`; every other moved act-* slug (incl. prefix-sharing ones like act-build-default-get) still 301s. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q4HrVBuRKYG46ztwLXQkHz

TC-MO

From my POV it looks good now

…niak-vsr50p

marcel-rbro · 2026-06-19T11:56:12Z

+- [List Actor Runs](https://docs.apify.com/api/v2/actor-runs-get)
+- [List Specific Actor Runs](https://docs.apify.com/api/v2/actor-runs-get)


These links now point to a different page, not sure if that would be a problem, don't know enough about this integration.

https://docs.apify.com/api/v2/act-runs-get (runs of a specific actor)
vs.
https://docs.apify.com/api/v2/actor-runs-get (all runs by a user)

janbuchar · 2026-06-22T12:25:40Z

Sorry guys for this "drop". It's a lot of changes but should be fairly safe I think.

It's great that we're getting rid of the act_ terminology, that's been long overdue. One concern though:

The operationId property determines the URL in the rendered API docs, and it's not cool to break links to tens of endpoints. I'm pretty sure that the x-legacy-doc-urls property on the Operation object should make it fairly easy to add redirects for compatibility.

EDIT: Now I noticed this in the PR description, sorry, my bad.

Added nginx rewrite rules to redirect legacy act-* and acts-* URL slugs to their actor-* and actors-* equivalents with 301 permanent redirects

Still, I'm not sure we want to have two parallel ways to handle redirects from deprecated URLs. I think we should either unify this right away or make a follow up issue.

janbuchar

I voiced my concern earlier, but it's not a reason to block this PR — it's fine from an openapi quality standpoint.

TC-MO · 2026-06-22T15:15:22Z

Wasn't the x-legacy-doc-urls just used for transition from API Blueprint, while in general redirects were always handled through nginx?

janbuchar · 2026-06-22T16:19:01Z

Wasn't the x-legacy-doc-urls just used for transition from API Blueprint, while in general redirects were always handled through nginx?

That sounds plausible. Maybe because nginx can't see the URL fragment?

jancurn · 2026-06-25T14:27:56Z

Thanks for the reviews, but pls let's not merge this yet, i still need to resolve the conflict between /actors/{x}/runs and /actor-runs in IDs

…niak-vsr50p # Conflicts: # apify-api/openapi/paths/actors/acts.yaml # apify-api/openapi/paths/actors/acts@{actorId}.yaml # sources/academy/tutorials/api/run_actor_and_retrieve_data_via_api.md # sources/platform/actors/development/builds_and_runs/runs.md # sources/platform/actors/running/index.md

…or scoped runs/builds The rename of act_* operationIds to actor_* collided on 7 slugs where the account-wide /v2/actor-runs and /v2/actor-builds families already own the actor-runs-*/actor-builds-* names (e.g. act-runs-get = runs of one Actor vs actor-runs-get = all runs of a user). The previous fix kept those 7 pages on their legacy act-* slugs behind an nginx serve-guard, which left the naming conflict unresolved. Rename the 9 direct operations on an Actor's own /runs and /builds collections (list/create plus the 5 deprecated per-item aliases) to the actors_* prefix, mirroring their literal path /v2/actors/{actorId}/... : act_runs_get -> actors_runs_get act_builds_get -> actors_builds_get act_run_get -> actors_run_get (deprecated) act_build_get -> actors_build_get (deprecated) act_run_abort_post -> actors_run_abort_post (deprecated) act_build_abort_post -> actors_build_abort_post (deprecated) act_run_metamorph_post -> actors_run_metamorph_post (deprecated) actor_runs_post -> actors_runs_post actor_builds_post -> actors_builds_post Deeper scoped sub-resources (runs/last, run-sync, builds/default, versions, webhooks) keep the actor- member prefix; account-wide families keep actor-runs-*/actor-builds-*. No act-*/acts-* slugs remain, so nginx needs no serve-exceptions: one explicit alternation rewrites the 9 legacy slugs to actors-*, and the two catch-alls 301 everything else. Verified: all 70 legacy slugs redirect to existing pages. Also relink bubble.md's Actor-scoped run-list references to actors-runs-get (they were pointing at the account-wide list), update actors-runs-post links across docs, rename the matching code sample files, and refresh the LLMs index exclusions. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q4HrVBuRKYG46ztwLXQkHz

apify-service-account · 2026-07-08T09:27:00Z

Important

Action required — @jancurn please coordinate this docs PR with the Python API client PR linked below.

Because this PR modifies the OpenAPI specification, the generated models in apify-client-python must be regenerated to stay in sync. This has already been done automatically:

A companion PR has been opened in apify-client-python with the regenerated models: apify/apify-client-python#926

Please make sure to review and merge both PRs together to keep the OpenAPI spec and API clients in sync.
You can ask for review and help from the Tooling team if needed.

jancurn · 2026-07-08T13:23:52Z

I've redone this with Fable, fixed the duplicates, and this should be good to go. Would be great if somebody else could check this, but in worst case, it only affects docs :)

jancurn requested review from fnesveda, honzajavorek, janbuchar, marcel-rbro and szaganek as code owners June 16, 2026 14:10

jancurn changed the title ~~Rename legacy act-* API operationIds to actor-* for consistency~~ feat: Rename legacy act-* API operationIds to actor-* for consistency Jun 16, 2026

jancurn requested a review from TC-MO June 16, 2026 14:16

jancurn removed the request for review from honzajavorek June 16, 2026 16:38

TC-MO reviewed Jun 17, 2026

View reviewed changes

TC-MO approved these changes Jun 19, 2026

View reviewed changes

Merge remote-tracking branch 'origin/master' into claude/vigilant-woz…

e92f9cd

…niak-vsr50p

marcel-rbro reviewed Jun 19, 2026

View reviewed changes

janbuchar approved these changes Jun 22, 2026

View reviewed changes

fnesveda approved these changes Jun 25, 2026

View reviewed changes

claude added 2 commits July 8, 2026 09:17

apify-service-account mentioned this pull request Jul 8, 2026

TODO apify/apify-client-python#926

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Rename legacy act-* API operationIds to actor-* for consistency#2646

feat: Rename legacy act-* API operationIds to actor-* for consistency#2646
jancurn wants to merge 5 commits into
masterfrom
claude/vigilant-wozniak-vsr50p

jancurn commented Jun 16, 2026 •

edited

Loading

Uh oh!

apify-service-account commented Jun 16, 2026 •

edited

Loading

Uh oh!

jancurn commented Jun 16, 2026

Uh oh!

TC-MO Jun 17, 2026

Uh oh!

TC-MO left a comment •

edited

Loading

Uh oh!

marcel-rbro Jun 19, 2026 •

edited

Loading

Uh oh!

janbuchar commented Jun 22, 2026 •

edited

Loading

Uh oh!

janbuchar left a comment

Uh oh!

TC-MO commented Jun 22, 2026

Uh oh!

janbuchar commented Jun 22, 2026

Uh oh!

jancurn commented Jun 25, 2026

Uh oh!

apify-service-account commented Jul 8, 2026

Uh oh!

jancurn commented Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

		- [List Actor Runs](https://docs.apify.com/api/v2/actor-runs-get)
		- [List Specific Actor Runs](https://docs.apify.com/api/v2/actor-runs-get)

Uh oh!

Conversation

jancurn commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

jancurn commented Jun 16, 2026

Uh oh!

TC-MO Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

TC-MO left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marcel-rbro Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

janbuchar commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

janbuchar left a comment

Choose a reason for hiding this comment

Uh oh!

TC-MO commented Jun 22, 2026

Uh oh!

janbuchar commented Jun 22, 2026

Uh oh!

jancurn commented Jun 25, 2026

Uh oh!

apify-service-account commented Jul 8, 2026

Uh oh!

jancurn commented Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

jancurn commented Jun 16, 2026 •

edited

Loading

apify-service-account commented Jun 16, 2026 •

edited

Loading

TC-MO left a comment •

edited

Loading

marcel-rbro Jun 19, 2026 •

edited

Loading

janbuchar commented Jun 22, 2026 •

edited

Loading