Invoke RunBook

Hi Team,

I have requirement to invoke RunBooks(under Operation) which are associated with Project using API by giving a parameter Environment and Tenant (i.e it should invoke project which are connected to Environment and Tenant).

Can you please help me here.

Santhosh Shet

HI @santoshuponi,

Thanks for getting in touch!

This is a basic script that will run a specific runbook and runbook snapshot with the ability to specify the desired environment and tenant. It is very barebones and requires the specific IDs for each resource, this could be enhanced by adding in some lookups on the names to retrieve the required IDs.

Add-Type -Path 'Octopus.Client.dll' 

$apikey = 'API-xxxxx' # Get this from your profile
$octopusURI = 'http://xxxxx' # Your Octopus Server address

$runbookId = "Runbooks-1" # Get this from /api/runbooks
$runbookSnapshotId = "RunbookSnapshots-1" # Get this from /api/runbookSnapshots
$environmentId = "Environments-1" # Get this from /api/environments
$tenantId = "Tenant-1" # Get this from /api/tenants

$endpoint = New-Object Octopus.Client.OctopusServerEndpoint $octopusURI,$apikey 
$repository = New-Object Octopus.Client.OctopusRepository $endpoint

$runbook = $repository.RunbookSnapshots.Get($runbookSnapshotId)
$deployment = New-Object Octopus.Client.Model.RunbookRunResource
$deployment.RunbookId = $runbookId
$deployment.RunbookSnapshotId = $runbookSnapshotId
$deployment.EnvironmentId = $environmentId
$deployment.TenantId = $tenantId



Hi Paul,

This script is failing because of " $runbook = $repository.RunbookSnapshots.Get($runbookSnapshotId) " , since RunbookSnapshots is in valid .

Can you please check and let me know the update script .

Santhosh Shet

Hi @santoshuponi,

The script worked for me when using a published runbook. You will need to replace the ID values with ones that exist within your server.


Hi Paul ,

Yes i have passed right values , but it is failing .

Are you using an up to date version of octopus.client.dll?

Can you provide the exact error message that is occurring?

Do you use Spaces at all? This script currently used the default space.

I could noticed when i run $repository

Error :

Ok, so I would check the version of octopus.client being used. The latest is 8.8.2

Hi Paul ,

Cant we use API to deploy Runbook !!

Hi @santoshuponi,

This method is using the API. The Octopus.client is a library that makes it easier to script and manipulate the REST API.

If you would prefer to run a script that uses the REST API without this library that is definitely doable. You would just need to use the Swagger documentation to convert the sample script above to the pure REST API calls.


Thanks Paul,

i am struck in finding the right API to trigger Runbook execution .
Can you please help me.

The easiest way to determine which API endpoint is needed is to perform the task you want to do within the UI and inspect which API endpoints are being used.

e.g. when running a runbook snapshot, I can see runbookRuns being used

You can then reference this against the Swagger definition and with some testing figure out which calls you need for the task you want.

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