fix(api): Fix boolean query params, search pollution, and OpenAPI schemas #2207

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.

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

B4nan merged 11 commits into master from fix/openapi-plugin-improvements

Jan 30, 2026

CONTRIBUTING.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -190,18 +190,22 @@ Content lives in the following locations:
  
    ### Overview

    The API reference documentation at [docs.apify.com](https://docs.apify.com/) is built directly from our OpenAPI specification. The source of truth for the API specification lives in the `/apify-api/openapi`  directory within [apify-docs](https://github.com/apify/apify-docs) repository.

    The API reference documentation at [docs.apify.com/api/v2](https://docs.apify.com/api/v2) is built from our OpenAPI specification. The source of truth lives in the `/apify-api/openapi` directory.

    ### Setup requirements

    ### Tooling

    1. Install Node.js

    2. Clone the repository

    3. Run `npm install`

    We use the following tools for API documentation:

    - **[OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.3)** - API specification format

    - **[Redocly CLI](https://redocly.com/docs/cli/)** - Linting and validation of OpenAPI specs

    - **[`docusaurus-plugin-openapi-docs`](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs)** - Generates MDX docs from OpenAPI

    - **[`docusaurus-theme-openapi-docs`](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs)** - Renders API reference with interactive explorer

    ### Basic commands

    - `npm start` - Starts docs preview server including API reference

    - `npm test` - Validates the definition

    - `npm run openapi:lint:redocly` - Validates OpenAPI spec with Redocly CLI

    - `npm run api:rebuild` - Regenerates API docs from OpenAPI specs

    ### Adding new documentation

apify-api/openapi/components/schemas/actor-runs/Metamorph.yaml

-Original file line number
+Diff line change
@@ -0,0 +1,25 @@
+    title: Metamorph
+    description: Information about a metamorph event that occurred during the run.
+    type: object
+    required:
+      - createdAt
+      - actorId
+      - buildId
+    properties:
+      createdAt:
+        type: string
+        format: date-time
+        description: Time when the metamorph occurred.
+        examples: ["2019-11-30T07:39:24.202Z"]
+      actorId:
+        type: string
+        description: ID of the Actor that the run was metamorphed to.
+        examples: [nspoEjklmnsF2oosD]
+      buildId:
+        type: string
+        description: ID of the build used for the metamorphed Actor.
+        examples: [ME6oKecqy5kXDS4KQ]
+      inputKey:
+        type: [string, "null"]
+        description: Key of the input record in the key-value store.
+        examples: [INPUT-METAMORPH-1]

apify-api/openapi/components/schemas/actor-runs/Run.yaml

-Original file line number
+Diff line change
@@ Expand Up / @@ -128,3 +128,10 @@ properties: @@
         anyOf:
           - $ref: ./RunUsageUsd.yaml
           - type: "null"
+      metamorphs:
+        description: List of metamorph events that occurred during the run.
+        anyOf:
+          - type: array
+            items:
+              $ref: ./Metamorph.yaml
+          - type: "null"

apify-api/openapi/components/schemas/actor-runs/RunMeta.yaml

-Original file line number
+Diff line change
@@ Expand Up / @@ -5,3 +5,16 @@ type: object @@
     properties:
       origin:
         $ref: ./RunOrigin.yaml
+      clientIp:
+        type: [string, "null"]
+        description: IP address of the client that started the run.
+      userAgent:
+        type: [string, "null"]
+        description: User agent of the client that started the run.
+      scheduleId:
+        type: [string, "null"]
+        description: ID of the schedule that triggered the run.
+      scheduledAt:
+        type: [string, "null"]
+        format: date-time
+        description: Time when the run was scheduled.

apify-api/openapi/components/schemas/actors/CreateOrUpdateVersionRequest.yaml

-Original file line number
+Diff line change
@@ Expand Up / @@ -21,3 +21,12 @@ properties: @@
         examples: [latest]
       sourceFiles:
         $ref: ./VersionSourceFiles.yaml
+      gitRepoUrl:
+        type: [string, "null"]
+        description: URL of the Git repository when sourceType is GIT_REPO.
+      tarballUrl:
+        type: [string, "null"]
+        description: URL of the tarball when sourceType is TARBALL.
+      gitHubGistUrl:
+        type: [string, "null"]
+        description: URL of the GitHub Gist when sourceType is GITHUB_GIST.

apify-api/openapi/components/schemas/actors/Version.yaml

-Original file line number
+Diff line change
@@ Expand Up / @@ -24,3 +24,12 @@ properties: @@
         examples: [latest]
       sourceFiles:
         $ref: ./VersionSourceFiles.yaml
+      gitRepoUrl:
+        type: [string, "null"]
+        description: URL of the Git repository when sourceType is GIT_REPO.
+      tarballUrl:
+        type: [string, "null"]
+        description: URL of the tarball when sourceType is TARBALL.
+      gitHubGistUrl:
+        type: [string, "null"]
+        description: URL of the GitHub Gist when sourceType is GITHUB_GIST.

apify-api/openapi/components/schemas/datasets/DatasetSchemaValidationError.yaml

-Original file line number
+Diff line change
@@ -1,5 +1,13 @@
     title: DatasetSchemaValidationError
     type: object
     properties:
-      error:
-        $ref: ./DatasetSchemaValidationErrorDetails.yaml
+      type:
+        type: string
+        description: The type of the error.
+        examples: [schema-validation-error]
+      message:
+        type: string
+        description: A human-readable message describing the error.
+        examples: [Schema validation failed]
+      data:
+        $ref: ./SchemaValidationErrorData.yaml

apify-api/openapi/components/schemas/datasets/DatasetSchemaValidationErrorDetails.yaml

This file was deleted.

apify-api/openapi/components/schemas/request-queues/RequestDraft.yaml

-Original file line number
+Diff line change
@@ Expand Up / @@ -6,6 +6,10 @@ required: @@
       - method
     type: object
     properties:
+      id:
+        type: string
+        description: A unique identifier assigned to the request.
+        examples: [sbJ7klsdf7ujN9l]
       uniqueKey:
         type: string
         description: A unique key used for request de-duplication. Requests with the same unique key are considered identical.
@@ Expand Down @@

apify-api/openapi/components/schemas/store/StoreListActor.yaml

-Original file line number
+Diff line change
@@ Expand Up / @@ -53,3 +53,6 @@ properties: @@
         $ref: ../actors/ActorStats.yaml
       currentPricingInfo:
         $ref: ./CurrentPricingInfo.yaml
+      isWhiteListedForAgenticPayment:
+        type: [boolean, "null"]
+        description: Whether the Actor is whitelisted for agentic payment processing.

apify-api/plugins/apify.mjs

-Original file line number
+Diff line change
@@ -1,4 +1,3 @@
-    import ClientReferencesLinksDecorator from './decorators/client-references-links-decorator.mjs';
     import CodeSamplesDecorator from './decorators/code-samples-decorator.mjs';
     import LegacyDocUrlDecorator from './decorators/legacy-doc-url-decorator.mjs';
@@ Expand All / @@ -7,7 +6,6 @@ export default () => ({ @@
         decorators: {
             oas3: {
                 'legacy-doc-url-decorator': LegacyDocUrlDecorator,
-                'client-references-links-decorator': ClientReferencesLinksDecorator,
                 'code-samples-decorator': CodeSamplesDecorator,
             },
         },
@@ Expand Down @@

apify-api/plugins/decorators/client-references-links-decorator.mjs

This file was deleted.

apify-docs-theme/src/roa-loader/index.js

-Original file line number
+Diff line change
@@ Expand Up / @@ -3,11 +3,13 @@ const { inspect } = require('node:util'); @@
     const { urlToRequest } = require('loader-utils');
+    const SIGNING_TOKEN = process.env.APIFY_SIGNING_TOKEN;
     const signingUrl = new URL('https://api.apify.com/v2/tools/encode-and-sign');
-    signingUrl.searchParams.set('token', process.env.APIFY_SIGNING_TOKEN);
+    signingUrl.searchParams.set('token', SIGNING_TOKEN || '');
     const queue = [];
     const cache = {};
     let working = false;
+    let warnedAboutMissingToken = false;
     function hash(source) {
         return createHash('sha1').update(source).digest('hex');
@@ Expand Down Expand Up / @@ -80,6 +82,15 @@ module.exports = async function (code) { @@
             return { code, hash: 'fast' };
         }
+        // Skip signing if token is not configured
+        if (!SIGNING_TOKEN) {
+            if (!warnedAboutMissingToken) {
+                console.warn('APIFY_SIGNING_TOKEN is not set, skipping code signing for runnable examples.');
+                warnedAboutMissingToken = true;
+            }
+            return { code, hash: 'unsigned' };
+        }
         console.log(`Signing ${urlToRequest(this.resourcePath)}...`, { working, queue: queue.length });
         const codeHash = await encodeAndSign(code);
@@ Expand Down @@

apify-docs-theme/src/theme/custom.css

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -1785,56 +1785,70 @@ iframe[src*="youtube"] {
  
    .theme-api-markdown .openapi-clients-box {

        display: block;

        float: right;

        padding-left: 12px;

        padding-right: 6px;

        margin-top: 16px;

        margin-left: 16px;

        margin-bottom: 12px;

        padding: 10px 16px;

        min-width: 140px;

        background: var(--ifm-background-surface-color);

        border: 1px solid var(--ifm-toc-border-color);

        border-radius: 8px;

    }

    .client-docs-link img {

        border: 1px solid var(--color-neutral-action-secondary);

        border-radius: 8px;

    .theme-api-markdown .openapi-clients-box-heading {

        display: block;

        font-size: 11px;

        font-weight: 600;

        letter-spacing: 0.5px;

        text-transform: uppercase;

        color: var(--ifm-color-emphasis-600);

        margin-bottom: 4px;

    }

    .client-docs-link {

        display: flex;

        flex-direction: row;

        align-items: center;

        justify-content: left;

        gap: 8px;

        padding: 4px 8px 8px 0px;

        gap: 6px;

        padding: 2px 0;

        text-decoration: none;

        transition: opacity 0.15s ease;

    }

    a.client-docs-link {

        font-weight: 500;

        color: var(--color-neutral-text-muted);

    .client-docs-link:hover {

        opacity: 0.8;

        text-decoration: none;

    }

    .theme-admonition {

        clear: right;

    a.client-docs-link {

        font-size: 13px;

        font-weight: 500;

        color: var(--ifm-color-emphasis-800);

    }

    .theme-api-markdown .openapi-clients-box-heading {

        display: inline-block;

        font-family: 'San Francisco', Helvetica, Arial, sans-serif;

        color: var(--color-neutral-text-muted);

        font-style: normal;

        font-weight: 700;

        font-size: 14px;

        line-height: 20px;

        text-transform: uppercase;

        padding-bottom: 6px;

    .client-docs-link img {

        border-radius: 4px;

    }

    .theme-api-markdown .openapi-clients-box-icon {

        display: block;

        padding: 2px;

        margin: 0 !important;

    }

    .theme-admonition {

        clear: right;

    }

    .theme-api-markdown .openapi__method-endpoint-path,

    .theme-api-markdown .openapi-security__summary-header {

        margin-top: 0;

    }

    .theme-api-markdown .openapi-explorer__details-summary:before {

        width: 1.6rem;

        height: 1.6rem;

    }

    .theme-api-markdown .prism-code .token-line::before {

        display: none !important;

    }

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(api): Fix boolean query params, search pollution, and OpenAPI schemas #2207

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

Uh oh!