Pulumi Cloud REST API Docs, Now Generated from OpenAPI

Source: Pulumi Blog

Why this matters

The previous REST API reference was a set of handwritten pages. Every new endpoint, renamed parameter, or revised response shape required a matching docs PR, and in practice the pages drifted. Small inconsistencies added up: missing parameters, outdated request shapes, and schemas that no longer matched what the API returned. We needed a durable fix that keeps the docs in sync as the API grows.

Generating the reference from the OpenAPI spec closes that gap. When the API ships a change, the docs pick it up automatically the next time our docs are built.

What’s new

The reference at /docs/reference/cloud-rest-api/ now includes:

• Find what you need faster – Endpoints are grouped by product area (Stacks, Deployments, Environments, Organizations, Registry, Insights, AI, Workflows, and more) so you can jump straight to the part of the API you’re working with.
• Complete request and response details – Every endpoint documents its parameters, request body, and the exact shape of what it returns, so you know what to send and what to expect back without guessing.
• One‑click navigation between related types – When a response references another object, the type name is a link. Click through to drill into its full definition instead of scrolling a lengthy API reference page.

What this unlocks for agents

Keeping the reference in sync with the spec isn’t just a human convenience; it changes what’s reliable for AI agents that read the docs and call the API on your behalf. An agent reading a handwritten reference might see a parameter that was renamed six months ago, or miss a field the API now returns, causing calls to fail silently or in hard‑to‑debug ways. When the reference is generated from the spec, the agent works from what the API actually accepts today.

Imagine you’re onboarding a new team and need to stand up their access in Pulumi Cloud. Point an agent at the REST API reference and ask it to:

1. Create an sre‑oncall team.
2. Add four members.
3. Grant admin on three stacks.

The agent walks the teams, memberships, and stack‑permissions endpoints, builds the right sequence of calls, and executes them.

The same pattern holds for bulk audits and cleanup. Ask an agent to find every stack in your org with no recent updates and tag them stale; it can paginate correctly because the response schema matches reality. While such workflows were technically possible before, they’re now much more reliable.

Same URL, existing links keep working

The generated docs live at the same URL as the previous reference: /docs/reference/cloud-rest-api/. Bookmarks, blog links, and inbound search traffic still land on the right page. Redirects are in place for any API reference docs page that has been tweaked, renamed, or moved.

Try it out

Start at the new REST API reference and browse by category. Each page links through to the request and response object schemas it uses.

If you spot anything that looks wrong, the most likely culprit is the OpenAPI spec itself — file an issue in pulumi/docs and we’ll trace it back to the source. For tag intros and structural improvements, PRs to pulumi/docs are welcome. Questions and feedback are always welcome in the Pulumi Community Slack.