Update project description with api

Is there a way to change or update the project description with the api or octopus cli? Currently many of the descriptions are empty, but I would like to populate all the descriptions with a value and can’t seem to figure out a way to do that.

Hi @nc,

First of all welcome to the Octopus boards!

Thanks for reaching out.

I think your best path forward here would be to use some API calls.

The pseudo code I would use is:
API Call to Projects/all
Iterate through each project using their IDs from previous call and do the following:
Bring down project body json with an API call
edit description to your liking
Use a POST api call and put the project back in place with the new description.

You may already know this, but if you are using Firefox or Chrome and hit F12 and go to the network tab, you can monitor the API calls that Octopus is running. This is the method I use for figuring out a way to automate things. It will give you the API call, as well as the JSON body that the API call is looking for.

As always test your scripts in a test environment before going to a production environment.

Here are some example scripts from our example repository: https://github.com/OctopusDeploy/OctopusDeploy-Api/tree/master/REST/PowerShell

This script I wrote is for editing a variable set, but you could probably apply a lot of the same logic and adapt it to edit the project description: https://github.com/OctopusDeploy/OctopusDeploy-Api/blob/master/REST/PowerShell/Variables/AddOrEditVariablesWithScoping.ps1

Please let me know if that works for you or if we need to dig in a bit more.


Hi Jeremy! Thank you for the quick response. I did have something similar to:

Get all project groups
For all projects in that group get the body
Tried to update the description only
Tried doing a post to ("$OctopusURL$($Project.Links.Self)") <- this could be where I’m messing up

Would I also need to post the entire body with just the description changed?

I wasn’t totally aware of the network tab on chrome/ff to check out the api calls. I’ll most definitely look into this in a little bit and see where I’m going wrong.

Thanks again for the help and links to check out. I’ll look at those soon and get back to you

Hi @nc,

You’re very welcome.

I haven’t tested this specific call, but the majority of API calls within Octopus need the entire body. Some can get by with pieces and parts and Octopus can fill in the rest, but I find its less work to just POST/PUT the entire thing (with whatever I want modified changed within that body)

The call for you should be doing will be something like POST http://URL/api/Spaces-#/projects/Projects-## with the full project body with the addition of the new description.

Please let me know how it goes.


Hey Jeremy, I got it figured out. I’m not really sure what I was doing when I was trying it earlier.

I’ll post what I used just in case anyone else runs into the same scenario. The script below gets all project groups and all projects within that group. If the description is empty (which was my case) it will update it with whatever you put between the quotes.

$octopusURL = "http://octourl"
$octopusAPIKey = "API-key"
$header =  @{ "X-Octopus-ApiKey" = $octopusAPIKey }
$projectGroupItems = (Invoke-Webrequest -uri "$octopusURL/api/Spaces-1/projectgroups?skip=0&take=2147483647" -Headers $header | ConvertFrom-Json).Items

foreach($group in $projectGroupItems){
    $projectsInGroup = Invoke-Webrequest -uri "$octopusURL/api/Spaces-1/projectgroups/$($group.Id)/projects" -Headers $header | ConvertFrom-Json
    foreach($project in ($projectsInGroup.Items)){
            $project.Description = "<string>"
            Invoke-Webrequest -Method Put -Uri "$octopusURL$($project.Links.Self)" -Headers $header -ContentType 'application/json' -Body ($project | ConvertTo-Json -Depth 10)

Hi @nc,

Thanks for the update. I’m glad to hear you got it going. I also appreciate you posting the script for others.

I hope you have a great rest of your week.


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