Docs Home Pulumi IaC Pulumi ESC Pulumi Insights Pulumi IDP Pulumi Cloud Packages Tutorials
  1. Docs
  2. Pulumi Cloud
  3. Pulumi Cloud REST API
  4. Services

Services

    Services are a way to group and organize related resources in Pulumi Cloud. The Services API allows you to create, manage, and organize collections of resources that work together to provide a specific capability.

    Service Operations

    The API provides endpoints for the following operations:

    • Creating and managing services
    • Listing available services
    • Adding and removing items from services

    Create Service

    Create a new service.

    POST /api/orgs/{organization}/services

    Parameters

    ParameterTypeInDescription
    organizationstringpathorganization name
    ownerTypestringbodytype of the owner (e.g. “user”, “team”)
    ownerNamestringbodyname of the owner
    namestringbodyname of the service
    descriptionstringbodyOptional. description of the service
    propertiesarraybodyOptional. list of properties to set on the service
    itemsarraybodyOptional. list of items to add during service creation

    Example

    curl \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  --X POST \
  --data '{ "ownerType": "team", "ownerName": "team1", "name": "my-cool-service", "description": "My service" }' \
  https://api.pulumi.com/api/orgs/my-org/services

    Default response

    Status: 200 OK

    {
  "organizationName": "org1",
  "name": "service1",
  "description": "My service",
  "itemCountSummary": {},
  "members": [
    {
      "name": "team1",
      "avatarURL": "https://example.com/avatar.png",
      "type": "team"
    }
  ],
  "properties": [],
  "owner": {
    "name": "team1",
    "avatarURL": "https://example.com/avatar.png",
    "type": "team"
  }
}

    List Services

    List all services in an organization.

    GET /api/orgs/{organization}/services

    Parameters

    ParameterTypeInDescription
    organizationstringpathorganization name

    Example

    curl \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  https://api.pulumi.com/api/orgs/my-org/services

    Head Service

    Check if a service exists.

    HEAD /api/orgs/{organization}/services/{ownerType}/{ownerName}/{serviceName}

    Parameters

    ParameterTypeInDescription
    organizationstringpathorganization name
    ownerTypestringpathtype of the owner (e.g. “user”, “team”)
    ownerNamestringpathname of the owner
    serviceNamestringpathname of the service

    Get Service

    Get details of a specific service.

    GET /api/orgs/{organization}/services/{ownerType}/{ownerName}/{serviceName}

    Parameters

    ParameterTypeInDescription
    organizationstringpathorganization name
    ownerTypestringpathtype of the owner (e.g. “user”, “team”)
    ownerNamestringpathname of the owner
    serviceNamestringpathname of the service

    Example

    curl \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  https://api.pulumi.com/api/orgs/my-org/services/team/my-team/my-service

    Update Service

    Update an existing service.

    PATCH /api/orgs/{organization}/services/{ownerType}/{ownerName}/{serviceName}

    Parameters

    ParameterTypeInDescription
    organizationstringpathorganization name
    ownerTypestringpathtype of the owner (e.g. “user”, “team”)
    ownerNamestringpathname of the owner
    serviceNamestringpathname of the service
    namestringbodyOptional. new name for the service
    descriptionstringbodyOptional. new description for the service
    propertiesarraybodyOptional. list of properties to set on the service

    Example

    curl \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  --request POST \
  --data '{ "name": "new-service-name", "description": "New description" }' \
  https://api.pulumi.com/api/orgs/my-org/services/team/my-team/my-service

    Delete Service

    Delete a service.

    DELETE /api/orgs/{organization}/services/{ownerType}/{ownerName}/{serviceName}

    Parameters

    ParameterTypeInDescription
    organizationstringpathorganization name
    ownerTypestringpathtype of the owner (e.g. “user”, “team”)
    ownerNamestringpathname of the owner
    serviceNamestringpathname of the service
    forcebooleanqueryOptional. ignore protections and force delete the service

    Example

    curl \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  --request DELETE \
  https://api.pulumi.com/api/orgs/my-org/services/team/my-team/my-service?force=true

    Add Service Items

    Add items to a service.

    POST /api/orgs/{organization}/services/{ownerType}/{ownerName}/{serviceName}/items

    Parameters

    ParameterTypeInDescription
    organizationstringpathorganization name
    ownerTypestringpathtype of the owner (e.g. “user”, “team”)
    ownerNamestringpathname of the owner
    serviceNamestringpathname of the service
    itemsarraybodyarray of items to add to the service

    Example

    curl \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  --request POST \
  --data '{ "items": [
    {
      "type": "stack",
      "name": "my-project/my-stack"
    },
    {
      "type": "environment",
      "name": "my-project/my-environment
    }
  ] }' \
  https://api.pulumi.com/api/orgs/my-org/services/team/my-team/my-service/items

    Remove Service Item

    Remove an item from a service.

    DELETE /api/orgs/{organization}/services/{ownerType}/{ownerName}/{serviceName}/items/{itemType}/{itemName}

    Parameters

    ParameterTypeInDescription
    organizationstringpathorganization name
    ownerTypestringpathtype of the owner (e.g. “user”, “team”)
    ownerNamestringpathname of the owner
    serviceNamestringpathname of the service
    itemTypestringpathtype of the item to remove
    itemNamestringpathname of the item to remove

    Example

    curl \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  --request DELETE \
  https://api.pulumi.com/api/orgs/my-org/services/team/my-team/my-service/items/stack/my-project/my-stack