Pulumi Blog: API

Pulumi Cloud REST API Docs, Now Generated from OpenAPI

Devon Grove — Mon, 20 Apr 2026 00:00:00 +0000

The Pulumi Cloud REST API reference is now generated directly from the live OpenAPI spec at build time. Every endpoint, parameter, request body, and response schema you see on the page comes from the same spec the API itself publishes. The docs now stay in sync with the API automatically!

Why this matters

The previous REST API reference was a set of handwritten pages. That meant every new endpoint, renamed parameter, or revised response shape needed a matching docs PR, and in practice the pages drifted. Small inconsistencies added up: missing parameters, outdated request shapes, schemas that no longer matched what the API returned. We wanted 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 if desired 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, and the call fails silently or in ways that are hard to debug. When the reference is generated from the spec, the agent is working from what the API actually accepts today.

Say 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 create an sre-oncall team, add four members, and grant admin on three stacks. The agent walks the teams, memberships, and stack-permissions endpoints, builds the right sequence of calls, and executes.

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, and it can paginate correctly because the response schema matches reality. While workflows like these were technically possible before, they’re much more reliable now.

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.

Explore the REST API

Announcing OpenAPI support for the Pulumi Cloud REST API

Davide Massarenti — Thu, 05 Feb 2026 00:00:00 +0000

We’re thrilled to announce that the Pulumi Cloud REST API is now described by an OpenAPI 3.0 specification, and we’re just getting started.

This is a feature that has been a long time coming. We have heard your requests for OpenAPI support loud and clear, and we’re excited to share that not only do we have a published specification for consumption, but our API code is now built from this specification as well. Moving forward, this single source of truth unlocks better tooling, tighter integration, and a more predictable API experience for everyone.

You can fetch the spec directly from the API at runtime or use it for client generation, validation, and documentation, all from one machine-readable contract.

A single contract for the Pulumi Cloud REST API

The Pulumi Cloud API powers the Pulumi CLI, the Pulumi Console, and third-party integrations. Until now, there was no single, published machine-readable description of that API. We’ve changed that. The API is now defined and served as a standard OpenAPI 3.0.3 document.

Runtime discovery: You can retrieve the spec from the API itself, so your tooling always sees the same surface the service implements.
Client generation: Use your favorite OpenAPI tooling (e.g. OpenAPI Generator, Swagger Codegen) to generate API clients in the language of your choice.
Validation and testing: Validate requests and responses, or build mocks and tests, from the same spec the service uses.
Documentation: The spec is the source of truth, not a separate, hand-maintained API doc that can drift from reality. Load the spec into Swagger UI, Redoc, or another viewer to browse the Pulumi Cloud API interactively.

How to get the spec

Send a GET request to:

https://api.pulumi.com/api/openapi/pulumi-spec.json

No authentication is required. The response is the OpenAPI 3.0 document for the Pulumi Cloud API, describing the supported, documented API surface.

Source of truth and stability

We do not hand-write the OpenAPI spec. We generate it from the same API definition that drives our backend and console code. When we add or change API routes or models, we regenerate the spec so the published document stays in sync with what the service actually implements. That gives you a clear, stable contract for the Pulumi Cloud API.

What we are building next

We are using this spec as the foundation for our own tooling, and have plans to continue leveraging the spec in our toolchain long-term.

CLI: We plan to drive the Pulumi CLI’s API client from the OpenAPI spec so that CLI and API stay in lockstep.
Pulumi Service Provider: We are also building towards day 1 updates to the Pulumi Service Provider so that new and changed API resources are generated from the spec and ship in sync with the service.
Docs Enhancements: Although you can load the spec using Swagger UI for your own browsing, we are intent on shipping enhancements to our public REST API docs that will keep them up-to-date according to the OpenAPI spec.

As we ship those updates, you will get a single source of truth from API to CLI to provider.

If you have questions or feedback about the OpenAPI spec or the Pulumi Cloud API, reach out in our Community Slack or open an issue in the Pulumi repository. We’re excited to see what you build with it.

Tap-Pulumi-Cloud: Simplifying Pulumi Cloud Data Integration

Pablo Seibelt — Tue, 03 Sep 2024 09:00:00 -0700

Integrating various infrastructure data sources into your data warehouse has long been a challenge for Platform Teams. Whether it’s dealing with multiple API endpoints, managing complex authentication processes, or just trying to get a consistent, reliable data feed, the process can be daunting and time-consuming. Especially when you factor in the various cloud providers, and the inconsistency in data formats across them all.

These pain points can slow down your ability to get actionable insights from your infrastructure data, leaving you with more questions than answers.

The tap-pulumi-cloud connector is designed to address these challenges head-on by offering a simple solution for automating the process of accessing infrastructure data.

Leveraging Pulumi Cloud data about your infrastructure instead of going directly to the provider eliminates the need for custom API integrations and handles the data consistency problem. And while all this data existed before by using the Pulumi Cloud console or Pulumi Cloud REST API directly, the tap-pulumi-cloud connector handles complex interactions with the API, transforming the raw data into a structured format that’s ready for analysis as soon as it lands in your data warehouse. This means less time spent on data wrangling and more time on generating insights.

A few examples of the types of analytics you can build on top Pulumi Cloud data:

Average resources under management overtime (code example)
The average time to deploy changes (code example)
See the total updates per user (code example)
Join with CI/CD provider data to generate DORA metrics and reporting
Join with resource cost data to generate infrastructure cost reporting

As it is built on the Meltano SDK, you can use tap-pulumi-cloud with loaders such as target-snowflake, target-bigquery, target-redshift or even target-postgres; allowing us to load the data into our own data warehouse easily.

Setup

Firstly, set up your environment by following Meltano’s installation guide. Once this is done, continue by adding tap-pulumi-cloud and your choice of loader into your environment, we’ll use target-duckdb for this example:

meltano add extractor tap-pulumi-cloud
meltano add loader target-duckdb

Then switch your tap variant to use Pulumi’s instead of the default, open meltano.yml and change the pip_url to git+https://github.com/pulumi/tap-pulumi-cloud.git

version: 1
default_environment: dev
project_id: be90b150-3e48-4ecd-be9d-161ef7417e3c
environments:
- name: dev
- name: staging
- name: prod
plugins:
 extractors:
 - name: tap-pulumi-cloud
 variant: meltanolabs
 pip_url: git+https://github.com/pulumi/tap-pulumi-cloud.git
 loaders:
 - name: target-duckdb
 variant: jwills
 pip_url: target-duckdb~=0.6

Then run meltano install to make sure the right version is installed.

Configure it

To configure all settings available for this tap, you can use Meltano’s interactive config running:

meltano config tap-pulumi-cloud set --interactive

The required variables are the token (Get one from Pulumi Cloud) and organizations is a list of Pulumi Cloud organizations you want to extract data from.

Load data

When your configuration has been finished, you can run the data pipeline:

meltano run tap-pulumi-cloud target-duckdb

After the run finishes, you can access the exported tables and create whichever analytics you need on top of them, for example, you could combine this dataset with tap-github in order to calculate DORA Metrics.

Orchestration

Once you have this working, you’ll need to establish some way of running this regularly in an automated fashion, to keep the data fresh. A popular way to do this is to use an orchestration tool such as Airflow, Dagster or Mage, among others. An easy way to set up Meltano to run in this way is to use a Docker container with your Meltano project.. Another option is to use Arch which is based on Meltano, which path you choose will depend on your requirements and existing stack.

Since each table is created with primary keys, when the process is run again, each run will “upsert” (update+insert) new data, replacing rows which match the same primary keys; e.g. stream Stacks has a primary key by org_name, project_name and stack_name, so if the same combination of keys arrives in the next update, the row will be updated instead of a new row being inserted.

If building a landing zone with all historical changes instead of just the current status, this behavior might not be the desired one, to ignore primary keys and only insert new data, you can add this setting to meltano.yml on the plugin configuration for tap-pulumi-cloud:

 metadata:
 '*':
 table-key-properties: []
 key-properties: []

Generate metrics

With all of the data in one place, you can generate metrics based on Pulumi Cloud data, and combine it with other data sources, for example if you wanted to look at your average Resources Under Management (RUM) monthly (Using DuckDB’s SQL Flavor, adjust to your specific database):

See average resources under management

WITH monthly_rum_average AS (
 SELECT
 DATE_TRUNC('month', MAKE_DATE(CAST(year AS INT), CAST(month AS INT), CAST(day AS INT))) AS rum_month,
 org_name,
 AVG(resources) AS monthly_avg_rum
 FROM
 pulumicloud.daily_rum_usage
 GROUP BY
 rum_month, org_name
)
SELECT
 rum_month,
 org_name,
 monthly_avg_rum,
 LAG(monthly_avg_rum) OVER (ORDER BY rum_month) AS previous_month_avg_rum,
 CASE
 WHEN LAG(monthly_avg_rum) OVER (ORDER BY rum_month) IS NULL THEN NULL
 ELSE ((monthly_avg_rum - LAG(monthly_avg_rum) OVER (ORDER BY rum_month)) / LAG(monthly_avg_rum) OVER (ORDER BY rum_month)) * 100
 END AS month_over_month_rum_growth_percentage
FROM
 monthly_rum_average

See the average time to deploy changes

If you want to see the average time to deploy changes, excluding console-initiated deploys (Similar to what is tracked for “Lead time for changes”):

WITH stack_deployments AS (
 SELECT
 CAST(json_extract(jobs, '$[0].started') AS TIMESTAMP) AS start_time,
 CAST(json_extract(jobs, '$[0].last_updated') AS TIMESTAMP) AS end_time,
 initiator
 FROM
 pulumicloud.stack_deployments
 WHERE
 initiator IS NOT NULL
 AND initiator <> 'console'
)
SELECT
 initiator,
 AVG(DATE_DIFF('second', start_time, end_time)) / 60 AS avg_deploy_time_in_minutes
FROM
 stack_deployments
GROUP BY
 initiator

See the total updates per user

WITH operations_by_members AS (
 SELECT
 org_name,
 REPLACE(CAST(json_extract(requested_by, '$.github_login') AS STRING), '"', '') AS github_login,
 COUNT(*) AS total_updates
 FROM
 pulumicloud.stack_updates
 GROUP BY
 org_name, github_login
 ORDER BY
 total_updates DESC
)
SELECT
 om.org_name,
 om.role,
 om.user_github_login,
 om.user_name,
 obm.total_updates
FROM
 pulumicloud.organization_members om
INNER JOIN
 operations_by_members obm
ON
 om.org_name = obm.org_name
 AND om.user_github_login = obm.github_login
ORDER BY
 total_updates DESC

Conclusion

Integrating Pulumi Cloud data into your data warehouse has never been easier with tap-pulumi-cloud. Whether you’re tracking costs, monitoring deployments, or improving security, the new tap connector empowers your team to make informed, data-driven decisions that drive your cloud strategy forward.