docs(openapi): Extract and re-use parameters defined in paths

[Pijukatel]

Summary

• Add Agents directives about changes in the OpenAPI spec
• Re-use previously extracted parameters in remaining paths
• Extract and re-use non-unique remaining parameters where possible
• Remove incorrect pagination query parameters in apify-api/openapi/paths/webhooks/webhooks.yaml
• Log-related options stream and download should be optional

Motivation

• Preparation for adding undocumented redispatch endpoints, which will re-use the error schemas and parameters.
• Make the specification more maintainable

Issues

Partially implements: #2286

[apify-service-account]

Preview for this PR was built for commit 7619b8f5 and is ready at https://pr-2324.preview.docs.apify.com!

[apify-service-account]

Preview for this PR was built for commit 31130a16 and is ready at https://pr-2324.preview.docs.apify.com!

[Copilot]

Pull request overview

Refactors the Apify API OpenAPI specification to reduce duplication by extracting common path/query parameters into reusable $ref components, and consolidates/moves some examples into schema components to keep path definitions leaner.

Changes:

• Replaced many inline parameter definitions across /openapi/paths with shared $ref components (pagination, run/build options, dataset items options, log options).
• Added new reusable parameter component files (runAndBuildOptions.yaml, DatasetItemsParameters.yaml, logOptions.yaml) and extended PaginationParameters.yaml.
• Moved some response examples from path files into shared schema components and updated AGENTS.md with OpenAPI editing guidance.

Reviewed changes

Copilot reviewed 60 out of 60 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
apify-api/openapi/paths/webhooks/webhooks@{webhookId}@test.yaml	Replaced inline webhookId parameter with shared $ref.
apify-api/openapi/paths/webhooks/webhooks@{webhookId}@dispatches.yaml	Replaced inline webhookId parameter with shared $ref.
apify-api/openapi/paths/webhooks/webhooks@{webhookId}.yaml	Replaced inline webhookId parameters (GET/PUT/DELETE) with shared $ref.
apify-api/openapi/paths/webhooks/webhooks.yaml	Replaced pagination query params with shared PaginationParameters refs; removed unused POST params.
apify-api/openapi/paths/webhook-dispatches/webhook-dispatches.yaml	Replaced pagination query params with shared PaginationParameters refs.
apify-api/openapi/paths/store/store.yaml	Switched limit/offset to shared pagination refs; moved large example out of the path response.
apify-api/openapi/paths/schedules/schedules@{scheduleId}@log.yaml	Replaced inline scheduleId parameter with shared $ref.
apify-api/openapi/paths/schedules/schedules@{scheduleId}.yaml	Replaced inline scheduleId parameters (GET/PUT/DELETE) with shared $ref.
apify-api/openapi/paths/schedules/schedules.yaml	Replaced pagination query params with shared PaginationParameters refs.
apify-api/openapi/paths/logs/logs@{buildOrRunId}.yaml	Replaced inline log query params with shared logOptions refs.
apify-api/openapi/paths/datasets/datasets@{datasetId}@items.yaml	Replaced many dataset items query params with shared DatasetItemsParameters refs.
apify-api/openapi/paths/actors/acts@{actorId}@webhooks.yaml	Replaced inline actorId + pagination params with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@versions@{versionNumber}@env-vars@{envVarName}.yaml	Replaced inline actorId/versionNumber params with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@versions@{versionNumber}@env-vars.yaml	Replaced inline actorId/versionNumber params with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@versions@{versionNumber}.yaml	Replaced inline actorId/versionNumber params with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@versions.yaml	Replaced inline actorId param with shared ref.
apify-api/openapi/paths/actors/acts@{actorId}@runs@last.yaml	Replaced inline actorId and status params with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@Runs@{runId}@resurrect.yaml	Replaced inline actorId/runId with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@Runs@{runId}@metamorph.yaml	Replaced inline actorId/runId/targetActorId with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@Runs@{runId}@abort.yaml	Replaced inline actorId/runId/gracefully with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@Runs@{runId}.yaml	Replaced inline actorId/runId/waitForFinish with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@runs.yaml	Replaced many run collection params with shared refs (pagination + run/build options).
apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml	Replaced inline run-sync params with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@run-sync-get-dataset-items.yaml	Replaced inline run params + dataset-item params with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@builds@default.yaml	Replaced inline actorId/waitForFinish with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@builds@{buildId}@openapi.json.yaml	Replaced inline actorId/buildId with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@builds@{buildId}@abort.yaml	Replaced inline actorId/buildId with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@builds@{buildId}.yaml	Replaced inline actorId/buildId/waitForFinish with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}@builds.yaml	Replaced inline actorId + pagination params + waitForFinish with shared refs.
apify-api/openapi/paths/actors/acts@{actorId}.yaml	Replaced inline actorId parameters (GET/PUT/DELETE) with shared ref.
apify-api/openapi/paths/actors/acts.yaml	Replaced inline pagination query params with shared PaginationParameters refs.
apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@webhooks.yaml	Replaced inline actorTaskId + pagination params with shared refs.
apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last.yaml	Replaced inline actorTaskId/status with shared refs.
apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@runs.yaml	Replaced many task-run params with shared refs (pagination + run/build options); removed a large inline example.
apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml	Replaced inline run-sync params with shared refs.
apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync-get-dataset-items.yaml	Replaced inline run params + dataset-item params with shared refs.
apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@input.yaml	Replaced inline actorTaskId params (GET/PUT) with shared ref.
apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}.yaml	Replaced inline actorTaskId params (GET/PUT/DELETE) with shared ref; removed inline examples.
apify-api/openapi/paths/actor-tasks/actor-tasks.yaml	Replaced inline pagination params with shared PaginationParameters refs.
apify-api/openapi/paths/actor-runs/actor-runs@{runId}@resurrect.yaml	Replaced resurrect endpoint params with shared run/build option refs.
apify-api/openapi/paths/actor-runs/actor-runs@{runId}@reboot.yaml	Replaced inline runId param with shared ref.
apify-api/openapi/paths/actor-runs/actor-runs@{runId}@metamorph.yaml	Replaced inline runId/targetActorId with shared refs.
apify-api/openapi/paths/actor-runs/actor-runs@{runId}@charge.yaml	Replaced inline runId with shared ref.
apify-api/openapi/paths/actor-runs/actor-runs@{runId}@abort.yaml	Replaced inline runId/gracefully with shared refs.
apify-api/openapi/paths/actor-runs/actor-runs@{runId}.yaml	Replaced inline runId/waitForFinish with shared refs across operations.
apify-api/openapi/paths/actor-runs/actor-runs.yaml	Replaced inline pagination/status/time filters with shared refs.
apify-api/openapi/paths/actor-builds/actor-builds@{buildId}@openapi.json.yaml	Replaced inline buildId param with shared ref.
apify-api/openapi/paths/actor-builds/actor-builds@{buildId}@log.yaml	Replaced inline buildId/log options with shared refs.
apify-api/openapi/paths/actor-builds/actor-builds@{buildId}@abort.yaml	Replaced inline buildId param with shared ref.
apify-api/openapi/paths/actor-builds/actor-builds@{buildId}.yaml	Replaced inline buildId/waitForFinish with shared refs.
apify-api/openapi/paths/actor-builds/actor-builds.yaml	Replaced inline pagination params with shared PaginationParameters refs.
apify-api/openapi/components/schemas/store/ListOfActorsInStoreResponse.yaml	Added schema-level example (migrated from path response).
apify-api/openapi/components/schemas/actor-tasks/TaskResponse.yaml	Added schema-level example.
apify-api/openapi/components/parameters/runAndBuildOptions.yaml	New shared parameter component file for actor/run/build/task/webhook/schedule IDs and run/build options.
apify-api/openapi/components/parameters/PaginationParameters.yaml	Added DescStartedAt and DescCreatedAt reusable params.
apify-api/openapi/components/parameters/logOptions.yaml	New shared parameter component file for log query options.
apify-api/openapi/components/parameters/DatasetItemsParameters.yaml	New shared parameter component file for dataset items query options.
apify-api/openapi/components/parameters/actor-run-options/maxTotalChargeUsd.yaml	Deleted (moved into runAndBuildOptions.yaml).
apify-api/openapi/components/parameters/actor-run-options/maxItems.yaml	Deleted (moved into runAndBuildOptions.yaml).
AGENTS.md	Added guidance for OpenAPI spec changes (reuse via $ref, prefer auto examples, etc.).

[apify-service-account]

Preview for this PR was built for commit 4d1a593d and is ready at https://pr-2324.preview.docs.apify.com!

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 77 out of 77 changed files in this pull request and generated 4 comments.

[apify-service-account]

Preview for this PR was built for commit f4fcc16e and is ready at https://pr-2324.preview.docs.apify.com!