Replace undocumented `/v2/acts` examples with OpenAPI routes

[webrdaniel]

Note

This issue was AI-generated based on an AI analysis of Apify’s agent-facing contracts.

Current problem

Official agent onboarding, Actor-page examples, agents.md, and official Skills still teach /v2/acts routes. Those aliases currently respond, but they are absent from the public OpenAPI contract, which defines /v2/actors and /v2/actor-runs. Agents that validate or generate integrations from OpenAPI therefore receive a different contract from agents that copy official examples.

Why this reduces adoption and usage

• Agents that copy official examples generate integrations different from clients generated from OpenAPI.
• Validation, SDK generation, and troubleshooting become less reliable because the documented and machine-readable contracts disagree.
• Even when the legacy alias works, teams may reject it as unsupported or incur migration work later, reducing confidence in production adoption.
• The mismatch is repeated across many surfaces, increasing the chance that an agent selects the wrong route.

Desired state

Every newly generated agent instruction uses routes and operation IDs from the public OpenAPI contract.

Acceptance criteria

• Update onboarding Actor operations to /v2/actors/{actorId} and run status to /v2/actor-runs/{runId}.
• Inventory and update affected docs, web snippets, Skills, plugins, and CLI help through linked follow-ups or coordinated PRs.
• Generate shared snippets from OpenAPI operation IDs instead of copied route strings.
• Add CI that fails when a documented api.apify.com/v2 path is absent from current OpenAPI.
• Treat /v2/acts only as an explicitly documented compatibility alias, if it must remain.

Priority: P0. Estimated effort: M.

[webrdaniel]

This is relevant, let's check it before proceeding with this: https://apify.slack.com/archives/CQ96RHG2U/p1785161648015039