docs(openapi): Autofix OpenAPI spec validation errors

[Pijukatel]

Summary

Autogenerated OpenAPI fixes suggestions based on validation errors generated from running API integration tests with OpenAPI validator turned on.

Error log: Production OpenAPI response-validation errors from apify-api (Jul 8, 2026)

apify-core version: https://github.com/apify/apify-core/commit/abeddcb4b7b3dee66ea2169435153144dae91c19

Detailed changes description

Error fixes

Missing 402 on Actor task run endpoints

Files: apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@runs.yaml (post.responses), apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync-get-dataset-items.yaml (get.responses, post.responses)
Error: no schema defined for status code '402' in the openapi spec (POST /v2/actor-tasks/{actorTaskId}/runs, GET /v2/actor-tasks/{actorTaskId}/run-sync-get-dataset-items)
Root cause: Task run creation goes through run-limit checks that throw notEnoughUsageToRunPaidActor / memory / concurrency errors with HTTP 402. Both run-sync variants launch a run and hit the same checks.
Reference: https://github.com/apify/apify-core/tree/abeddcb4b7b3dee66ea2169435153144dae91c19/src/packages/actor-server/src/actor_jobs/run_limits_helper.ts#L194

Missing 402 on storage read endpoints (x402 payment reuse)

Files: apify-api/openapi/components/objects/datasets/dataset.yaml, .../datasets/dataset-statistics.yaml, .../datasets/dataset-items.yaml, .../key-value-stores/key-value-store.yaml, .../key-value-stores/key-value-store-keys.yaml, .../key-value-stores/key-value-store-record.yaml, .../request-queues/request-queue.yaml, .../request-queues/request-queue-head.yaml, .../request-queues/request-queue-requests.yaml, .../request-queues/request-queue-request.yaml (all in the shared GET response blocks)
Error: no schema defined for status code '402' in the openapi spec (observed on GET /v2/datasets/{datasetId}/items; applies to storage reads generally)
Root cause: The agentic-payment middleware runs on every request, but only emits 402 when the caller participates in x402 payment. A new x402 payment must be initiated on an Actor execution route; reusing an already-initiated payment to read a run's results is permitted on any route, and the reuse check returns 402 on a non-execution (storage) route. Consequently any storage GET (read) can return 402. 402 was added to the shared GET blocks of datasets, key-value stores, and request queues - read operations only, not writes - which also covers the default and last-run storage variants (e.g. /v2/actor-runs/{runId}/dataset/items).
Reference: https://github.com/apify/apify-core/tree/abeddcb4b7b3dee66ea2169435153144dae91c19/src/packages/agentic-payments/src/x402/x402_client.ts#L873

Missing 401 on POST /v2/actors/{actorId}/run-sync-get-dataset-items

Files: apify-api/openapi/paths/actors/acts@{actorId}@run-sync-get-dataset-items.yaml (post.responses)
Error: no schema defined for status code '401' in the openapi spec (POST /v2/actors/{actorId}/run-sync-get-dataset-items)
Root cause: The operation inherits global bearer/api-key security; an invalid token is rejected with 401 by the auth middleware. The GET sibling already documented 401, the POST did not.
Reference: https://github.com/apify/apify-core/tree/abeddcb4b7b3dee66ea2169435153144dae91c19/src/api/src/routes/routes_config.ts#L648

Missing 401 on GET /v2/store

Files: apify-api/openapi/paths/store/store.yaml (get.responses)
Error: no schema defined for status code '401' in the openapi spec (GET /v2/store)
Root cause: The global auth middleware validates any supplied token before the route runs, so passing an invalid token to store search returns 401.
Reference: https://github.com/apify/apify-core/tree/abeddcb4b7b3dee66ea2169435153144dae91c19/src/api/src/middleware/authentication.ts#L91

Missing 401 on GET /v2/actors/{actorId}/builds/default

Files: apify-api/openapi/paths/actors/acts@{actorId}@builds@default.yaml (get.responses)
Error: no schema defined for status code '401' in the openapi spec (GET /v2/actors/{actorId}/builds/default)
Root cause: Although the endpoint does not require a token (security: []), the auth middleware still validates any token that is supplied and returns 401 for an invalid one - the same reason the file already documents 403. security: [] is left unchanged; only the response is documented.
Reference: https://github.com/apify/apify-core/tree/abeddcb4b7b3dee66ea2169435153144dae91c19/src/api/src/routes/routes_config.ts#L521

options.maxTotalChargeUsd must be nullable

Files: apify-api/openapi/components/schemas/actor-runs/RunOptions.yaml
Error: type.openapi.validation: must be number at /response/data/options/maxTotalChargeUsd (POST /v2/actor-runs/{runId}/abort)
Root cause: maxTotalChargeUsd is an optional run option that is only stored when truthy, so runs created without it surface null. Changed to type: [number, "null"] to match the sibling maxItems field.
Reference: https://github.com/apify/apify-core/tree/abeddcb4b7b3dee66ea2169435153144dae91c19/src/packages/schemas/src/actors.ts#L97

options.maxItems minimum lowered to 0

Files: apify-api/openapi/components/schemas/actor-runs/RunOptions.yaml
Error: minimum.openapi.validation: must be >= 1 at /response/data/options/maxItems (POST /v2/actor-runs/{runId}/resurrect)
Root cause: The API defines maxItems with min 0 and treats 0 as a valid sentinel; the spec's minimum: 1 was stricter than the API. Lowered to 0.
Reference: https://github.com/apify/apify-core/tree/abeddcb4b7b3dee66ea2169435153144dae91c19/src/packages/schemas/src/actors.ts#L94

stats.deleteCount / stats.listCount no longer required

Files: apify-api/openapi/components/schemas/key-value-stores/KeyValueStoreStats.yaml
Error: required.openapi.validation: must have required property 'deleteCount' / 'listCount' at /response/data/stats (POST /v2/key-value-stores)
Root cause: The stats serializer picks only present fields and the DB marks every counter optional, so a pre-existing (get-or-create) store can omit deleteCount/listCount. Removed them from required.
Reference: https://github.com/apify/apify-core/tree/abeddcb4b7b3dee66ea2169435153144dae91c19/src/api/src/lib/key_value_stores.ts#L682

proxy no longer required on GET /v2/users/me

Files: apify-api/openapi/components/schemas/users/UserPrivateInfo.yaml
Error: required.openapi.validation: must have required property 'proxy' at /response/data/proxy (GET /v2/users/me)
Root cause: proxy is only attached when the user has proxy USE permission; otherwise the key is omitted. Removed from required.
Reference: https://github.com/apify/apify-core/tree/abeddcb4b7b3dee66ea2169435153144dae91c19/src/api/src/routes/users/user.ts#L84

requestUrl must be nullable

Files: apify-api/openapi/components/schemas/webhooks/Webhook.yaml
Error: type.openapi.validation: must be string at /response/data/requestUrl (GET /v2/webhooks/{webhookId}, POST /v2/webhooks)
Root cause: requestUrl is modeled as nullish and is only meaningful for HTTP-request webhooks; other action types (Slack, email, etc.) return null. Changed to type: [string, "null"].
Reference: https://github.com/apify/apify-core/tree/abeddcb4b7b3dee66ea2169435153144dae91c19/src/packages/zod-types/src/common/webhooks.ts#L57

currentPricingInfo no longer required on store items

Files: apify-api/openapi/components/schemas/store/StoreListActor.yaml
Error: required.openapi.validation: must have required property 'currentPricingInfo' at /response/data/items/{i}/currentPricingInfo (GET /v2/store)
Root cause: The Recombee-backed store search maps items without a currentPricingInfo field, so it is not guaranteed. Removed from required.
Reference: https://github.com/apify/apify-core/tree/abeddcb4b7b3dee66ea2169435153144dae91c19/src/packages/actor-server/src/recombee/recombee_store_search.ts#L183

notice must be nullable (store items and actor)

Files: apify-api/openapi/components/schemas/store/StoreListActor.yaml, apify-api/openapi/components/schemas/actors/Actor.yaml
Error: type.openapi.validation: must be string at /response/data/items/{i}/notice (GET /v2/store) and /response/data/notice (GET /v2/actors/{actorId})
Root cause: notice is modeled as string | null in the data layer and coalesced to null when absent. Made nullable in both (independent) schemas.
Reference: https://github.com/apify/apify-core/tree/abeddcb4b7b3dee66ea2169435153144dae91c19/src/packages/types/src/recombee.ts#L34

Issues

Partially implements: #2286

[apify-service-account]

🗑️ Preview for this PR was deleted.

[apify-service-account]

Important

Action required — @Pijukatel 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#936

• 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.

[vdusek]

🚀