Include X-Glean-Include-Experimental header in generated cURL examples

[travis-hoover-glean]

Problem

For experimental endpoints, the SDK code samples (Python/Go/Java/TypeScript) correctly show the experimental opt-in (e.g. includeExperimental: true), but the cURL tab omitted the required X-Glean-Include-Experimental: true header — so copy-pasting the cURL example would fail against experimental endpoints.

Root cause

The two snippet types come from different pipelines:

• SDK tabs are curated x-codeSamples baked into the OpenAPI specs by Speakeasy, which emits includeExperimental: true.
• The cURL tab is generated at runtime in the browser by docusaurus-theme-openapi-docs (postman-code-generators) purely from the operation's declared parameters. Experimental operations never declared the header, so cURL omitted it.

Key mechanism: in the theme's ApiExplorer/buildPostmanRequest.js → setHeaders, a header parameter is only emitted into the snippet when the parameter object carries a truthy value property. Parameter objects flow verbatim from spec → page frontmatter → snippet generator.

Fix

• scripts/openapi-capitalize-language.mjs (shared spec-transform step for all three specs): new injectExperimentalHeaders() that, for every operation marked x-glean-experimental, injects a required X-Glean-Include-Experimental header parameter with a pre-set value: 'true' (the non-standard value property is what makes the theme render it in the generated cURL). Idempotent, and runs automatically in the existing openapi:transform:* / openapi:regenerate:* flows so it survives future spec refreshes from upstream.
• Regenerated the transformed specs and the docs for the 7 affected experimental endpoints (2 client Tools + 5 Platform).
• Added scripts/openapi-capitalize-language.test.ts covering injection, missing-parameters case, non-experimental operations, idempotency, and empty specs.

The cURL tab now renders:

curl -L 'https://instance-name-be.glean.com/rest/api/v1/tool-servers/{serverId}/auth' \
-H 'X-Glean-Include-Experimental: true' \
-H 'Content-Type: application/json' \
...

Bonus: the header now also appears in each experimental endpoint's Header Parameters docs section with a link to How experimental APIs work, which helps anyone hand-writing requests.

Testing

• pnpm test — 128 passed (incl. 5 new)
• pnpm build — succeeds
• Prettier — clean

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
glean-developer-site	Ready	Preview, Comment	Jul 9, 2026 4:56pm