docs: use current endpoint names in API links and remove broken legacy anchors

.claude/README.md

@@ -32,7 +32,7 @@ Each skill contains its own `references/` and `scripts/` (formerly in `workflows
 
 ### For Claude Code users
 
-1. **Start a new session**: Claude Code reads `CLAUDE.md` (symlink to `AGENTS.md`)
+1. **Start a new session**: Claude Code reads `AGENTS.md`
 2. **Use skills**: Type `/doc-write`, `/api-doc`, `/tutorial`, or `/review-docs`
 3. **Reference standards**: See `standards/` for detailed rules, `AGENTS.md` for summary
 
@@ -104,7 +104,7 @@ npm start            # Preview changes
 
 ## Best practices
 
-1. **Read `CLAUDE.md` first**
+1. **Read `AGENTS.md` first**
 2. **Check `standards/`** - Detailed rules for writing, formatting, terminology
 3. **Use the appropriate skill** - Designed for specific documentation tasks
 4. **Run linters before committing** - `npm run lint:md`, `npm run lint:code`, and `vale`

.markdownlintignore

@@ -3,7 +3,6 @@ build
 .claude
 .agents
 AGENTS.md
-CLAUDE.md
 GEMINI.md
 standards
 sources/_partials/*

AGENTS.md

@@ -90,6 +90,18 @@ schema:
   const: "constantValue"
 ```
 
+### Links to API endpoints
+
+Applies to every link to an API reference page, in the OpenAPI spec and in `sources/`:
+
+- Use the endpoint's current `summary` as the link text, exactly as written in the spec: `[Get dataset items](/api/v2/dataset-items-get)`, not `[List items](…)`, `[API](…)` or `[documentation](…)`. Keep "endpoint" or "API reference" outside the link: `use the [Run Actor](/api/v2/actors-runs-post) endpoint`
+- Exception for lists: when a sentence lists several related endpoints, you can shorten each link to the word that tells them apart, as long as the surrounding text names the resource. For example, `CRUD ([add](…), [get](…), [update](…), [delete](…)) operations on requests` or `endpoints for [Actors](…) and [tasks](…)`. A link to a single endpoint still uses its full summary
+- Link to an endpoint group page with that group's current title, for example `[Manage Actor runs](/api/v2/actor-runs)`
+- Link to the page path (`/api/v2/<page-id>`), never to legacy anchors such as `#/reference/...` or `#tag/.../operation/...`. Those anchors only exist on the target page itself, so they lead nowhere from any other page
+- When you rename an endpoint's `summary`, update the link text of every link to it across the repo (`grep -rn "/api/v2/<page-id>"`)
+- When two endpoints share a summary, add the path after the link to tell them apart
+- Exception: link text that has to match a name in another product, such as Bubble plugin action names, stays as it is
+
 ### Python API client model generation
 
 `apify-client-python` generates its Pydantic models from the **published** spec, and it pulls them on its own schedule - this repo does not push anything to it:

CONTRIBUTING.md

@@ -95,7 +95,7 @@ This project uses an agent-agnostic approach: standards and workflows live at th
 
 - **`standards/`** - Writing, formatting, terminology, and quality rules
 - **`.agents/skills/`** - Documentation skills with processes, references, and scripts (AgentSkills spec)
-- **`AGENTS.md`** - Condensed summary + pointers (also `CLAUDE.md` via symlink)
+- **`AGENTS.md`** - Condensed summary + pointers (also `GEMINI.md` via symlink)
 
 ### Skills (AgentSkills standard)
 

apify-api/openapi/components/objects/actor-runs/abort.yaml

@@ -56,7 +56,8 @@ byActorRunId:
   summary: Abort Actor run
   description: |
     **[DEPRECATED]** API endpoints related to run of the Actor were moved under
-    new namespace [`actor-runs`](#/reference/actor-runs). Aborts an Actor run and
+    new namespace `actor-runs`
+    ([Manage Actor runs](/api/v2/actor-runs)). Aborts an Actor run and
     returns an object that contains all the details about the run.
 
     Only runs that are starting or running are aborted. For runs with status
@@ -81,7 +82,7 @@ lastRunByActor:
     Aborts the last run of the specified Actor and returns an object that
     contains all the details about the run.
 
-    This endpoint is a shortcut for [Abort run](#/reference/actor-runs/abort-run/abort-run)
+    This endpoint is a shortcut for [Abort Actor run](/api/v2/actor-run-abort-post)
     on the Actor's last run. Only runs that are starting or running are aborted.
     For runs with status `FINISHED`, `FAILED`, `ABORTING` and `TIMED-OUT` this call
     does nothing.
@@ -101,7 +102,7 @@ lastRunByActorTask:
     Aborts the last run of the specified Actor task and returns an object that
     contains all the details about the run.
 
-    This endpoint is a shortcut for [Abort run](#/reference/actor-runs/abort-run/abort-run)
+    This endpoint is a shortcut for [Abort Actor run](/api/v2/actor-run-abort-post)
     on the Actor task's last run. Only runs that are starting or running are aborted.
     For runs with status `FINISHED`, `FAILED`, `ABORTING` and `TIMED-OUT` this call
     does nothing.

apify-api/openapi/components/objects/actor-runs/metamorph.yaml

@@ -81,7 +81,8 @@ byActorRunId:
   summary: Metamorph Actor run
   description: |
     **[DEPRECATED]** API endpoints related to run of the Actor were moved under
-    new namespace [`actor-runs`](#/reference/actor-runs). Transforms an Actor run
+    new namespace `actor-runs`
+    ([Manage Actor runs](/api/v2/actor-runs)). Transforms an Actor run
     into a run of another Actor with a new input.
 
     This is useful if you want to use another Actor to finish the work
@@ -120,7 +121,7 @@ lastRunByActor:
     Transforms the last run of the specified Actor into a run of another Actor with
     a new input.
 
-    This endpoint is a shortcut for [Metamorph run](#/reference/actor-runs/metamorph-run/metamorph-run)
+    This endpoint is a shortcut for [Metamorph Actor run](/api/v2/actor-run-metamorph-post)
     on the Actor's last run.
   operationId: actor_runs_last_metamorph_post
   parameters:
@@ -139,7 +140,7 @@ lastRunByActorTask:
     Transforms the last run of the specified Actor task into a run of another Actor with
     a new input.
 
-    This endpoint is a shortcut for [Metamorph run](#/reference/actor-runs/metamorph-run/metamorph-run)
+    This endpoint is a shortcut for [Metamorph Actor run](/api/v2/actor-run-metamorph-post)
     on the Actor task's last run.
   operationId: actorTask_runs_last_metamorph_post
   parameters:

apify-api/openapi/components/objects/actor-runs/reboot.yaml

@@ -57,7 +57,7 @@ lastRunByActor:
     Reboots the last run of the specified Actor and returns an object that
     contains all the details about the rebooted run.
 
-    This endpoint is a shortcut for [Reboot run](#/reference/actor-runs/reboot-run/reboot-run)
+    This endpoint is a shortcut for [Reboot Actor run](/api/v2/actor-run-reboot-post)
     on the Actor's last run. Only runs with status `RUNNING` can be rebooted. The run's
     container will be restarted, so any data not persisted in the key-value store, dataset,
     or request queue will be lost.
@@ -76,7 +76,7 @@ lastRunByActorTask:
     Reboots the last run of the specified Actor task and returns an object that
     contains all the details about the rebooted run.
 
-    This endpoint is a shortcut for [Reboot run](#/reference/actor-runs/reboot-run/reboot-run)
+    This endpoint is a shortcut for [Reboot Actor run](/api/v2/actor-run-reboot-post)
     on the Actor task's last run. Only runs with status `RUNNING` can be rebooted. The run's
     container will be restarted, so any data not persisted in the key-value store, dataset,
     or request queue will be lost.

apify-api/openapi/components/objects/actor-runs/resurrect.yaml

@@ -56,14 +56,15 @@
   x-py-name: resurrect
   x-py-doc-url: https://docs.apify.com/api/client/python/reference/class/RunClientAsync#resurrect
 
 byActorRunId:
   <<: *sharedResurrect
   tags:
     - Actors/Actor runs
   summary: Resurrect Actor run
   description: |
     **[DEPRECATED]** API endpoints related to run of the Actor were moved under
-    new namespace [`actor-runs`](#/reference/actor-runs).Resurrects a finished
+    new namespace `actor-runs`
+    ([Manage Actor runs](/api/v2/actor-runs)). Resurrects a finished
     Actor run and returns an object that contains all the details about the
     resurrected run.
 

apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}@env-vars@{envVarName}put.yaml

@@ -61,8 +61,8 @@ put:
   <<: *shared
   summary: Update environment variable in Actor version
   description: |
-    Updates Actor environment variable using values specified by a [EnvVar
-    object](#/reference/actors/environment-variable-object)
+    Updates Actor environment variable using values specified by an `EnvVar`
+    object
     passed as JSON in the POST payload.
     If the object does not define a specific property, its value will not be
     updated.
@@ -71,11 +71,11 @@ put:
     header!
 
     When providing your API authentication token, we recommend using the
-    request's `Authorization` header, rather than the URL. ([More
-    info](#/introduction/authentication)).
+    request's `Authorization` header, rather than the URL.
+    [Learn more](/api/v2/getting-started#authentication)
 
-    The response is the [EnvVar object](#/reference/actors/environment-variable-object) as returned by the
-    [Get environment variable](#/reference/actors/environment-variable-object/get-environment-variable)
+    The response is the `EnvVar` object as returned by the
+    [Get environment variable of Actor version](/api/v2/actor-version-env-var-get)
     endpoint.
   operationId: actor_version_envVar_put
   x-legacy-doc-urls:
@@ -87,10 +87,10 @@ post:
   <<: *shared
   summary: Update environment variable in Actor version (POST)
   description: |
-    Updates Actor environment variable using values specified by a [EnvVar
-    object](#/reference/actors/environment-variable-object)
+    Updates Actor environment variable using values specified by an `EnvVar`
+    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 [Update environment variable in Actor version](/api/v2/actor-version-env-var-put) endpoint 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

apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}put.yaml

@@ -57,7 +57,7 @@ put:
   <<: *shared
   summary: Update Actor version
   description: |
-    Updates Actor version using values specified by a [Version object](#/reference/actors/version-object) passed as JSON in the POST payload.
+    Updates Actor version using values specified by a `Version` object passed as JSON in the POST payload.
 
     If the object does not define a specific property, its value will not be
     updated.
@@ -66,11 +66,11 @@ put:
     header!
 
     When providing your API authentication token, we recommend using the
-    request's `Authorization` header, rather than the URL. ([More
-    info](#/introduction/authentication)).
+    request's `Authorization` header, rather than the URL.
+    [Learn more](/api/v2/getting-started#authentication)
 
-    The response is the [Version object](#/reference/actors/version-object) as
-    returned by the [Get version](#/reference/actors/version-object/get-version) endpoint.
+    The response is the `Version` object as
+    returned by the [Get Actor version](/api/v2/actor-version-get) endpoint.
   operationId: actor_version_put
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/actors/version-object/update-version
@@ -81,8 +81,8 @@ post:
   <<: *shared
   summary: Update Actor 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.
+    Updates Actor version using values specified by a `Version` object passed as JSON in the POST payload.
+    This endpoint is an alias for the [Update Actor version](/api/v2/actor-version-put) endpoint and behaves identically.
   operationId: actor_version_post
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/actors/version-object/update-version

apify-api/openapi/components/objects/datasets/dataset.yaml

@@ -63,7 +63,7 @@ getById:
     Returns dataset object for given dataset ID.
 
     This does not return dataset items, only information about the storage itself.
-    To retrieve dataset items, use the [List dataset items](/api/v2/dataset-items-get) endpoint.
+    To retrieve dataset items, use the [Get dataset items](/api/v2/dataset-items-get) endpoint.
 
     :::note
 
@@ -157,7 +157,7 @@ putDefault:
     Updates the default dataset associated with an Actor run.
 
     This endpoint is a shortcut for getting the run's `defaultDatasetId` and then using the
-    [Put dataset](/api/v2/dataset-put) endpoint.
+    [Update dataset](/api/v2/dataset-put) endpoint.
 
   operationId: actorRun_dataset_put
 
@@ -208,7 +208,7 @@ deleteDefault:
     Deletes default dataset associated with an Actor run.
 
     This endpoint is a shortcut for getting the last run's `defaultDatasetId` and then using the
-    [ Delete dataset ](/api/v2/dataset-delete) endpoint.
+    [Delete dataset](/api/v2/dataset-delete) endpoint.
   operationId: actorRun_dataset_delete
 
 deleteLastRun:

apify-api/openapi/components/objects/key-value-stores/key-value-store-record.yaml

@@ -102,7 +102,7 @@ getById:
     Gets a value stored in the key-value store under a specific key.
 
     The response body has the same `Content-Encoding` header as it was set in
-    [Put record](#tag/Key-value-storesRecord/operation/keyValueStore_record_put).
+    [Set key-value store record](/api/v2/key-value-store-record-put).
 
     If the request does not define the `Accept-Encoding` HTTP header with the
     right encoding, the record will be decompressed.
@@ -290,7 +290,7 @@ postById:
   description: |
     Stores a value under a specific key to the key-value store.
 
-    This endpoint is an alias for the [`PUT` record](#tag/Key-value-storesRecord/operation/keyValueStore_record_put) method and behaves identically.
+    This endpoint is an alias for the [Set key-value store record](/api/v2/key-value-store-record-put) endpoint and behaves identically.
   operationId: keyValueStore_record_post
   parameters:
     - $ref: "../../parameters/keyValueStoreParameters.yaml#/storeId"

apify-api/openapi/components/objects/key-value-stores/key-value-store-records.yaml

@@ -181,7 +181,7 @@ postById:
   summary: Store record (POST)
   description: |
     Stores a value under a specific key to the key-value store.
-    This endpoint is an alias for the [`PUT` record](#tag/Key-value-storesRecord/operation/keyValueStore_record_put) method and behaves identically.
+    This endpoint is an alias for the [Set key-value store record](/api/v2/key-value-store-record-put) endpoint and behaves identically.
   operationId: keyValueStore_record_post
   parameters:
     - $ref: "../../parameters/keyValueStoreParameters.yaml#/storeId"
@@ -195,7 +195,7 @@ putDefault:
     Stores a value under a specific key to the key-value store.
 
     This endpoint is a shortcut for getting the run's `defaultKeyValueStoreId` and then using the
-    [PUT record](/api/v2/key-value-store-record-put) endpoint.
+    [Set key-value store record](/api/v2/key-value-store-record-put) endpoint.
   operationId: keyValueStore_record_put
   parameters:
     - $ref: "../../parameters/runAndBuildParameters.yaml#/runId"
@@ -219,7 +219,7 @@ postDefault:
     Stores a value under a specific key to the key-value store.
 
     This endpoint is a shortcut for getting the run's `defaultKeyValueStoreId` and then using the
-    [POST record](/api/v2/key-value-store-record-post) endpoint.
+    [Set key-value store record (POST)](/api/v2/key-value-store-record-post) endpoint.
   operationId: keyValueStore_record_post
   parameters:
     - $ref: "../../parameters/runAndBuildParameters.yaml#/runId"
@@ -233,7 +233,7 @@ putLastRun:
     Stores a value under a specific key to the key-value store.
 
     This endpoint is a shortcut for getting the last run's `defaultKeyValueStoreId` and then using the
-    [PUT record](/api/v2/key-value-store-record-put) endpoint.
+    [Set key-value store record](/api/v2/key-value-store-record-put) endpoint.
   operationId: keyValueStore_record_put
   parameters:
     - $ref: "../../parameters/runAndBuildParameters.yaml#/actorId"
@@ -257,7 +257,7 @@ postLastRun:
     Stores a value under a specific key to the key-value store.
 
     This endpoint is a shortcut for getting the last run's `defaultKeyValueStoreId` and then using the
-    [POST record](/api/v2/key-value-store-record-post) endpoint.
+    [Set key-value store record (POST)](/api/v2/key-value-store-record-post) endpoint.
   operationId: keyValueStore_record_post
   parameters:
     - $ref: "../../parameters/runAndBuildParameters.yaml#/actorId"
@@ -271,7 +271,7 @@ putTaskLastRun:
     Stores a value under a specific key to the default key-value store of the last Actor task run.
 
     This endpoint is a shortcut for getting the last task run's `defaultKeyValueStoreId` and then using the
-    [PUT record](/api/v2/key-value-store-record-put) endpoint.
+    [Set key-value store record](/api/v2/key-value-store-record-put) endpoint.
   operationId: actorTask_runs_last_keyValueStore_records_put
   parameters:
     - $ref: "../../parameters/runAndBuildParameters.yaml#/actorTaskId"
@@ -285,7 +285,7 @@ postTaskLastRun:
     Stores a value under a specific key to the default key-value store of the last Actor task run.
 
     This endpoint is a shortcut for getting the last task run's `defaultKeyValueStoreId` and then using the
-    [POST record](/api/v2/key-value-store-record-post) endpoint.
+    [Set key-value store record (POST)](/api/v2/key-value-store-record-post) endpoint.
   operationId: actorTask_runs_last_keyValueStore_records_post
   parameters:
     - $ref: "../../parameters/runAndBuildParameters.yaml#/actorTaskId"

apify-api/openapi/components/objects/key-value-stores/key-value-store.yaml

@@ -132,8 +132,7 @@ putById:
     Updates a key-value store's name and general resource access level using a value specified by a JSON object
     passed in the PUT payload.
 
-    The response is the updated key-value store object, as returned by the [Get
-    store](#/reference/key-value-stores/store-object/get-store) API endpoint.
+    The response is the updated key-value store object, as returned by the [Get key-value store](/api/v2/key-value-store-get) API endpoint.
   operationId: keyValueStore_put
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/key-value-stores/store-object/update-store

apify-api/openapi/components/objects/request-queues/request-queue.yaml

@@ -131,7 +131,7 @@ putById:
     passed in the PUT payload.
 
     The response is the updated request queue object, as returned by the
-    [Get request queue](#/reference/request-queues/queue-collection/get-request-queue) API endpoint.
+    [Get request queue](/api/v2/request-queue-get) API endpoint.
   operationId: requestQueue_put
   x-legacy-doc-urls:
     - https://docs.apify.com/api/v2#/reference/request-queues/queue/update-request-queue

apify-api/openapi/components/parameters/requestQueueParameters.yaml

@@ -27,8 +27,7 @@ clientKey:
     determine whether the queue was accessed by multiple clients. If
     `clientKey` is not provided,
     the system considers this API call to come from a new client. For
-    details, see the `hadMultipleClients` field returned by the [Get
-    head](#/reference/request-queues/queue-head) operation.
+    details, see the `hadMultipleClients` field returned by the [Get request queue head](/api/v2/request-queue-head-get) endpoint.
   style: form
   explode: true
   schema:

apify-api/openapi/components/securitySchemes/httpBearer.yaml

@@ -1,7 +1,7 @@
 type: http
 scheme: bearer
 description: |-
-  Bearer token provided in the `Authorization` header (e.g., `Authorization: Bearer your_token`—recommended). [More info](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization).
+  Bearer token provided in the `Authorization` header (e.g., `Authorization: Bearer your_token`—recommended). [Learn more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)
 
   Use your API token to authenticate requests. You can find it on the [Integrations page](https://console.apify.com/account#/integrations) in Apify Console. This method is more secure than query parameters, as headers are not logged in browser history or server logs.