openapi: 3.0.3 info: description: APIs and Definitions for the Pulumi Cloud product. title: Pulumi APIs AccessTokens PolicyGroups API version: 1.0.0 tags: - name: PolicyGroups paths: /api/orgs/{orgName}/policygroups: get: description: Returns a list of all Policy Groups for the organization. Policy Groups define which Policy Packs are enforced on which stacks, with configurable enforcement levels (advisory, mandatory, or disabled) per pack. Every organization has a default Policy Group, and additional groups can be created to apply different policy sets to different environments (e.g., stricter enforcement in production). operationId: ListPolicyGroups parameters: - description: The organization name in: path name: orgName required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/AppListPolicyGroupsResponse' description: OK '404': description: Organization not found summary: ListPolicyGroups tags: - PolicyGroups post: description: Creates a new Policy Group for an organization. Policy Groups define which Policy Packs are enforced on which stacks or cloud accounts, with configurable enforcement levels (advisory, mandatory, or disabled) per pack. This allows different policy strictness for different environments, such as advisory-only in development and mandatory in production. operationId: NewPolicyGroup parameters: - description: The organization name in: path name: orgName required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/NewPolicyGroupRequest' x-originalParamName: body responses: '204': description: No Content '400': description: Invalid entity type or invalid Policy Group name '404': description: Organization not found '409': description: Policy Group already exists summary: NewPolicyGroup tags: - PolicyGroups /api/orgs/{orgName}/policygroups/metadata: get: description: Returns high-level policy protection metrics for an organization, including the number of stacks protected by policy enforcement, the total number of Policy Groups, and overall policy coverage statistics. operationId: GetPolicyGroupMetadata parameters: - description: The organization name in: path name: orgName required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/PolicyGroupMetadata' description: OK '404': description: Organization not found summary: GetPolicyGroupMetadata tags: - PolicyGroups /api/orgs/{orgName}/policygroups/{policyGroup}: delete: description: Deletes a Policy Group from an organization. A Policy Group defines which Policy Packs are enforced on which stacks, with configurable enforcement levels (advisory, mandatory, or disabled) per pack. The organization's default Policy Group cannot be deleted. Deleting a Policy Group removes all policy enforcement associations for the stacks that were assigned to it. operationId: DeletePolicyGroup parameters: - description: The organization name in: path name: orgName required: true schema: type: string - description: The policy group name in: path name: policyGroup required: true schema: type: string responses: '204': description: No Content '400': description: Cannot delete the default Policy Group '404': description: Organization or Policy Group not found summary: DeletePolicyGroup tags: - PolicyGroups get: description: Returns the details of a specific Policy Group, including the list of Policy Packs applied to it and their enforcement levels (advisory, mandatory, or disabled), as well as the stacks or cloud accounts assigned to the group. Policy Groups enable targeted policy enforcement by associating sets of policies with specific infrastructure resources. operationId: GetPolicyGroup parameters: - description: The organization name in: path name: orgName required: true schema: type: string - description: The policy group name in: path name: policyGroup required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/PolicyGroup' description: OK '404': description: Organization or Policy Group not found summary: GetPolicyGroup tags: - PolicyGroups patch: description: 'Updates a Policy Group''s configuration. This multi-purpose endpoint supports several operations in a single request via different body fields: - `newName`: rename the policy group - `addStack` / `removeStack`: add or remove stacks (with `name` and `routingProject` fields) - `addPolicyPack` / `removePolicyPack`: add or remove policy packs (with `name`, `version`, `versionTag`, and optional `config`) - `addInsightsAccount` / `removeInsightsAccount`: add or remove Insights accounts Enforcement levels for policy packs are `advisory`, `mandatory`, or `disabled`.' operationId: UpdatePolicyGroup parameters: - description: The organization name in: path name: orgName required: true schema: type: string - description: The policy group name in: path name: policyGroup required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdatePolicyGroupRequest' x-originalParamName: body responses: '204': description: No Content '400': description: Bad Request '404': description: Organization, Policy Group, Stack, Account, or Policy Pack not found summary: UpdatePolicyGroup tags: - PolicyGroups /api/orgs/{orgName}/policygroups/{policyGroup}/batch: patch: description: BatchUpdatePolicyGroup applies multiple update operations to the Policy Group efficiently. Each operation in the list uses the same fields as UpdatePolicyGroupRequest. Operations are grouped by type (adds, removes) and processed in batches for efficiency. operationId: BatchUpdatePolicyGroup parameters: - description: The organization name in: path name: orgName required: true schema: type: string - description: The policy group name in: path name: policyGroup required: true schema: type: string requestBody: content: application/json: schema: items: $ref: '#/components/schemas/UpdatePolicyGroupRequest' type: array x-originalParamName: body responses: '204': description: No Content '400': description: Bad Request '404': description: Organization, Policy Group, Stack, Account, or Policy Pack not found summary: BatchUpdatePolicyGroup tags: - PolicyGroups components: schemas: AppListPolicyGroupsResponse: description: ListPolicyGroupsResponse lists a summary of the organization's Policy Groups. properties: policyGroups: description: List of policy groups items: $ref: '#/components/schemas/AppPolicyGroupSummary' type: array x-order: 1 required: - policyGroups type: object AppPolicyGroupSummary: description: 'PolicyGroupSummary details the name, applicable stacks and the applied Policy Packs for an organization''s Policy Group.' properties: entityType: description: The type of entity this policy group targets (e.g. stacks, accounts). enum: - stacks - accounts type: string x-order: 5 x-pulumi-model-property: enumTypeName: AppEntityType enumComments: EntityType indicates the type of entity a policy group applies to enumFieldComments: - Stacks indicates the policy group applies to stacks - Accounts indicates the policy group applies to accounts isOrgDefault: description: Whether this is the organization's default policy group, applied to all stacks not in another group. type: boolean x-order: 2 mode: description: The enforcement mode of the policy group. enum: - audit - preventative type: string x-order: 6 x-pulumi-model-property: enumTypeName: PolicyGroupMode enumComments: PolicyGroupMode represents the enforcement mode for a policy group name: description: The unique name of the policy group. type: string x-order: 1 numAccounts: description: Number of cloud accounts assigned to this policy group. format: int64 type: integer x-order: 4 numEnabledPolicyPacks: description: Number of policy packs currently enabled in this group. format: int64 type: integer x-order: 7 numStacks: description: Number of stacks assigned to this policy group. format: int64 type: integer x-order: 3 required: - entityType - isOrgDefault - mode - name - numEnabledPolicyPacks - numStacks type: object AppPolicyPackMetadata: description: PolicyPackMetadata is the metadata of a Policy Pack. properties: config: additionalProperties: type: object description: 'The configuration that is to be passed to the Policy Pack. This map ties Policies with their configuration.' type: object x-order: 5 displayName: description: The display name type: string x-order: 2 environments: description: References to ESC environments to use for this policy pack. items: type: string type: array x-order: 6 name: description: The name type: string x-order: 1 version: description: The version number format: int64 type: integer x-order: 3 versionTag: description: The version tag type: string x-order: 4 required: - displayName - name - version - versionTag type: object NewPolicyGroupRequest: description: NewPolicyGroupRequest is the request struct to create a new Policy Group. properties: agentPoolId: description: Agent pool ID for policy evaluation. Defaults to Pulumi hosted pool if not specified. type: string x-order: 4 entityType: description: The type of entities this policy group applies to (stacks or accounts). enum: - stacks - accounts type: string x-order: 2 x-pulumi-model-property: enumTypeName: PolicyGroupEntityType enumComments: PolicyGroupEntityType represents the type of entities a policy group applies to mode: description: The enforcement mode for the policy group (audit or preventative). Defaults to 'audit' for account policy groups, 'preventative' for stack policy groups. enum: - audit - preventative type: string x-order: 3 x-pulumi-model-property: enumTypeName: PolicyGroupMode enumComments: PolicyGroupMode represents the enforcement mode for a policy group name: description: The name of the new policy group. type: string x-order: 1 required: - entityType - name type: object JobRun: description: JobRun contains information about a job run. properties: lastUpdated: description: When the job was last updated format: date-time type: string x-order: 3 started: description: When the job started running format: date-time type: string x-order: 2 status: description: The current status of the job run enum: - not-started - accepted - running - failed - succeeded - skipped type: string x-order: 1 x-pulumi-model-property: enumTypeName: JobStatus enumComments: JobStatus describes the status of a job run. enumFieldNames: - NotStarted - Accepted - Running - Failed - Succeeded - Skipped enumFieldComments: - JobStatusNotStarted indicates that a job has not yet started. - JobStatusAccepted indicates that a job has been accepted for execution, but is not yet running. - JobStatusRunning indicates that a job is running. - JobStatusFailed indicates that a job has failed. - JobStatusSucceeded indicates that a job has succeeded. - JobStatusSkipped indicates that a job has skipped as there are fresher deployments to execute in the queue. steps: description: The list of step runs within this job items: $ref: '#/components/schemas/StepRun' type: array x-order: 5 timeout: description: The timeout duration for the job in nanoseconds (Go time.Duration). format: int64 type: integer x-order: 4 worker: description: Information about the worker executing this job type: object x-order: 6 required: - status - steps - timeout type: object PolicyGroup: description: PolicyGroup details the name, applicable entities and the applied PolicyPacks. properties: accounts: description: List of Insights account names that are members of this policy group. items: type: string type: array x-order: 7 agentPoolId: description: Agent pool ID for audit policy evaluation. Defaults to Pulumi hosted pool if not specified. type: string x-order: 8 appliedPolicyPacks: description: List of policy packs that are applied to this policy group. items: $ref: '#/components/schemas/AppPolicyPackMetadata' type: array x-order: 6 entityType: description: The type of entities this policy group applies to (stacks or accounts). enum: - stacks - accounts type: string x-order: 3 x-pulumi-model-property: enumTypeName: PolicyGroupEntityType enumComments: PolicyGroupEntityType represents the type of entities a policy group applies to isOrgDefault: description: True if this is either the default stacks or default accounts policy group for the organization. type: boolean x-order: 2 mode: description: The enforcement mode for the policy group (audit or preventative). enum: - audit - preventative type: string x-order: 4 x-pulumi-model-property: enumTypeName: PolicyGroupMode enumComments: PolicyGroupMode represents the enforcement mode for a policy group name: description: The name of the policy group. type: string x-order: 1 stacks: description: List of stacks that are members of this policy group. items: $ref: '#/components/schemas/AppPulumiStackReference' type: array x-order: 5 required: - accounts - appliedPolicyPacks - entityType - isOrgDefault - mode - name - stacks type: object AppUpdatePolicyGroupRequest: description: UpdatePolicyGroupRequest modifies a Policy Group. properties: addPolicyPack: $ref: '#/components/schemas/AppPolicyPackMetadata' description: A policy pack to enable for the policy group. x-order: 4 addStack: $ref: '#/components/schemas/AppPulumiStackReference' description: A stack to add to the policy group. x-order: 2 newName: description: The new name to assign to the policy group. type: string x-order: 1 removePolicyPack: $ref: '#/components/schemas/AppPolicyPackMetadata' description: A policy pack to disable for the policy group. x-order: 5 removeStack: $ref: '#/components/schemas/AppPulumiStackReference' description: A stack to remove from the policy group. x-order: 3 type: object UserInfo: description: 'UserInfo contains just the display information for a user. This information may be returned from public APIs, and as such this structure must not contain sensitive information. Please refer to User for this sort of thing.' properties: avatarUrl: description: The URL of the user's avatar image. type: string x-order: 3 email: description: 'IMPORTANT: The email address of the user is only included on a few admin-only APIs. For nearly all APIs that return a UserInfo object, this will not be provided. considered sensitive information.' type: string x-order: 4 githubLogin: description: The user's login name. type: string x-order: 2 name: description: The user's display name. type: string x-order: 1 required: - avatarUrl - githubLogin - name type: object ScanStatus: allOf: - $ref: '#/components/schemas/WorkflowRun' - description: The status of an Insights account scan, including resource count. properties: accountName: description: The name of the insights account associated with this scan. type: string x-order: 1 resourceCount: description: The number of resources discovered by this scan. format: int64 type: integer x-order: 2 type: object UpdatePolicyGroupRequest: allOf: - $ref: '#/components/schemas/AppUpdatePolicyGroupRequest' - description: UpdatePolicyGroupRequest modifies a Policy Group. properties: addInsightsAccount: $ref: '#/components/schemas/InsightsAccount' description: An Insights account to add to the policy group. x-order: 1 agentPoolId: description: Agent pool ID for audit policy evaluation. Set to empty string to clear, omit to leave unchanged. type: string x-order: 3 removeInsightsAccount: $ref: '#/components/schemas/InsightsAccount' description: An Insights account to remove from the policy group. x-order: 2 type: object StepRun: description: StepRun contains information about a step run. properties: lastUpdated: description: The timestamp when the step was last updated. format: date-time type: string x-order: 4 name: description: The name of the step. type: string x-order: 1 started: description: The timestamp when the step started. format: date-time type: string x-order: 3 status: description: The current status of the step. enum: - not-started - running - failed - succeeded type: string x-order: 2 x-pulumi-model-property: enumTypeName: StepStatus enumComments: StepStatus describes the status of a step in a workflow job run. enumFieldNames: - NotStarted - Running - Failed - Succeeded enumFieldComments: - StepStatusNotStarted indicates that a step has not yet started. - StepStatusRunning indicates that a step is running. - StepStatusFailed indicates that a step has failed. - StepStatusSucceeded indicates that a step has succeeded. required: - name - status type: object PolicyGroupMetadata: description: PolicyGroupMetadata returns policy protection metrics for an organization. properties: AuditStackResources: description: Number of resources in stacks in audit policy groups format: int32 type: integer x-order: 6 AuditStacks: description: Number of stacks in audit policy groups format: int32 type: integer x-order: 5 PreventativeStackResources: description: Number of resources in stacks in preventative policy groups format: int32 type: integer x-order: 4 PreventativeStacks: description: Number of stacks in preventative policy groups format: int32 type: integer x-order: 3 ProtectedAccountResources: description: Number of resources in accounts in policy groups format: int32 type: integer x-order: 10 ProtectedAccounts: description: Number of accounts in policy groups format: int32 type: integer x-order: 9 ProtectedStackResources: description: 'Number of resources in unique stacks in any policy group (preventative or audit). Deprecated: Use PreventativeStackResources and AuditStackResources for breakdown by mode' format: int32 type: integer x-order: 2 ProtectedStacks: description: 'Number of unique stacks in any policy group (preventative or audit). Deprecated: Use PreventativeStacks and AuditStacks for breakdown by mode' format: int32 type: integer x-order: 1 TotalAccountResources: description: Total number of resources in all accounts format: int32 type: integer x-order: 12 TotalAccounts: description: Total number of accounts in the organization format: int32 type: integer x-order: 11 TotalStackResources: description: Total number of resources in all stacks format: int32 type: integer x-order: 8 TotalStacks: description: Total number of stacks in the organization format: int32 type: integer x-order: 7 required: - AuditStackResources - AuditStacks - PreventativeStackResources - PreventativeStacks - ProtectedAccountResources - ProtectedAccounts - ProtectedStackResources - ProtectedStacks - TotalAccountResources - TotalAccounts - TotalStackResources - TotalStacks type: object InsightsAccount: description: A cloud account configured for Pulumi Insights resource discovery. properties: agentPoolID: description: 'The ID of the agent pool to run account discovery workflows. If not specified, discovery will use the default agent pool.' type: string x-order: 8 id: description: ID of the account. type: string x-order: 1 name: description: The name of the account. type: string x-order: 2 ownedBy: $ref: '#/components/schemas/UserInfo' description: The user with ownership of this Insights account x-order: 3 provider: description: The cloud provider for the account (e.g., aws, gcp, azure-native). type: string x-order: 4 providerConfig: description: Provider-specific configuration for the account. type: object x-order: 9 providerEnvRef: description: 'Reference to an ESC environment containing provider credentials, in the format ''project/environment'' with an optional @version suffix.' type: string x-order: 6 providerVersion: description: The version of the Pulumi provider package used for discovery. type: string x-order: 5 scanStatus: $ref: '#/components/schemas/ScanStatus' description: Status of the last discovery scan for this account. x-order: 10 scheduledScanEnabled: description: If true, the account is scheduled for recurring discovery. type: boolean x-order: 7 required: - id - name - ownedBy - provider - scheduledScanEnabled type: object AppPulumiStackReference: description: PulumiStackReference contains the StackName and ProjectName of the stack. properties: name: description: The name type: string x-order: 1 routingProject: description: The routing project type: string x-order: 2 required: - name - routingProject type: object WorkflowRun: description: WorkflowRun contains information about a workflow run. properties: finishedAt: description: The time the workflow run finished, if completed. format: date-time type: string x-order: 6 id: description: The unique identifier of the workflow run. type: string x-order: 1 jobTimeout: description: The timeout for jobs in the workflow run. format: date-time type: string x-order: 8 jobs: description: The list of job runs within the workflow. items: $ref: '#/components/schemas/JobRun' type: array x-order: 9 lastUpdatedAt: description: The time the workflow run was last updated. format: date-time type: string x-order: 7 orgId: description: The organization ID. type: string x-order: 2 startedAt: description: The time the workflow run started. format: date-time type: string x-order: 5 status: description: The current status of the workflow run. enum: - running - failed - succeeded type: string x-order: 4 x-pulumi-model-property: enumTypeName: WorkflowRunStatus enumComments: WorkflowRunStatus describes the status of a workflow run. enumFieldComments: - WorkflowRunStatusRunning indicates that a workflow run is running. - WorkflowRunStatusFailed indicates that a workflow run has failed. - WorkflowRunStatusSucceeded indicates that a workflow run has succeeded. userId: description: The user ID who initiated the workflow run. type: string x-order: 3 required: - finishedAt - id - jobTimeout - lastUpdatedAt - orgId - startedAt - status - userId type: object