[Pijukatel]

Summary

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

Replaces #3200, which GitHub closed after a branch force-push and will not reopen.

Error log: Production response-validation log exported from Mezmo (6d31d9db-errors, 318 lines, Oct 30 – Nov 6 2026), supplied manually. There is no public link; the log is not reproducible in the PR test environment.

apify-core version: https://github.com/apify/apify-core/tree/8870ffca6640f3f60e8aeaee328a13f3ac90d8c4 (develop at the time the log was processed)

Stop reason: The scope of this iteration was limited to endpoints that are completely missing from the spec. Of the three such endpoints in the log, only GET /v2/openapi.json belongs in the public reference and is added here. The deprecated direct-upload-url endpoint and the internal POST /v2/meta/github-leaked-tokens webhook stay undocumented on purpose, and the remaining "not found" errors are malformed URLs that Express serves leniently. All of these are skipped in the validator instead, see the companion apify-core branch claude/funny-ptolemy-phf4wv (commits https://github.com/apify/apify-core/commit/753b48854aa744d6040d3f0822464fec91f1fc98 and https://github.com/apify/apify-core/commit/e72e879303adb3f4bcfb74d6e6182c5bd4e8324f). All other errors in the log are schema errors on existing endpoints and are listed below without fixes.

The PR test environment was not run for this change (push to the validator branch was not available in this session). Regression check was done statically: the bundled openapi.json built from this branch differs from the one built from master only by the added path and the added tag (OpenAPI). Every pre-existing path, schema, tag and tag group is unchanged. pnpm openapi:lint passes.

Detailed changes description

Error fixes

Add missing GET /v2/openapi.json

• Files: apify-api/openapi/paths/tools/openapi.json.yaml:1, apify-api/openapi/openapi.yaml:808, apify-api/openapi/components/tags.yaml:450, apify-api/openapi/components/x-tag-groups.yaml:46
• Error: {"errors":[{"message":"not found","path":"/v2/openapi.json"}],"method":"GET","msg":"Response OpenAPI validation error","rt":"misc.openApi","statusCode":200.0,"url":"/v2/openapi.json"} (2 occurrences, plus 1 with "statusCode":304.0)
• Root cause: The public, unauthenticated misc.openApi route returns the bundled OpenAPI definition, but the spec had no path for it. The handler sends the document with Express res.send, which adds an ETag header and answers a matching If-None-Match with an empty 304, so both 200 and 304 are documented. A new OpenAPI tag is added to the "Utility tools" tag group, because the docs site generates pages per tag group and an operation without a grouped tag would get no page.
• Reference: https://github.com/apify/apify-core/tree/8870ffca6640f3f60e8aeaee328a13f3ac90d8c4/src/api/src/routes/misc/openapi.ts#L17 and https://github.com/apify/apify-core/tree/8870ffca6640f3f60e8aeaee328a13f3ac90d8c4/src/api/src/routes/routes_config.ts#L1398

Refactoring

None.

Unfixed errors

False positives

Requests with a doubled slash after /v2 reported as "not found" (88 occurrences)

• Error: {"errors":[{"message":"not found","path":"/v2//datasets/{datasetId}/items"}],"method":"GET","msg":"Response OpenAPI validation error","rt":"datasets.items","statusCode":200.0,"url":"/v2//datasets/{datasetId}/items?format=json&token=[REDACTED]"} and the same pattern for actorTasks.actorTaskRunList, logs.log, actors.runList, actorRuns.runList, datasets.dataset, users.user, datasets.datasetList, actorTasks.actorTask.
• Root cause: The clients sent URLs such as /v2//datasets/... (the logged url is req.originalUrl, which internal rewrites never change). Express mounts the API router with app.use('/v2', ...), and its mount matching consumes the optional slash after the prefix, so /v2//datasets/x reaches the router as /datasets/x and is served normally. The validator middleware runs at app level before that mount and express-openapi-validator 5.6.2 matches spec routes by regex against the raw req.originalUrl, so /v2//datasets/x matches nothing. The spec cannot and should not describe doubled slashes. Handled in apify-core: the validator now skips URLs with repeated slashes (https://github.com/apify/apify-core/commit/753b48854aa744d6040d3f0822464fec91f1fc98).
• Reference: https://github.com/apify/apify-core/tree/8870ffca6640f3f60e8aeaee328a13f3ac90d8c4/src/api/src/middleware/openapi_validation.ts#L206 and https://github.com/apify/apify-core/tree/8870ffca6640f3f60e8aeaee328a13f3ac90d8c4/src/api/src/lib/api_server.ts#L147

Misspelled runs/last-successded served as runs/last (3 occurrences)

• Error: {"errors":[{"message":"not found","path":"/v2/actors/apify~facebook-marketplace-scraper/runs/last-successded/dataset/items"}],"method":"GET","msg":"Response OpenAPI validation error","rt":"datasets.items","statusCode":200.0,"url":"/v2/actors/apify~facebook-marketplace-scraper/runs/last-successded/dataset/items?token=[REDACTED]"}
• Root cause: The last-run router is registered with the Express path /actors/:actorId/runs/last* (and /actor-tasks/:actorTaskId/runs/last*), so any segment starting with last is served as last. The spec documents only runs/last, which is the intended contract. Handled in apify-core: the validator now skips paths with a suffix glued to runs/last (https://github.com/apify/apify-core/commit/753b48854aa744d6040d3f0822464fec91f1fc98). Tightening the route pattern itself is a separate decision, see Potential API bugs.
• Reference: https://github.com/apify/apify-core/tree/8870ffca6640f3f60e8aeaee328a13f3ac90d8c4/src/api/src/routes/routes_config.ts#L415 and https://github.com/apify/apify-core/tree/8870ffca6640f3f60e8aeaee328a13f3ac90d8c4/src/api/src/routes/routes_config.ts#L329

Paths with a URL-encoded query string (...runs/last/dataset/items%3Ftoken%3D..., 8 occurrences, 401)

• Error: {"errors":[{"message":"not found","path":"/v2/actor-tasks/{actorTaskId}/runs/last/dataset/items%3Ftoken%3D[REDACTED]"}],"method":"GET","msg":"Response OpenAPI validation error","rt":"actorTasks.runLastRouter","statusCode":401.0,"url":"/v2/actor-tasks/{actorTaskId}/runs/last/dataset/items%3Ftoken%3D[REDACTED]"}
• Root cause: The client percent-encoded the ? of its query string, so the token became part of the last path segment and the request was rejected with 401. Client bug, nothing to document. Handled in apify-core: the validator now skips paths containing a percent-encoded ? (https://github.com/apify/apify-core/commit/753b48854aa744d6040d3f0822464fec91f1fc98).
• Reference: https://github.com/apify/apify-core/tree/8870ffca6640f3f60e8aeaee328a13f3ac90d8c4/src/api/src/routes/routes_config.ts#L329

POST /v2/meta/github-leaked-tokens (2 occurrences, 204)

• Error: {"errors":[{"message":"not found","path":"/v2/meta/github-leaked-tokens"}],"method":"POST","msg":"Response OpenAPI validation error","rt":"meta.githubLeakedTokens","statusCode":204.0,"url":"/v2/meta/github-leaked-tokens"}
• Root cause: This is the GitHub secret-scanning partner webhook: GitHub calls it with a signed payload and nothing else can use it. It is intentionally not part of the public API reference, so it is not added to the spec. Handled in apify-core: /v2/meta is now on the validator's list of paths intentionally absent from the spec (https://github.com/apify/apify-core/commit/753b48854aa744d6040d3f0822464fec91f1fc98).
• Reference: https://github.com/apify/apify-core/tree/8870ffca6640f3f60e8aeaee328a13f3ac90d8c4/src/api/src/routes/meta/github_leaked_tokens.ts#L82 and https://github.com/apify/apify-core/tree/8870ffca6640f3f60e8aeaee328a13f3ac90d8c4/src/api/src/middleware/openapi_validation.ts#L208

GET /v2/key-value-stores/{storeId}/records/{recordKey}/direct-upload-url (56 occurrences, 201)

• Error: {"errors":[{"message":"not found","path":"/v2/key-value-stores/{storeId}/records/{recordKey}/direct-upload-url"}],"method":"GET","msg":"Response OpenAPI validation error","rt":"keyValueStores.recordDirectUploadUrl","statusCode":201.0,"url":"/v2/key-value-stores/{storeId}/records/{recordKey}/direct-upload-url?token=[REDACTED]"}
• Root cause: The route is deprecated: the API no longer issues signed upload URLs and the handler only returns the Set key-value store record endpoint URL with the token in the query, plus the raw store document, so that old clients keep working. It is intentionally not part of the public API reference. Handled in apify-core: the validator now skips this endpoint (https://github.com/apify/apify-core/commit/e72e879303adb3f4bcfb74d6e6182c5bd4e8324f).
• Reference: https://github.com/apify/apify-core/tree/8870ffca6640f3f60e8aeaee328a13f3ac90d8c4/src/api/src/routes/key_value_stores/record_direct_upload_url.ts#L51 and https://github.com/apify/apify-core/tree/8870ffca6640f3f60e8aeaee328a13f3ac90d8c4/src/api/src/routes/routes_config.ts#L234

Potential API bugs

runs/last* wildcard routes accept arbitrary suffixes

• Error: same runs/last-successded error as above.
• Root cause: The last* route pattern makes a typo in the URL silently return the last run's data. The pattern should probably only accept last followed by / or the end of the path.
• Reference: https://github.com/apify/apify-core/tree/8870ffca6640f3f60e8aeaee328a13f3ac90d8c4/src/api/src/routes/routes_config.ts#L415

direct-upload-url returns the raw store document and 201 on a GET

• Error: same direct-upload-url error as above.
• Root cause: Unlike Get key-value store, the handler returns the store exactly as read from the database, without transformObject and the published-fields projection, so the response carries _id instead of id and internal fields such as nameLowerCase, accessibleByUserIds, statsAccounted, schemaHash and raw stats. It also answers 201 Created to a GET that creates nothing, which is not what RFC 9110 §15.3.2 describes.
• Reference: https://github.com/apify/apify-core/tree/8870ffca6640f3f60e8aeaee328a13f3ac90d8c4/src/api/src/routes/key_value_stores/record_direct_upload_url.ts#L51

Out of scope errors

Schema errors on existing endpoints (not in this iteration's scope)

• Error: GET /v2/store must be string at /response/data/items/{n}/categories/0 (126) and must be array at /response/data/items/{n}/categories (24); GET /v2/actors/{actorId} must be string at /response/data/categories/0 (1); GET /v2/request-queues/{queueId} and POST /v2/request-queues must be >= 0 at /response/data/totalRequestCount (26); POST /v2/actors no schema defined for status code '409' (7); POST /v2/actor-runs/{runId}/reboot and /metamorph must be string at /response/data/integrationTracking/appId (7); POST /v2/actor-runs/{runId}/abort meta.origin not in enum (2); GET /v2/store no schema defined for status code '402' (1); GET /v2/actors/{actorId}/versions/0.0 must be array at /response/data/sourceFiles (1).
• Root cause: These are property-level schema mismatches on endpoints that already exist in the spec. This iteration was explicitly limited to completely missing endpoints, so they are left for a follow-up.

Issues

Partially implements: #2286

---

Generated by Claude Code

[apify-service-account]

🗑️ Preview for this PR was deleted.

[apify-service-account]

API behavior and specification alignment:

• 401 is not documented: the endpoint needs no token, but a request that carries an invalid token gets rejected. Request: GET /v2/openapi.json?token=<invalid> (same with Authorization: Bearer <invalid>). Response: 401 {"error":{"type":"user-or-token-not-found","message":"User was not found or authentication token is not valid"}}

Reviewed commit: 484c960