REST API to create worker pool and cloud region

Hi Team,
we are trying to automate creation of worker pools and cloud region using powershell [REST API]. Could you please provide some sample script using which we can achieve this ? thanks in advance

Sujesh Sasidharan

Hi Sujesh,

Thanks for getting in touch!

I’ve had a look through our script samples and I’m not seeing one specifically for this scenario. It may be worth reviewing them to see how we setup the headers and Space for the rest of the script though.

To create your script you can either check out the Swagger API doc for these specific endpoints which will provide the payload details you need.

Or my preferred method is to open up the browser dev tools with F12 and perform the desired action within the Octopus web portal. Every action within the portal uses the REST API so you can capture the request and payload within the dev tools and then use that to create your script.

When creating a worker pool I can see it performing a POST using the /api/<spaceId>/workerpools endpoint

And the payload is fairly basic

A basic script to add a worker pool would then be:

$ErrorActionPreference = "Stop";

# Define working variables
$octopusURL = "xxxxxx"
$octopusAPIKey = "API-xxxxxx"
$header = @{ "X-Octopus-ApiKey" = $octopusAPIKey }
$workerPoolName = "TestWorkerPool"

$spaceName = "PaulC"

# Get space
$spaces = Invoke-RestMethod -Uri "$octopusURL/api/spaces?partialName=$([uri]::EscapeDataString($spaceName))&skip=0&take=100" -Headers $header 
$space = $spaces.Items | Where-Object { $_.Name -eq $spaceName }

$body = @{
            Name = $workerPoolName
            WorkerPoolType = "StaticWorkerPool"
        } | ConvertTo-Json

Invoke-RestMethod -Uri "$octopusURL/api/$($space.Id)/workerpools" -Headers $header -Method Post -Body $body 

If you run into any issues whilst creating the scripts feel free to share them with us and we’ll do our best to get you unstuck.


Hi Paul,
Thanks. I was able to create the worker pools, I did try the same method with Cloud Region but I want to pass most of the parameters like

  • Name
  • Environments
  • Target Roles
  • Worker Pool
  • Tenanted Deployments
  • Associated Tenants

I did try to pass the parameters but was failing , Could you please help me in forming the json body for cloud region ?

Sujesh S

Creating the Cloud Region is a little more complicated as some of the parameters require an array, and also, the values will need to be the ID of the item, which you will need to retrieve beforehand.

This script for an Azure Web App target is similar to what you’ll need. It performs a search for the environment ID and places the roles and environments into an array for the JSON body.

You would need to amend some of the parameters to match what the Cloud Target payload looks like in dev tools and also add a section to retrieve the worker pool ID.

Hi Paul,
Thanks. I can retrieve the values that needs to be placed inside the json body but even after providing all the values[hard coded] in the json body it fails with the error shown below. Could you help in identifying the parameters that needs to be passed atleast the basic ones to create an cloud region.

I can’t see anything immediately wrong with the parameters.

Would you be able to add the script that you’re running so I can give it a try and see if I can figure out the issue?

Thanks Paul for the support , I was able to create the cloud region now. I had to order my request in the same format which solved the issue

1 Like

This topic was automatically closed 31 days after the last reply. New replies are no longer allowed.