This page is for Octopus Deploy 3.0 and newer versions. You can view this page for Octopus 2.0

Skip to end of metadata
Go to start of metadata

Octopus.Client is an open source .NET library that makes it easy to write C# programs that manipulate the Octopus Deploy REST API.

Because the Octopus Deploy application itself is built entirely on the API, C# programs using the API can do anything that could be done by a user of the application itself.

The NuGet package contains both a .NET Framework build as well as a .NET Standard build. The .NET Framework build targets 4.5 or later and contains both the synchronous and asynchronous API. The .NET Standard build is compatible with a variety of runtimes, including .NET Core 1.0 and only contains the asynchronous API.

Getting started


The complete details for the API itself - where to find it, how to authenticate, the available resources and so-on - are available at the API documentation site.

To use the C# client, first install the package via NuGet:

Synchronous API

The easiest way to use the client is via the OctopusRepository helper:

If you don't want to provide an API key for authentication, you can leave it out and authenticate with the SignIn() method instead:

Asynchronous API (Octopus.Client 4.0+)

The easiest way to use the client is via the OctopusAsyncClient:

If you don't want to provide an API key for authentication, you can leave it out and authenticate with the SignIn() method instead:




Also see the OctoPosh project, which provides PowerShell commandlet wrappers around Octopus.Client


Working with resources

Resources can be loaded and saved with code like the following:

The repository methods all make direct HTTP requests, there's no "session" abstraction or transaction support.

Working directly with the client

For some operations not available through repositories it will be necessary to use the IOctopusClient type:

The entire API is accessible by traversing links - each resource carries a collection of links, like the "Connection" link on MachineResource shown above.

To start traversing links, IOctopusClient.RootDocument is provided:

(This example is superfluous as repository.Users.GetCurrent() wraps this common operation.)

Loading in an octopus step

To use Octopus.Client from inside an octopus (for example in a script step, a package install script, or the script console) by loading it from the server or tentacle application directory. The credentials would still need to be supplied to establish the connection. For example:

C# Script



The variable Octopus.Tentacle.Agent.ProgramDirectoryPath was added in server version 3.7.12, which can be used to obtain the directory that contains the Octopus.Client assembly. For prior versions of the server, the variable Octopus.Tentacle.Agent.ProgramDirectoryPath can be used, but that will not work for steps that run on the octopus server or cloud regions.

Documentation and samples

Documentation and samples for the Octopus Deploy REST API are available on the Octopus REST API GitHub site, along with Octopus.Client samples

  • No labels