1. Docs
  2. Reference
  3. REST API Docs

Pulumi Cloud REST API

    The Pulumi Cloud REST API is used by the Pulumi CLI to query and interact with state information, history, stack tags, etc. This API is available for end users to integrate into their own automation use cases.

    Endpoint URL

    For the Managed Pulumi Cloud (i.e. app.pulumi.com), API endpoints are prefixed with the following URL:

    https://api.pulumi.com

    If you are using Self-Hosted Pulumi Cloud, then use the configured endpoint for the Pulumi API component (e.g. https://api.pulumi.example.com).

    Authentication

    All requests must be authenticated using a token via the Authorization HTTP header.

    The Authorization header must be in the form below with the literal string token, then a space, then your access token value.

    Authorization: token {token}

    To view your access tokens, or create a new one, view the Access Tokens page. You will see a list of past tokens, when they were last used, and have the ability to revoke them.

    The Pulumi Cloud REST API will return a 401 status code if the token is missing or invalid.

    Required Request Headers

    The following headers are required for all operations except where explicitly noted:

    Accept: application/vnd.pulumi+8
Content-Type: application/json

    API documentation by category

    The Pulumi Cloud REST API is organized into the following categories. Each page is generated from the live OpenAPI spec.

    • Access Tokens: Authenticate users and automation with Pulumi Cloud. Covers personal access tokens (PATs) for individuals and organization-level tokens for teams and CI.
    • AI: Generate Pulumi project templates from natural-language prompts and access other AI-assisted Pulumi capabilities.
    • Audit Logs: Retrieve and export Pulumi Cloud audit log entries (user actions and system events) for compliance, security, and monitoring.
    • Cloud Setup: Configure cloud provider credentials and integrations for use with Pulumi. Covers initial provider setup workflows for AWS, Azure, and GCP.
    • Data Export: Download Pulumi Cloud resource data for offline analysis or integration with other systems via an endpoint that exports resource search results.
    • Deployment Runners: Manage agent pools for Deployment Runners, which execute Pulumi deployments in private, controlled environments for your organization.
    • Deployments: Configure and manage Pulumi Deployments to run updates and other operations through Pulumi Cloud, including settings, triggers, status, logs, and history.
    • Environments: Create and manage environments for Pulumi ESC (Environments, Secrets, and Configuration), the centralized way to manage infrastructure configuration.
    • Insights: Get visibility into cloud resources and policies across your organization. Covers account management, resource search and inventory, and policy results.
    • Insights Accounts: Create, list, and manage Pulumi Insights accounts for various cloud providers, the entry point for cloud resource visibility and compliance monitoring.
    • Miscellaneous: Utility endpoints for service capabilities, the CLI version, OAuth token exchange, and the OpenAPI specification.
    • Neo: Create and manage AI agent tasks in Pulumi Cloud, including monitoring status, responding to agent requests, and retrieving task events.
    • OAuth Token Exchange: Exchange OIDC and other external identity tokens for Pulumi access tokens, so workflows authenticate with Pulumi Cloud without long-lived credentials.
    • OIDC Issuers: Register and manage OpenID Connect (OIDC) issuers, used to authenticate workloads with Pulumi Cloud via identity tokens from providers like GitHub Actions.
    • Organizations: Manage Pulumi Cloud organizations and their members, teams, access tokens, and webhooks. Organizations are the primary management boundary in Pulumi Cloud.
    • Policy Groups: Create, manage, and apply Policy Groups, which are collections of policy packs that enforce governance rules on stacks.
    • Policy Packs: Create, manage, and apply Policy Packs, which are collections of policies that define governance rules for infrastructure across your organization.
    • Policy Results: Retrieve policy issues detected during stack updates and resource scanning, part of Pulumi Insights, for governance and compliance monitoring.
    • Registry: List, retrieve, publish, and manage packages, templates, and policy packs in the Pulumi Registry, the host for reusable infrastructure components.
    • Registry Preview: Preview endpoints for the next-generation Pulumi Registry, covering package, template, and policy pack versions under the new identifier scheme.
    • Resource Search: Find and filter resources managed by Pulumi across your organization using structured filters, and retrieve detailed resource metadata.
    • Resources Under Management: Track Resources Under Management (RUM), the cloud resources managed by Pulumi across your organization, over time with various aggregations.
    • Schedules: Automate recurring operations on Pulumi stacks, including drift detection, time-to-live (TTL), and custom scheduled operations.
    • Services: Group and organize related Pulumi Cloud resources into Services, which are collections of resources that work together to provide a specific capability.
    • Stack Config: Manage cloud-persisted stack configuration for service-managed stacks. For stack config variables set during updates, see the Stack Updates API.
    • Stack Policy: Retrieve the policy groups and policy packs associated with a Pulumi stack. Policies define governance rules enforced during stack updates.
    • Stack Tags: Attach key-value metadata to Pulumi stacks for organization, filtering, and storing additional information.
    • Stack Updates: List Pulumi stack update operations (create, update, or delete resources), check status, and view detailed events for each operation.
    • Stacks: Create and manage Pulumi stacks, the isolated and independently configurable instances of a Pulumi program. Covers lifecycle, config, tags, and update history.
    • Users: Manage user profiles, identity linking, and account settings for the authenticated Pulumi user.
    • VCS Integrations: Connect Pulumi Cloud to version control providers like GitHub, GitLab, and Bitbucket, and configure deployment triggers.
    • Webhooks: Create and manage webhooks for organizations and stacks that notify external services of events like stack updates, deployments, or policy violations.