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

## Summary

- Fix boolean query parameters showing empty values in API tester (e.g.,
`?clean=` instead of `?clean=true`)
- Move API clients box from markdown injection to direct React rendering
with BrowserOnly (fixes search pollution and markdown export)
- Move LLM buttons from markdown injection to React portal rendering
(fixes search pollution and markdown export)
- Add missing properties to OpenAPI schemas to fix @redocly/cli 2.15.0
validation errors
- Skip apiKey auth schemes in API tester (only support httpBearer)
- Improve response examples display:
  - Show Example tab first (before Schema)
  - Skip auto-generated example when explicit example exists
  - Expand first level of nested schema items by default
- Update OpenAPI plugin packages to 4.7.1 and @redocly/cli to 2.15.0

## Test plan

- [x] Test boolean query parameters in API tester (e.g., Dataset items
`clean` param)
- [x] Verify API clients box renders correctly and doesn't appear in
search or `.md` export
- [x] Verify LLM buttons render after heading and don't appear in search
or `.md` export
- [x] Verify API tester only shows Bearer token auth option
- [x] Verify response examples show Example tab first with explicit
examples preferred
- [x] Verify first level of schema is expanded by default
- [x] OpenAPI lint passes (`npm run openapi:lint:redocly`)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Closes #2204
Closes #1983
Closes #1943
Closes #1327
Closes #1174

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: B4nan

CONTRIBUTING.md

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

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

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

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