Skip to content

docs(openapi): Autofix OpenAPI spec validation errors #2403

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Pijukatel merged 12 commits into from
Apr 13, 2026
Merged

docs(openapi): Autofix OpenAPI spec validation errors #2403

Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
ecbb1b1
fix(openapi): fix pricingInfo oneOf, version delete 404, maxItems typ…
claude Apr 8, 2026
1d46f4b
fix(openapi): fix KV store record GET response content type overlap
claude Apr 8, 2026
dbf3175
fix(openapi): revert KV store fix, fix sourceFiles required fields, r…
claude Apr 8, 2026
2cc6a7d
fix(openapi): fix content types, required fields, parameter serializa…
claude Apr 9, 2026
84e88e9
fix(openapi): add waitForFinish to actor-tasks runs/last, add identit…
claude Apr 9, 2026
0b907d7
fix(openapi): add missing view parameter to run-sync-get-dataset-item…
claude Apr 9, 2026
d779733
Merge branch 'master' into claude/fix-openapi-autofixes-U0Wy4
vdusek Apr 9, 2026
cb46377
Add syntax hint about const for agents
Pijukatel Apr 9, 2026
63945b4
refactor(openapi): replace single-item enums with const
claude Apr 9, 2026
c312f9d
Merge branch 'master' into claude/fix-openapi-autofixes-U0Wy4
vdusek Apr 9, 2026
775e660
Remove unused `PricingModel.yaml`
Pijukatel Apr 10, 2026
56d8aa3
Merge remote-tracking branch 'origin/master' into claude/fix-openapi-…
Pijukatel Apr 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,22 @@ Add code samples by creating files in `apify-api/openapi/code_samples/{javascrip
- Each endpoint that has `runs/last` in its path or that has any ID related parameter (for example `actorId`, `buildId`, `runId`, `datasetId` and so on) should have at least one 404 (Not Found) error.
- Each endpoint that has `requestBody` should have at least following error responses: 413 (Payload Too Large), 415 (Unsupported Media Type).

#### Syntax hints
- Instead of using one item `enum`, use `const`:
Avoid this:
```yaml
schema:
type: string
enum:
- "constantValue"
```
Use this:
```yaml
schema:
type: string
const: "constantValue"
```

### Theme system

Uses `@apify/docs-theme` package - a shared theme across all 6+ documentation repos. Don't modify theme files directly. Changes to the theme propagate via CI to all projects.
Expand Down
1 change: 1 addition & 0 deletions ...omponents/objects/key-value-stores/key-value-stores@{storeId}@records@{recordKey}put.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ shared: &shared
- gzip
- deflate
- br
- identity
type: string
requestBody:
description: ""
Expand Down
11 changes: 11 additions & 0 deletions apify-api/openapi/components/parameters/datasetItemsParameters.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,17 @@ descDataset:
type: boolean
example: true

view:
name: view
in: query
description: |
Defines the view configuration for dataset items based on the schema definition.
This parameter determines how the data will be filtered and presented.
For complete specification details, see the [dataset schema documentation](/platform/actors/development/actor-definition/dataset-schema).
schema:
type: string
example: overview

skipFailedPages:
name: skipFailedPages
in: query
Expand Down
10 changes: 7 additions & 3 deletions apify-api/openapi/components/parameters/runAndBuildParameters.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,10 +258,12 @@ status:
Single status or comma-separated list of statuses, see ([available
statuses](https://docs.apify.com/platform/actors/running/runs-and-builds#lifecycle)). Used to filter runs by the specified statuses only.
style: form
explode: true
explode: false
schema:
type: string
example: SUCCEEDED
type: array
items:
type: string
example: [SUCCEEDED]

startedAfter:
name: startedAfter
Expand All @@ -271,6 +273,7 @@ startedAfter:
The value must be a valid ISO 8601 datetime string (UTC).
style: form
explode: true
allowReserved: true
schema:
type: string
format: date-time
Expand All @@ -284,6 +287,7 @@ startedBefore:
The value must be a valid ISO 8601 datetime string (UTC).
style: form
explode: true
allowReserved: true
schema:
type: string
format: date-time
Expand Down
3 changes: 2 additions & 1 deletion ...-api/openapi/components/schemas/actor-pricing-info/FlatPricePerMonthActorPricingInfo.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ allOf:
- trialMinutes
properties:
pricingModel:
$ref: ./PricingModel.yaml
Copy link
Copy Markdown
Contributor

@vdusek vdusek Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIUC the PricingModel is no longer used anywhere, which means it won't be generated anymore (it's being removed, see: https://github.com/apify/apify-client-python/pull/707/changes).

Is that correct?

class PricingModel(StrEnum):
    PAY_PER_EVENT = 'PAY_PER_EVENT'
    PRICE_PER_DATASET_ITEM = 'PRICE_PER_DATASET_ITEM'
    FLAT_PRICE_PER_MONTH = 'FLAT_PRICE_PER_MONTH'
    FREE = 'FREE'

We really don't need the enum anywhere?

Copy link
Copy Markdown
Contributor Author

@Pijukatel Pijukatel Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is autogenerated based on errors produced by the integration tests. So as of now it is still part of the API. We can remove it from the specification in the future once it is completely removed from the API.

Copy link
Copy Markdown
Contributor Author

@Pijukatel Pijukatel Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this specifc file is no longer referenced anywhere

Copy link
Copy Markdown
Contributor

@vdusek vdusek Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My point was whether the PricingModel enum isn't used somewhere else in the Client or SDK.

Copy link
Copy Markdown
Contributor Author

@Pijukatel Pijukatel Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Used in SDK, but there it should be refactored. apify/apify-sdk-python#853

type: string
const: FLAT_PRICE_PER_MONTH
trialMinutes:
type: integer
description: For how long this Actor can be used for free in trial period
Expand Down
3 changes: 2 additions & 1 deletion apify-api/openapi/components/schemas/actor-pricing-info/FreeActorPricingInfo.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,5 @@ allOf:
- pricingModel
properties:
pricingModel:
$ref: ./PricingModel.yaml
type: string
const: FREE
3 changes: 2 additions & 1 deletion apify-api/openapi/components/schemas/actor-pricing-info/PayPerEventActorPricingInfo.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@ allOf:
- pricingPerEvent
properties:
pricingModel:
$ref: ./PricingModel.yaml
type: string
const: PAY_PER_EVENT
pricingPerEvent:
type: object
properties:
Expand Down
3 changes: 2 additions & 1 deletion ...pi/openapi/components/schemas/actor-pricing-info/PricePerDatasetItemActorPricingInfo.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ allOf:
- unitName
properties:
pricingModel:
$ref: ./PricingModel.yaml
type: string
const: PRICE_PER_DATASET_ITEM
unitName:
type: string
description: Name of the unit that is being charged
Expand Down
7 changes: 0 additions & 7 deletions apify-api/openapi/components/schemas/actor-pricing-info/PricingModel.yaml
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion apify-api/openapi/components/schemas/actor-runs/RunOptions.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ properties:
minimum: 0
examples: [2048]
maxItems:
type: integer
type: [integer, "null"]
minimum: 1
examples: [1000]
maxTotalChargeUsd:
Expand Down
1 change: 0 additions & 1 deletion apify-api/openapi/components/schemas/actor-tasks/CreateTaskRequest.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
title: CreateTaskRequest
required:
- actId
- name
type: object
properties:
actId:
Expand Down
2 changes: 0 additions & 2 deletions apify-api/openapi/components/schemas/actors/SourceCodeFile.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
title: SourceCodeFile
type: object
required:
- format
- content
- name
properties:
format:
Expand Down
2 changes: 1 addition & 1 deletion apify-api/openapi/components/schemas/request-queues/RequestBase.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ properties:
description: The final URL that was loaded, after redirects (if any).
examples: [https://apify.com/jobs]
payload:
type: [object, "null"]
type: [string, object, "null"]
description: The request payload, typically used with POST or PUT requests.
examples: [null]
headers:
Expand Down
1 change: 0 additions & 1 deletion apify-api/openapi/components/schemas/request-queues/SharedProperties.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@ UniqueKey:

RequestUrl:
type: string
format: uri
Copy link
Copy Markdown
Contributor

@vdusek vdusek Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why are we removing these format constraints?

Copy link
Copy Markdown
Contributor Author

@Pijukatel Pijukatel Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This constraint does not exist in API:
image
https://github.com/apify/apify-core/blob/e8976db3b5b2476d2f01af1a84d4268fc61e839f/src/packages/schemas/src/request_queues.ts#L27

Copy link
Copy Markdown
Contributor

@janbuchar janbuchar Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is that intentional? Perhaps @tobice of @fnesveda could share some thoughts?

Copy link
Copy Markdown
Member

@fnesveda fnesveda Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably because you might also want to save PseudoURLs to the queue, not just regular URLs. It's been like this since the original implementation: https://github.com/apify/apify-core/commit/9bb347bd4baf62a23bda7c180ce58dd68cf30252#diff-48532f504598f9f0dc62bb5d060e1b3951b95c959d76e797f24e1e6bb155ddebR117

Copy link
Copy Markdown
Contributor

@janbuchar janbuchar Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh hot damn... so will the API really accept any string?

Copy link
Copy Markdown
Member

@fnesveda fnesveda Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep.

Copy link
Copy Markdown
Contributor

@vdusek vdusek Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are still other fields using the URI format, for example, loadedUrl in RequestBase, or consoleUrl and standbyUrl. Is that intentional? You wanna address it later @Pijukatel ?

Copy link
Copy Markdown
Contributor Author

@Pijukatel Pijukatel Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will check that and align it in a separate PR.

Copy link
Copy Markdown
Contributor Author

@Pijukatel Pijukatel Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#2423

description: The URL of the request.
examples: [https://apify.com]

Expand Down
1 change: 0 additions & 1 deletion apify-api/openapi/components/schemas/webhooks/WebhookCreate.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,6 @@ properties:
examples: [false]
requestUrl:
type: string
format: uri
examples: ["http://example.com/"]
payloadTemplate:
type: [string, "null"]
Expand Down
4 changes: 4 additions & 0 deletions ...y-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync-get-dataset-items.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ get:
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipHidden"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipEmpty"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/simplified"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/view"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipFailedPages"
responses:
"201":
Expand Down Expand Up @@ -147,6 +148,7 @@ post:
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipHidden"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipEmpty"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/simplified"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/view"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipFailedPages"
requestBody:
description: ""
Expand All @@ -156,6 +158,8 @@ post:
type: object
example:
foo: bar
"*/*":
schema: {}
required: true
responses:
"201":
Expand Down
2 changes: 2 additions & 0 deletions apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,8 @@ post:
type: object
example:
foo: bar
"*/*":
schema: {}
required: true
responses:
"201":
Expand Down
2 changes: 2 additions & 0 deletions apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@runs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,8 @@ post:
type: object
example:
foo: bar
"*/*":
schema: {}
required: true
responses:
"201":
Expand Down
1 change: 1 addition & 0 deletions apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@runs@last.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ get:
parameters:
- $ref: "../../components/parameters/runAndBuildParameters.yaml#/actorTaskId"
- $ref: "../../components/parameters/runAndBuildParameters.yaml#/statusLastRun"
- $ref: "../../components/parameters/runAndBuildParameters.yaml#/waitForFinishRun"
responses:
"200":
description: ""
Expand Down
4 changes: 4 additions & 0 deletions apify-api/openapi/paths/actors/acts@{actorId}@run-sync-get-dataset-items.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ post:
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipHidden"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipEmpty"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/simplified"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/view"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipFailedPages"
requestBody:
description: ""
Expand All @@ -64,6 +65,8 @@ post:
type: object
example:
foo: bar
"*/*":
schema: {}
required: true
responses:
"201":
Expand Down Expand Up @@ -156,6 +159,7 @@ get:
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipHidden"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipEmpty"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/simplified"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/view"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipFailedPages"
responses:
"201":
Expand Down
2 changes: 2 additions & 0 deletions apify-api/openapi/paths/actors/acts@{actorId}@run-sync.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ post:
type: object
example:
foo: bar
"*/*":
schema: {}
required: true
responses:
"201":
Expand Down
2 changes: 2 additions & 0 deletions apify-api/openapi/paths/actors/acts@{actorId}@runs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,8 @@ post:
type: object
example:
foo: bar
"*/*":
schema: {}
required: true
responses:
"201":
Expand Down
1 change: 1 addition & 0 deletions apify-api/openapi/paths/actors/acts@{actorId}@runs@last.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ get:
parameters:
- $ref: "../../components/parameters/runAndBuildParameters.yaml#/actorId"
- $ref: "../../components/parameters/runAndBuildParameters.yaml#/statusLastRun"
- $ref: "../../components/parameters/runAndBuildParameters.yaml#/waitForFinishRun"
responses:
"200":
description: ""
Expand Down
2 changes: 1 addition & 1 deletion apify-api/openapi/paths/actors/acts@{actorId}@versions@{versionNumber}.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ delete:
application/json:
schema:
oneOf:
- $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorNotFoundError"
- $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/RecordOrTokenNotFoundError"
- $ref: "../../components/schemas/common/errors/ActorErrors.yaml#/ActorVersionNotFoundError"
"405":
$ref: ../../components/responses/MethodNotAllowed.yaml
Expand Down
20 changes: 2 additions & 18 deletions apify-api/openapi/paths/datasets/datasets@{datasetId}@items.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,15 +173,7 @@ get:
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipHidden"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipEmpty"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/simplified"
- name: view
in: query
description: |
Defines the view configuration for dataset items based on the schema definition.
This parameter determines how the data will be filtered and presented.
For complete specification details, see the [dataset schema documentation](/platform/actors/development/actor-definition/dataset-schema).
schema:
type: string
example: overview
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/view"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipFailedPages"
- $ref: "../../components/parameters/storageParameters.yaml#/signature"
responses:
Expand Down Expand Up @@ -274,15 +266,7 @@ head:
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipHidden"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipEmpty"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/simplified"
- name: view
in: query
description: |
Defines the view configuration for dataset items based on the schema definition.
This parameter determines how the data will be filtered and presented.
For complete specification details, see the [dataset schema documentation](/platform/actors/development/actor-definition/dataset-schema).
schema:
type: string
example: overview
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/view"
- $ref: "../../components/parameters/datasetItemsParameters.yaml#/skipFailedPages"
- $ref: "../../components/parameters/storageParameters.yaml#/signature"
responses:
Expand Down
14 changes: 8 additions & 6 deletions apify-api/openapi/paths/request-queues/request-queues@{queueId}@requests.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,13 +39,15 @@ get:
in: query
description: Filter requests by their state. Possible values are `locked` and `pending`. (Is not compatible with deprecated `exclusiveStartId` parameter.)
style: form
explode: true
explode: false
schema:
type: string
enum:
- locked
- pending
example: locked
type: array
items:
type: string
enum:
- locked
- pending
example: [locked]
responses:
"200":
description: ""
Expand Down
3 changes: 1 addition & 2 deletions apify-api/openapi/paths/request-queues/request-queues@{queueId}@requests@batch.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,9 +92,8 @@ delete:
required: true
style: simple
schema:
enum:
- application/json
type: string
const: application/json
- $ref: "../../components/parameters/storageParameters.yaml#/clientKey"
requestBody:
description: ""
Expand Down
Loading