Pulumi Registry API

openapi: 3.0.3
info:
  description: APIs and Definitions for the Pulumi Cloud product.
  title: Pulumi APIs AccessTokens Registry API
  version: 1.0.0
tags:
- name: Registry
paths:
  /api/registry/packages:
    get:
      description: Retrieves all registry packages accessible to the caller, with support for filtering, sorting, and pagination. No authentication is required, but authenticated requests may include additional usage statistics per package. Results can be filtered by package name, publisher, owning organization, package type, usage, search query, and visibility level. The sort parameter controls the ordering of results, and the asc parameter toggles ascending vs. descending order. Results are paginated with a default limit of 100 per page; use the continuationToken from the response to retrieve subsequent pages. Each entry in the response contains the full package metadata including name, publisher, source, version, title, description, repository URL, category, featured status, package types, maturity status, readme URL, schema URL, creation timestamp, and visibility.
      operationId: ListPackages
      parameters:
      - description: When true, sort results in ascending order
        in: query
        name: asc
        schema:
          type: boolean
      - description: Pagination token for retrieving the next page of results
        in: query
        name: continuationToken
        schema:
          type: string
      - description: 'Results per page (default: 100)'
        in: query
        name: limit
        schema:
          format: int64
          type: integer
      - description: Filter by specific package name
        in: query
        name: name
        schema:
          type: string
      - description: Filter by owning organization
        in: query
        name: orgLogin
        schema:
          type: string
      - description: Filter by package type
        in: query
        name: packageType
        schema:
          type: string
      - description: Filter by publisher organization
        in: query
        name: publisher
        schema:
          type: string
      - description: Search query string
        in: query
        name: search
        schema:
          type: string
      - description: Sort field for results
        in: query
        name: sort
        schema:
          type: string
      - description: Filter by usage type
        in: query
        name: usage
        schema:
          type: string
      - description: Filter by visibility level
        in: query
        name: visibility
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPackagesResponse'
          description: OK
        '400':
          description: Bad continuationToken
      summary: ListPackages
      tags:
      - Registry
  /api/registry/packages/{source}/{publisher}/{name}/versions:
    post:
      description: Initiates the first step of a two-phase package version publish workflow. This creates a publish transaction and returns an operationID along with pre-signed upload URLs for the package artifacts (schema, index, and installationConfiguration). The caller must upload all required artifacts to the provided URLs and then call the PostPublishPackageVersionComplete endpoint with the operationID to finalize the publish. The request body must include the semantic version to publish. Returns 202 Accepted with the operation details, 404 if the source does not exist, or 409 if the specified version already exists.
      operationId: PostPublishPackageVersion
      parameters:
      - description: 'The package source: ''pulumi'', ''opentofu'', or ''private'''
        in: path
        name: source
        required: true
        schema:
          type: string
      - description: Organization that owns the package
        in: path
        name: publisher
        required: true
        schema:
          type: string
      - description: The package name
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartPackagePublishRequest'
        x-originalParamName: body
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartPackagePublishResponse'
          description: Accepted
        '404':
          description: Source
        '409':
          description: Version already exists
      summary: PostPublishPackageVersion
      tags:
      - Registry
  /api/registry/packages/{source}/{publisher}/{name}/versions/{version}:
    delete:
      description: Removes a specific version of a package from the registry. The package is identified by its source (e.g. 'pulumi', 'opentofu', or 'private'), publisher organization, name, and semantic version. Requires the RegistryPublish permission on the publisher organization. Returns 204 No Content on success.
      operationId: DeletePublishPackageVersion
      parameters:
      - description: 'The package source: ''pulumi'', ''opentofu'', or ''private'''
        in: path
        name: source
        required: true
        schema:
          type: string
      - description: Organization that owns the package
        in: path
        name: publisher
        required: true
        schema:
          type: string
      - description: The package name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Semantic version string of the package version to delete
        in: path
        name: version
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
      summary: DeletePublishPackageVersion
      tags:
      - Registry
    get:
      description: Retrieves metadata for a specific version of a registry package. The package is identified by its source, publisher organization, and name. The version parameter accepts either a specific semantic version string or the special value 'latest' to retrieve the most recently published version. The response includes the package's name, publisher, version, title, description, repository URL, category, featured status, package types, maturity status, readme URL, schema URL, plugin download URL, creation timestamp, visibility, parameterization details, and usage statistics (when the caller is authenticated). Returns 404 if the specified package version does not exist.
      operationId: GetPackageVersion
      parameters:
      - description: 'The package source: ''pulumi'', ''opentofu'', or ''private'''
        in: path
        name: source
        required: true
        schema:
          type: string
      - description: Organization that owns the package
        in: path
        name: publisher
        required: true
        schema:
          type: string
      - description: The package name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Semantic version string or 'latest'
        in: path
        name: version
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageMetadata'
          description: OK
        '404':
          description: package version
      summary: GetPackageVersion
      tags:
      - Registry
  /api/registry/packages/{source}/{publisher}/{name}/versions/{version}/complete:
    post:
      description: Finalizes the second step of the two-phase package version publish workflow. After initiating a publish with PostPublishPackageVersion and uploading all required artifacts (schema, index, installationConfiguration) to the pre-signed URLs, call this endpoint with the operationID to complete the publish. The service validates that all artifacts were uploaded successfully before making the version available in the registry. Returns 201 Created on success, 400 for a bad request (e.g. missing artifacts), 404 if the publish operation is not found, or 409 if the version already exists.
      operationId: PostPublishPackageVersionComplete
      parameters:
      - description: 'The package source: ''pulumi'', ''opentofu'', or ''private'''
        in: path
        name: source
        required: true
        schema:
          type: string
      - description: Organization that owns the package
        in: path
        name: publisher
        required: true
        schema:
          type: string
      - description: The package name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Semantic version string of the package version to complete
        in: path
        name: version
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishPackageVersionCompleteRequest'
        x-originalParamName: body
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishPackageVersionCompleteResponse'
          description: Created
        '400':
          description: Bad request
        '404':
          description: Publish Operation
        '409':
          description: Version already exists
      summary: PostPublishPackageVersionComplete
      tags:
      - Registry
  /api/registry/packages/{source}/{publisher}/{name}/versions/{version}/docs/{token}:
    get:
      description: 'Returns structured API documentation for a single resource or function identified by its Pulumi token. The token must be URL-encoded (e.g. ''random:index%2FrandomPassword:RandomPassword''). The ''lang'' parameter is required and filters all property names, types, descriptions, and code examples to the specified language. Use the ''os'' parameter to collapse OS choosers in descriptions. Supports content negotiation via the Accept header: send ''text/markdown'' to receive a rendered markdown document with property tables instead of structured JSON. The version parameter accepts a specific semantic version string or ''latest''. Returns 404 if the package version or token does not exist.'
      operationId: GetPackageDocs
      parameters:
      - description: 'The package source: ''pulumi'', ''opentofu'', or ''private'''
        in: path
        name: source
        required: true
        schema:
          type: string
      - description: Organization that owns the package
        in: path
        name: publisher
        required: true
        schema:
          type: string
      - description: The package name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Semantic version string or 'latest'
        in: path
        name: version
        required: true
        schema:
          type: string
      - description: URL-encoded Pulumi token identifying the resource or function
        in: path
        name: token
        required: true
        schema:
          type: string
      - description: 'Language for filtering property names, types, descriptions, and code examples. Values: typescript, python, go, csharp, java, yaml'
        in: query
        name: lang
        required: true
        schema:
          type: string
      - description: 'Filter OS choosers in descriptions to a single OS. Values: linux, macos, windows'
        in: query
        name: os
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPackageDocsResponse'
            text/markdown:
              schema:
                type: string
          description: OK
        '400':
          description: invalid query parameter
        '404':
          description: package version or token
      summary: GetPackageDocs
      tags:
      - Registry
      x-pulumi-route-property:
        Visibility: Preview
  /api/registry/packages/{source}/{publisher}/{name}/versions/{version}/installation:
    get:
      description: 'Returns installation configuration content for a registry package version, structured as an ordered list of content nodes. Not all packages include installation configuration; this endpoint returns 404 when absent. Use the ''lang'' parameter to filter language-specific content to a single language (fallback chain: requested language, then Go, then first available). Use the ''os'' parameter to filter OS-specific content similarly (fallback: Linux). Supports content negotiation via the Accept header: send ''text/markdown'' to receive a clean rendered markdown string instead of structured JSON. The version parameter accepts a specific semantic version string or ''latest''. Returns 404 if the specified package version does not exist or if the package does not include installation configuration.'
      operationId: GetPackageInstallation
      parameters:
      - description: 'The package source: ''pulumi'', ''opentofu'', or ''private'''
        in: path
        name: source
        required: true
        schema:
          type: string
      - description: Organization that owns the package
        in: path
        name: publisher
        required: true
        schema:
          type: string
      - description: The package name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Semantic version string or 'latest'
        in: path
        name: version
        required: true
        schema:
          type: string
      - description: 'Filter language-specific content to a single language. Values: typescript, python, go, csharp, java, yaml'
        in: query
        name: lang
        schema:
          type: string
      - description: 'Filter OS-specific content to a single OS. Values: linux, macos, windows'
        in: query
        name: os
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPackageInstallationResponse'
            text/markdown:
              schema:
                type: string
          description: OK
        '400':
          description: invalid query parameter
        '404':
          description: package version or installation configuration
      summary: GetPackageInstallation
      tags:
      - Registry
      x-pulumi-route-property:
        Visibility: Preview
  /api/registry/packages/{source}/{publisher}/{name}/versions/{version}/nav:
    get:
      description: 'Returns the module, resource, and function navigation tree for a registry package version. Names are resolved for the requested language (defaulting to Go when omitted). Use the ''q'' parameter for case-insensitive search: the tree is filtered to nodes whose name or token contains the query string, with ancestor module paths preserved. Modules with no matching children are omitted. Supports content negotiation via the Accept header: send ''text/markdown'' to receive a plain-text listing instead of structured JSON. The version parameter accepts a specific semantic version string or ''latest''. Returns 404 if the specified package version does not exist.'
      operationId: GetPackageNav
      parameters:
      - description: 'The package source: ''pulumi'', ''opentofu'', or ''private'''
        in: path
        name: source
        required: true
        schema:
          type: string
      - description: Organization that owns the package
        in: path
        name: publisher
        required: true
        schema:
          type: string
      - description: The package name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Semantic version string or 'latest'
        in: path
        name: version
        required: true
        schema:
          type: string
      - description: 'Language for name resolution. Names are resolved for this language with a fallback chain: requested language, then Go, then first available. Values: typescript, python, go, csharp, java, yaml'
        in: query
        name: lang
        schema:
          type: string
      - description: Search query for filtering the navigation tree. Case-insensitive matching against resource/function names and tokens
        in: query
        name: q
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPackageNavResponse'
            text/markdown:
              schema:
                type: string
          description: OK
        '400':
          description: invalid query parameter
        '404':
          description: package version
      summary: GetPackageNav
      tags:
      - Registry
      x-pulumi-route-property:
        Visibility: Preview
  /api/registry/packages/{source}/{publisher}/{name}/versions/{version}/readme:
    get:
      description: 'Returns README content for a registry package version, structured as an ordered list of content nodes. Each node has a ''kind'' and a ''markdown'' fallback for forward compatibility. Use the ''lang'' parameter to filter language-specific content to a single language (fallback chain: requested language, then Go, then first available). Use the ''os'' parameter to filter OS-specific content similarly (fallback: Linux). Supports content negotiation via the Accept header: send ''text/markdown'' to receive a clean rendered markdown string instead of structured JSON. The version parameter accepts a specific semantic version string or ''latest''. Returns 404 if the specified package version does not exist.'
      operationId: GetPackageReadme
      parameters:
      - description: 'The package source: ''pulumi'', ''opentofu'', or ''private'''
        in: path
        name: source
        required: true
        schema:
          type: string
      - description: Organization that owns the package
        in: path
        name: publisher
        required: true
        schema:
          type: string
      - description: The package name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Semantic version string or 'latest'
        in: path
        name: version
        required: true
        schema:
          type: string
      - description: 'Filter language-specific content to a single language. Values: typescript, python, go, csharp, java, yaml'
        in: query
        name: lang
        schema:
          type: string
      - description: 'Filter OS-specific content to a single OS. Values: linux, macos, windows'
        in: query
        name: os
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPackageReadmeResponse'
            text/markdown:
              schema:
                type: string
          description: OK
        '400':
          description: invalid query parameter
        '404':
          description: package version
      summary: GetPackageReadme
      tags:
      - Registry
      x-pulumi-route-property:
        Visibility: Preview
  /api/registry/templates:
    get:
      description: Lists registry-backed templates with optional filtering, search, and pagination. This endpoint returns only registry-backed templates and does not include VCS-backed templates (those sourced from GitHub or GitLab repositories). No authentication is required. Results can be filtered by template name and owning organization (orgLogin). The search parameter performs case-insensitive partial matching against the template name, display name, description, metadata values, and runtime language. Results are paginated with a default limit of 100 per page; use the continuationToken from the response to retrieve subsequent pages. Each entry in the response includes the template's name, publisher, source, display name, description, runtime, language, readme URL, download URL, visibility, and updated timestamp.
      operationId: ListTemplates
      parameters:
      - description: Pagination token for retrieving the next page of results
        in: query
        name: continuationToken
        schema:
          type: string
      - description: 'Maximum number of results to return (default: 100)'
        in: query
        name: limit
        schema:
          format: int64
          type: integer
      - description: Filter by specific template name
        in: query
        name: name
        schema:
          type: string
      - description: Filter by owning organization
        in: query
        name: orgLogin
        schema:
          type: string
      - description: Search query matching template name, display name, description, metadata values, or runtime language. Multiple space-separated terms require all terms to match (AND semantics).
        in: query
        name: search
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTemplatesResponse'
          description: OK
        '400':
          description: Bad continuationToken
      summary: ListTemplates
      tags:
      - Registry
  /api/registry/templates/{source}/{publisher}/{name}/versions:
    get:
      description: Lists all versions of a specific template, ordered by version descending (latest first). The template is identified by its source, publisher organization, and name. Results are paginated with a default limit of 100 per page. Use the continuationToken from the response to retrieve subsequent pages. Each entry in the response contains the template version metadata. Returns 400 for an invalid continuationToken or 404 if the template does not exist.
      operationId: ListTemplateVersions
      parameters:
      - description: 'The template source: ''private'', ''github'', or ''gitlab'''
        in: path
        name: source
        required: true
        schema:
          type: string
      - description: Organization that owns the template
        in: path
        name: publisher
        required: true
        schema:
          type: string
      - description: The template name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Pagination token for retrieving the next page of results
        in: query
        name: continuationToken
        schema:
          type: string
      - description: 'Maximum number of results to return (default: 100)'
        in: query
        name: limit
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTemplateVersionsResponse'
          description: OK
        '400':
          description: Bad continuationToken
        '404':
          description: template
      summary: ListTemplateVersions
      tags:
      - Registry
    post:
      description: Initiates the first step of a two-phase template version publish workflow. This creates a publish transaction and returns an operationID along with a pre-signed upload URL for the template archive. The source must be 'private'. The caller must upload the template archive (a gzip-compressed tar file containing a root-level Pulumi.yaml with a template section, and optionally a README.md) to the provided URL, then call PostPublishTemplateVersionComplete with the operationID to finalize the publish. The request body must include the semantic version to publish. Returns 202 Accepted with the operation details, or 404 if the source does not exist.
      operationId: PostPublishTemplateVersion
      parameters:
      - description: 'The template source: ''private'', ''github'', or ''gitlab'''
        in: path
        name: source
        required: true
        schema:
          type: string
      - description: Organization that owns the template
        in: path
        name: publisher
        required: true
        schema:
          type: string
      - description: The template name
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartTemplatePublishRequest'
        x-originalParamName: body
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartTemplatePublishResponse'
          description: Accepted
        '404':
          description: Source
      summary: PostPublishTemplateVersion
      tags:
      - Registry
  /api/registry/templates/{source}/{publisher}/{name}/versions/{version}:
    delete:
      description: Removes a specific version of a template from the registry. The template is identified by its source (e.g. 'private', 'github', or 'gitlab'), publisher organization, name, and semantic version. If this is the last remaining version of the template, the 'force' query parameter must be set to true; doing so will also delete the template itself. Returns 204 No Content on success, or 400 if an invalid query parameter is provided.
      operationId: DeleteTemplateVersion
      parameters:
      - description: 'The template source: ''private'', ''github'', or ''gitlab'''
        in: path
        name: source
        required: true
        schema:
          type: string
      - description: Organization that owns the template
        in: path
        name: publisher
        required: true
        schema:
          type: string
      - description: The template name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Semantic version string of the template version to delete
        in: path
        name: version
        required: true
        schema:
          type: string
      - description: When true, allows deletion of the final remaining template version
        in: query
        name: force
        schema:
          type: boolean
      responses:
        '204':
          description: No Content
        '400':
          description: invalid query parameter
      summary: DeleteTemplateVersion
      tags:
      - Registry
    get:
      description: Retrieves metadata for a specific version of a registry template. The template is identified by its source (e.g. 'private', 'github', or 'gitlab'), publisher organization, and name. The version parameter accepts either a specific semantic version string or the special value 'latest' to retrieve the most recent version. The response includes the template's name, display name, description, runtime information, language, readme URL, download URL (a pre-signed URL valid for at least 5 minutes for retrieving the .tar.gz archive), repository slug (for VCS-backed templates), visibility, updated timestamp, metadata, and configuration values. Returns 400 if a specific version is provided for VCS-backed templates (which do not support versioning), or 404 if the template version does not exist.
      operationId: GetTemplateVersion
      parameters:
      - description: 'The template source: ''private'', ''github'', or ''gitlab'''
        in: path
        name: source
        required: true
        schema:
          type: string
      - description: Organization that owns the template
        in: path
        name: publisher
        required: true
        schema:
          type: string
      - description: The template name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Semantic version string or 'latest'
        in: path
        name: version
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTemplateResponse'
          description: OK
        '400':
          description: version cannot be specified for VCS-backed templates
        '404':
          description: template version
      summary: GetTemplateVersion
      tags:
      - Registry
  /api/registry/templates/{source}/{publisher}/{name}/versions/{version}/complete:
    post:
      description: Finalizes the second step of the two-phase template version publish workflow. After initiating a publish with PostPublishTemplateVersion and uploading the template archive (.tar.gz) to the pre-signed URL, call this endpoint with the operationID to complete the publish. The service validates that the archive was uploaded successfully before making the version available in the registry. Once complete, the template becomes available to the publisher's organization. Returns 201 Created on success, 400 for invalid operation state, 404 if the publish operation is not found, or 409 if the version already exists.
      operationId: PostPublishTemplateVersionComplete
      parameters:
      - description: 'The template source: ''private'', ''github'', or ''gitlab'''
        in: path
        name: source
        required: true
        schema:
          type: string
      - description: Organization that owns the template
        in: path
        name: publisher
        required: true
        schema:
          type: string
      - description: The template name
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: Semantic version string of the template version to complete
        in: path
        name: version
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishTemplateVersionCompleteRequest'
        x-originalParamName: body
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishTemplateVersionCompleteResponse'
          description: Created
        '400':
          description: Operation
        '404':
          description: Publish Operation
        '409':
          description: Version already exists
      summary: PostPublishTemplateVersionComplete
      tags:
      - Registry
components:
  schemas:
    PublishTemplateVersionCompleteRequest:
      description: PublishTemplateVersionCompleteRequest is a request to mark a template version publish operation as complete.
      properties:
        operationID:
          description: The identifier of the publish operation to complete.
          type: string
          x-order: 1
      required:
      - operationID
      type: object
    RegistryDocsProperty:
      description: A property of a Pulumi resource or function in the public API documentation. Name, type, and description are maps keyed by language. When a language filter is applied, each map contains exactly one entry matching the requested language.
      properties:
        deprecated:
          description: Whether this property is deprecated.
          type: boolean
          x-order: 5
        description:
          additionalProperties:
            type: string
          description: The property description in markdown, keyed by language.
          type: object
          x-order: 6
        name:
          additionalProperties:
            type: string
          description: The property name, keyed by language.
          type: object
          x-order: 1
        replaceOnChanges:
          description: Whether changing this property forces resource replacement.
          type: boolean
          x-order: 4
        required:
          description: Whether the property is required.
          type: boolean
          x-order: 3
        type:
          additionalProperties:
            type: string
          description: The display type of the property, keyed by language.
   

# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pulumi/refs/heads/main/openapi/pulumi-registry-api-openapi.yml