Runbooks

GET /api/{spaceId}/projects/{projectId}/git/migrate-runbooks

Also reachable at /api/spaces/{spaceIdentifier}/projects/{projectId}/git/migrate-runbooks.

Path Parameters

• projectId string (required)
• spaceId string (required)

Response

200 — Returns as summary of the runbooks that will be converted to Git

• DraftRunbooks array of object
  • RunbookId string
  • RunbookName string
• PublishedRunbooks array of object
  • RunbookId string
  • RunbookName string

{
  "DraftRunbooks": [
    {
      "RunbookId": "string",
      "RunbookName": "string"
    }
  ],
  "PublishedRunbooks": [
    {
      "RunbookId": "string",
      "RunbookName": "string"
    }
  ]
}

GET /api/{spaceId}/projects/{projectId}/runbooks

Also reachable at /api/projects/{projectId}/runbooks, /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks.

Path Parameters

• projectId string (required)
  The ID of the project.
• spaceId string (required)
  The ID of the space containing the resource(s).

Query Parameters

• excludedRunbookTags array of string
  A list of tag IDs to exclude runbooks by. Returns runbooks that have none of the specified tags.
• partialName string
  A partial or complete name to search on. This will perform a “contains” style match against the supplied name or name-fragment.
• runbookTags array of string
  A list of tag IDs to filter runbooks by. Returns runbooks that have any of the specified tags.
• skip integer
  Number of items to skip. Defaults to zero. Minimum 0.
• take integer
  Number of items to take. Defaults to 30. Minimum 0.

Response

200 — Success

• Id string
  Gets or sets a unique identifier for this resource.
• ItemType string
• Items array of object
  • CancelQueuedTasks boolean
  • CancelRunningTasks boolean
  • ConnectivityPolicy object
  • DefaultGuidedFailureMode enum
    Allowed values: EnvironmentDefault, Off, On.
  • Description string
  • EnvironmentScope enum
    Allowed values: All, Specified, FromProjectLifecycles.
  • Environments array of string
  • FailTargetDiscovery boolean
  • ForcePackageDownload boolean
  • Id string
    Gets or sets a unique identifier for this resource.
  • LastModifiedBy string
    Gets or sets the username of the user who last modified this resource.
  • LastModifiedOn string
    Gets or sets the date/time that this resource was last modified. Format date-time.
  • Links object
    Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
  • MultiTenancyMode enum
    Allowed values: Untenanted, TenantedOrUntenanted, Tenanted.
  • Name string
  • ProjectId string
  • PublishedRunbookSnapshotId string
  • RunRetentionPolicy object
  • RunbookProcessId string
  • RunbookTags array of string
    List of tags assigned to this runbook.
  • Slug string
  • SpaceId string
• ItemsPerPage integer
• LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
• LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
• LastPageNumber integer
• Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
• NumberOfPages integer
• TotalResults integer

{
  "Id": "string",
  "ItemType": "string",
  "Items": [
    {
      "CancelQueuedTasks": true,
      "CancelRunningTasks": true,
      "ConnectivityPolicy": {
        "AllowDeploymentsToNoTargets": true,
        "ExcludeUnhealthyTargets": true,
        "SkipMachineBehavior": "None",
        "TargetRoles": [
          "string"
        ]
      },
      "DefaultGuidedFailureMode": "EnvironmentDefault",
      "Description": "string",
      "EnvironmentScope": "All",
      "Environments": [
        "string"
      ],
      "FailTargetDiscovery": true,
      "ForcePackageDownload": true,
      "Id": "string",
      "LastModifiedBy": "string",
      "LastModifiedOn": "2020-01-01T00:00:00.000Z",
      "Links": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "MultiTenancyMode": "Untenanted",
      "Name": "string",
      "ProjectId": "string",
      "PublishedRunbookSnapshotId": "string",
      "RunRetentionPolicy": {
        "QuantityToKeep": 0,
        "ShouldKeepForever": true,
        "Strategy": "string",
        "Unit": "Days"
      },
      "RunbookProcessId": "string",
      "RunbookTags": [
        "string"
      ],
      "Slug": "string",
      "SpaceId": "string"
    }
  ],
  "ItemsPerPage": 0,
  "LastModifiedBy": "string",
  "LastModifiedOn": "2020-01-01T00:00:00.000Z",
  "LastPageNumber": 0,
  "Links": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "NumberOfPages": 0,
  "TotalResults": 0
}

POST /api/{spaceId}/projects/{projectId}/runbooks

Also reachable at /api/projects/{projectId}/runbooks, /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks.

Path Parameters

• projectId string (required)
  The Project that contains the Runbook.
• spaceId string (required)
  The ID of the space containing the resource(s).

Request Body

• Clone string
  The ID of an existing database runbook to copy. Cloning brings across the source runbook’s settings, its process and steps, and any project triggers that target it. The source runbook’s tags come across too, unless you supply RunbookTags. Leave unset to create a runbook from scratch, which starts with an empty process.
• ConnectivityPolicy object
  • AllowDeploymentsToNoTargets boolean
  • ExcludeUnhealthyTargets boolean
  • SkipMachineBehavior enum
    Allowed values: None, SkipUnavailableMachines.
  • TargetRoles array of string
• DefaultGuidedFailureMode enum
  What a run does when a step fails. One of ‘EnvironmentDefault’ (follow the target environment’s setting), ‘Off’ (fail the run immediately, the default), or ‘On’ (pause the run and wait for someone to choose whether to retry, ignore or abort).
  Allowed values: EnvironmentDefault, Off, On.
• Description string
  The description of the Runbook to create.
• EnvironmentScope enum
  Which environments the runbook may be run in. One of ‘All’ (every environment in the space, the default), ‘Specified’ (only the environments listed in Environments), or ‘FromProjectLifecycles’ (only the environments used by the project’s lifecycles).
  Allowed values: All, Specified, FromProjectLifecycles.
• Environments array of string
  The environments the runbook may be run in. Only applies when EnvironmentScope is ‘Specified’; ignored otherwise.
• ForcePackageDownload boolean
  Re-download every package on each run instead of reusing the copy already cached on the deployment target.
• MultiTenancyMode enum
  Whether the runbook can be run for tenants. One of ‘Untenanted’ (untenanted runs only, the default), ‘Tenanted’ (a tenant must be supplied for every run), or ‘TenantedOrUntenanted’ (either is allowed).
  Allowed values: Untenanted, TenantedOrUntenanted, Tenanted.
• Name string (required)
  The name of the Runbook to create. Minimum length 1.
• ProjectId string (required)
  The ID of the project to create the runbook in. Must be a project that stores its runbooks in the Octopus database.
• PublishedRunbookSnapshotId string
  Leave unset. A snapshot can only be published after the runbook exists and has a process.
• RunRetentionPolicy object (required)
  • QuantityToKeep integer
  • ShouldKeepForever boolean
  • Strategy string
  • Unit enum
    Allowed values: Days, Items.
• RunbookProcessId string
  Leave unset. Octopus creates an empty runbook process for the new runbook and links it automatically.
• RunbookTags array of string
  Tags to apply to the runbook, each written as “TagSet/Tag” using either the names or the IDs of the tag set and tag (for example “Ops/Nightly”). Call find_tag_sets to discover which tag sets apply to runbooks and what tags they contain.
• Slug string
  A short URL-friendly identifier for the runbook, unique within the project. Generated from the name when omitted.
• SpaceId string (required)
  The ID of the space containing the resource(s).

Response

201 — Created

• CancelQueuedTasks boolean
• CancelRunningTasks boolean
• ConnectivityPolicy object
  • AllowDeploymentsToNoTargets boolean
  • ExcludeUnhealthyTargets boolean
  • SkipMachineBehavior enum
    Allowed values: None, SkipUnavailableMachines.
  • TargetRoles array of string
• DefaultGuidedFailureMode enum
  Allowed values: EnvironmentDefault, Off, On.
• Description string
• EnvironmentScope enum
  Allowed values: All, Specified, FromProjectLifecycles.
• Environments array of string
• FailTargetDiscovery boolean
• ForcePackageDownload boolean
• Id string
  Gets or sets a unique identifier for this resource.
• LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
• LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
• Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
• MultiTenancyMode enum
  Allowed values: Untenanted, TenantedOrUntenanted, Tenanted.
• Name string
• ProjectId string
• PublishedRunbookSnapshotId string
• RunRetentionPolicy object
  • QuantityToKeep integer
  • ShouldKeepForever boolean
  • Strategy string
  • Unit enum
    Allowed values: Days, Items.
• RunbookProcessId string
• RunbookTags array of string
  List of tags assigned to this runbook.
• Slug string
• SpaceId string

{
  "Clone": "string",
  "ConnectivityPolicy": {
    "AllowDeploymentsToNoTargets": true,
    "ExcludeUnhealthyTargets": true,
    "SkipMachineBehavior": "None",
    "TargetRoles": [
      "string"
    ]
  },
  "DefaultGuidedFailureMode": "EnvironmentDefault",
  "Description": "string",
  "EnvironmentScope": "All",
  "Environments": [
    "string"
  ],
  "ForcePackageDownload": true,
  "MultiTenancyMode": "Untenanted",
  "Name": "string",
  "ProjectId": "string",
  "PublishedRunbookSnapshotId": "string",
  "RunRetentionPolicy": {
    "QuantityToKeep": 0,
    "ShouldKeepForever": true,
    "Strategy": "string",
    "Unit": "Days"
  },
  "RunbookProcessId": "string",
  "RunbookTags": [
    "string"
  ],
  "Slug": "string",
  "SpaceId": "string"
}

{
  "CancelQueuedTasks": true,
  "CancelRunningTasks": true,
  "ConnectivityPolicy": {
    "AllowDeploymentsToNoTargets": true,
    "ExcludeUnhealthyTargets": true,
    "SkipMachineBehavior": "None",
    "TargetRoles": [
      "string"
    ]
  },
  "DefaultGuidedFailureMode": "EnvironmentDefault",
  "Description": "string",
  "EnvironmentScope": "All",
  "Environments": [
    "string"
  ],
  "FailTargetDiscovery": true,
  "ForcePackageDownload": true,
  "Id": "string",
  "LastModifiedBy": "string",
  "LastModifiedOn": "2020-01-01T00:00:00.000Z",
  "Links": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "MultiTenancyMode": "Untenanted",
  "Name": "string",
  "ProjectId": "string",
  "PublishedRunbookSnapshotId": "string",
  "RunRetentionPolicy": {
    "QuantityToKeep": 0,
    "ShouldKeepForever": true,
    "Strategy": "string",
    "Unit": "Days"
  },
  "RunbookProcessId": "string",
  "RunbookTags": [
    "string"
  ],
  "Slug": "string",
  "SpaceId": "string"
}

GET /api/{spaceId}/projects/{projectId}/runbooks/all/v2

Also reachable at /api/projects/{projectId}/runbooks/all/v2, /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/all/v2.

Path Parameters

• projectId string (required)
  The ID of the project containing the resource(s).
• spaceId string (required)
  The ID of the space containing the resource(s).

Query Parameters

• ids array of string
  A list of Runbook resource ids used to filter a query.

Response

200 — Requested list of Runbooks

• Runbooks array of object
  • CancelQueuedTasks boolean
  • CancelRunningTasks boolean
  • ConnectivityPolicy object
  • DefaultGuidedFailureMode enum
    Allowed values: EnvironmentDefault, Off, On.
  • Description string
  • EnvironmentScope enum
    Allowed values: All, Specified, FromProjectLifecycles.
  • Environments array of string
  • FailTargetDiscovery boolean
  • ForcePackageDownload boolean
  • Id string
    Gets or sets a unique identifier for this resource.
  • LastModifiedBy string
    Gets or sets the username of the user who last modified this resource.
  • LastModifiedOn string
    Gets or sets the date/time that this resource was last modified. Format date-time.
  • Links object
    Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
  • MultiTenancyMode enum
    Allowed values: Untenanted, TenantedOrUntenanted, Tenanted.
  • Name string
  • ProjectId string
  • PublishedRunbookSnapshotId string
  • RunRetentionPolicy object
  • RunbookProcessId string
  • RunbookTags array of string
    List of tags assigned to this runbook.
  • Slug string
  • SpaceId string

{
  "Runbooks": [
    {
      "CancelQueuedTasks": true,
      "CancelRunningTasks": true,
      "ConnectivityPolicy": {
        "AllowDeploymentsToNoTargets": true,
        "ExcludeUnhealthyTargets": true,
        "SkipMachineBehavior": "None",
        "TargetRoles": [
          "string"
        ]
      },
      "DefaultGuidedFailureMode": "EnvironmentDefault",
      "Description": "string",
      "EnvironmentScope": "All",
      "Environments": [
        "string"
      ],
      "FailTargetDiscovery": true,
      "ForcePackageDownload": true,
      "Id": "string",
      "LastModifiedBy": "string",
      "LastModifiedOn": "2020-01-01T00:00:00.000Z",
      "Links": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "MultiTenancyMode": "Untenanted",
      "Name": "string",
      "ProjectId": "string",
      "PublishedRunbookSnapshotId": "string",
      "RunRetentionPolicy": {
        "QuantityToKeep": 0,
        "ShouldKeepForever": true,
        "Strategy": "string",
        "Unit": "Days"
      },
      "RunbookProcessId": "string",
      "RunbookTags": [
        "string"
      ],
      "Slug": "string",
      "SpaceId": "string"
    }
  ]
}

POST /api/{spaceId}/projects/{projectId}/runbooks/v2

Also reachable at /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/v2.

Path Parameters

• projectId string (required)
• spaceId string (required)

Request Body

• ConnectivityPolicy object
  • AllowDeploymentsToNoTargets boolean
  • ExcludeUnhealthyTargets boolean
  • SkipMachineBehavior enum
    Allowed values: None, SkipUnavailableMachines.
  • TargetRoles array of string
• DefaultGuidedFailureMode enum
  Allowed values: EnvironmentDefault, Off, On.
• Description string
• EnvironmentScope enum
  Allowed values: All, Specified, FromProjectLifecycles.
• Environments array of string
• ForcePackageDownload boolean
• MultiTenancyMode enum
  Allowed values: Untenanted, TenantedOrUntenanted, Tenanted.
• Name string (required)
  Minimum length 1.
• ProjectId string (required)
• RunRetentionPolicy object
  • QuantityToKeep integer
  • ShouldKeepForever boolean
  • Strategy string
  • Unit enum
    Allowed values: Days, Items.
• RunbookTags array of string
• Slug string
• SpaceId string (required)

Response

201 — Created

• Id string
• Name string
  Minimum length 1.
• ProjectId string
• Slug string
  Minimum length 1.

{
  "ConnectivityPolicy": {
    "AllowDeploymentsToNoTargets": true,
    "ExcludeUnhealthyTargets": true,
    "SkipMachineBehavior": "None",
    "TargetRoles": [
      "string"
    ]
  },
  "DefaultGuidedFailureMode": "EnvironmentDefault",
  "Description": "string",
  "EnvironmentScope": "All",
  "Environments": [
    "string"
  ],
  "ForcePackageDownload": true,
  "MultiTenancyMode": "Untenanted",
  "Name": "string",
  "ProjectId": "string",
  "RunRetentionPolicy": {
    "QuantityToKeep": 0,
    "ShouldKeepForever": true,
    "Strategy": "string",
    "Unit": "Days"
  },
  "RunbookTags": [
    "string"
  ],
  "Slug": "string",
  "SpaceId": "string"
}

{
  "Id": "string",
  "Name": "string",
  "ProjectId": "string",
  "Slug": "string"
}

GET /api/{spaceId}/projects/{projectId}/runbooks/{id}

Also reachable at /api/projects/{projectId}/runbooks/{id}, /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{id}.

Path Parameters

• id string (required)
  ID of the Runbook to retrieve.
• projectId string (required)
• spaceId string (required)

Response

200 — Returns a runbook

• CancelQueuedTasks boolean
• CancelRunningTasks boolean
• ConnectivityPolicy object
  • AllowDeploymentsToNoTargets boolean
  • ExcludeUnhealthyTargets boolean
  • SkipMachineBehavior enum
    Allowed values: None, SkipUnavailableMachines.
  • TargetRoles array of string
• DefaultGuidedFailureMode enum
  Allowed values: EnvironmentDefault, Off, On.
• Description string
• EnvironmentScope enum
  Allowed values: All, Specified, FromProjectLifecycles.
• Environments array of string
• FailTargetDiscovery boolean
• ForcePackageDownload boolean
• Id string
  Gets or sets a unique identifier for this resource.
• LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
• LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
• Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
• MultiTenancyMode enum
  Allowed values: Untenanted, TenantedOrUntenanted, Tenanted.
• Name string
• ProjectId string
• PublishedRunbookSnapshotId string
• RunRetentionPolicy object
  • QuantityToKeep integer
  • ShouldKeepForever boolean
  • Strategy string
  • Unit enum
    Allowed values: Days, Items.
• RunbookProcessId string
• RunbookTags array of string
  List of tags assigned to this runbook.
• Slug string
• SpaceId string

{
  "CancelQueuedTasks": true,
  "CancelRunningTasks": true,
  "ConnectivityPolicy": {
    "AllowDeploymentsToNoTargets": true,
    "ExcludeUnhealthyTargets": true,
    "SkipMachineBehavior": "None",
    "TargetRoles": [
      "string"
    ]
  },
  "DefaultGuidedFailureMode": "EnvironmentDefault",
  "Description": "string",
  "EnvironmentScope": "All",
  "Environments": [
    "string"
  ],
  "FailTargetDiscovery": true,
  "ForcePackageDownload": true,
  "Id": "string",
  "LastModifiedBy": "string",
  "LastModifiedOn": "2020-01-01T00:00:00.000Z",
  "Links": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "MultiTenancyMode": "Untenanted",
  "Name": "string",
  "ProjectId": "string",
  "PublishedRunbookSnapshotId": "string",
  "RunRetentionPolicy": {
    "QuantityToKeep": 0,
    "ShouldKeepForever": true,
    "Strategy": "string",
    "Unit": "Days"
  },
  "RunbookProcessId": "string",
  "RunbookTags": [
    "string"
  ],
  "Slug": "string",
  "SpaceId": "string"
}

PUT /api/{spaceId}/projects/{projectId}/runbooks/{id}

Also reachable at /api/projects/{projectId}/runbooks/{id}, /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{id}.

Path Parameters

• id string (required)
  The ID of the runbook to update, for example ‘Runbooks-123’.
• projectId string (required)
  The ID of the project the runbook belongs to. Must be a project that stores its runbooks in the Octopus database.
• spaceId string (required)

Request Body

• CancelQueuedTasks boolean
  When a new run of this runbook is queued, automatically cancel earlier runs of it that are still queued and now superseded. This is a standing setting on the runbook, not an instruction to cancel anything right now. Omit to leave the current setting unchanged.
• CancelRunningTasks boolean
  When a new run of this runbook is queued, automatically cancel an earlier run of it that is already executing and now superseded. This is a standing setting on the runbook, not an instruction to cancel anything right now. Omit to leave the current setting unchanged.
• ConnectivityPolicy object
  • AllowDeploymentsToNoTargets boolean
  • ExcludeUnhealthyTargets boolean
  • SkipMachineBehavior enum
    Allowed values: None, SkipUnavailableMachines.
  • TargetRoles array of string
• DefaultGuidedFailureMode enum
  What a run does when a step fails. One of ‘EnvironmentDefault’ (follow the target environment’s setting), ‘Off’ (fail the run immediately), or ‘On’ (pause the run and wait for someone to choose whether to retry, ignore or abort). Resets to ‘Off’ when omitted.
  Allowed values: EnvironmentDefault, Off, On.
• Description string
• EnvironmentScope enum
  Which environments the runbook may be run in. One of ‘All’ (every environment in the space), ‘Specified’ (only the environments listed in Environments), or ‘FromProjectLifecycles’ (only the environments used by the project’s lifecycles). Resets to ‘All’ when omitted.
  Allowed values: All, Specified, FromProjectLifecycles.
• Environments array of string
  The runbook’s complete environment list, used when EnvironmentScope is ‘Specified’. This replaces the current list, so resubmit the existing environments you want to keep. The update is rejected if it would remove an environment that a project trigger still runs this runbook in.
• FailTargetDiscovery boolean
  Fail a run when one of its target discovery steps finds no matching deployment targets, instead of letting the step succeed. Resets to false when omitted.
• ForcePackageDownload boolean
  Re-download every package on each run instead of reusing the copy already cached on the deployment target. Resets to false when omitted.
• Id string (required)
  The ID of the runbook to update, for example ‘Runbooks-123’.
• MultiTenancyMode enum
  Whether the runbook can be run for tenants. One of ‘Untenanted’ (untenanted runs only), ‘Tenanted’ (a tenant must be supplied for every run), or ‘TenantedOrUntenanted’ (either is allowed). Resets to ‘Untenanted’ when omitted.
  Allowed values: Untenanted, TenantedOrUntenanted, Tenanted.
• Name string (required)
  Minimum length 1.
• ProjectId string (required)
  The ID of the project the runbook belongs to. Must be a project that stores its runbooks in the Octopus database.
• PublishedRunbookSnapshotId string
  The ID of the runbook snapshot to publish. Setting this to a different snapshot publishes that snapshot, which is what subsequent runs execute. Resubmit the current value to leave the published snapshot alone.
• RunRetentionPolicy object (required)
  • QuantityToKeep integer
  • ShouldKeepForever boolean
  • Strategy string
  • Unit enum
    Allowed values: Days, Items.
• RunbookProcessId string
  Leave this as the value returned by get_runbook. Octopus manages the link between a runbook and its process.
• RunbookTags array of string
  The runbook’s complete set of tags, each written as “TagSet/Tag” using either the names or the IDs of the tag set and tag (for example “Ops/Nightly”). This replaces the current tags, so resubmit the existing ones you want to keep. Call find_tag_sets to discover which tag sets apply to runbooks.
• Slug string
  A short URL-friendly identifier for the runbook, unique within the project. The current slug is kept when omitted.
• SpaceId string (required)

Response

200 — Confirmation that the Runbook has been modified, containing the updated Runbook

• CancelQueuedTasks boolean
• CancelRunningTasks boolean
• ConnectivityPolicy object
  • AllowDeploymentsToNoTargets boolean
  • ExcludeUnhealthyTargets boolean
  • SkipMachineBehavior enum
    Allowed values: None, SkipUnavailableMachines.
  • TargetRoles array of string
• DefaultGuidedFailureMode enum
  Allowed values: EnvironmentDefault, Off, On.
• Description string
• EnvironmentScope enum
  Allowed values: All, Specified, FromProjectLifecycles.
• Environments array of string
• FailTargetDiscovery boolean
• ForcePackageDownload boolean
• Id string
  Gets or sets a unique identifier for this resource.
• LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
• LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
• Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
• MultiTenancyMode enum
  Allowed values: Untenanted, TenantedOrUntenanted, Tenanted.
• Name string
• ProjectId string
• PublishedRunbookSnapshotId string
• RunRetentionPolicy object
  • QuantityToKeep integer
  • ShouldKeepForever boolean
  • Strategy string
  • Unit enum
    Allowed values: Days, Items.
• RunbookProcessId string
• RunbookTags array of string
  List of tags assigned to this runbook.
• Slug string
• SpaceId string

{
  "CancelQueuedTasks": true,
  "CancelRunningTasks": true,
  "ConnectivityPolicy": {
    "AllowDeploymentsToNoTargets": true,
    "ExcludeUnhealthyTargets": true,
    "SkipMachineBehavior": "None",
    "TargetRoles": [
      "string"
    ]
  },
  "DefaultGuidedFailureMode": "EnvironmentDefault",
  "Description": "string",
  "EnvironmentScope": "All",
  "Environments": [
    "string"
  ],
  "FailTargetDiscovery": true,
  "ForcePackageDownload": true,
  "Id": "string",
  "MultiTenancyMode": "Untenanted",
  "Name": "string",
  "ProjectId": "string",
  "PublishedRunbookSnapshotId": "string",
  "RunRetentionPolicy": {
    "QuantityToKeep": 0,
    "ShouldKeepForever": true,
    "Strategy": "string",
    "Unit": "Days"
  },
  "RunbookProcessId": "string",
  "RunbookTags": [
    "string"
  ],
  "Slug": "string",
  "SpaceId": "string"
}

{
  "CancelQueuedTasks": true,
  "CancelRunningTasks": true,
  "ConnectivityPolicy": {
    "AllowDeploymentsToNoTargets": true,
    "ExcludeUnhealthyTargets": true,
    "SkipMachineBehavior": "None",
    "TargetRoles": [
      "string"
    ]
  },
  "DefaultGuidedFailureMode": "EnvironmentDefault",
  "Description": "string",
  "EnvironmentScope": "All",
  "Environments": [
    "string"
  ],
  "FailTargetDiscovery": true,
  "ForcePackageDownload": true,
  "Id": "string",
  "LastModifiedBy": "string",
  "LastModifiedOn": "2020-01-01T00:00:00.000Z",
  "Links": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "MultiTenancyMode": "Untenanted",
  "Name": "string",
  "ProjectId": "string",
  "PublishedRunbookSnapshotId": "string",
  "RunRetentionPolicy": {
    "QuantityToKeep": 0,
    "ShouldKeepForever": true,
    "Strategy": "string",
    "Unit": "Days"
  },
  "RunbookProcessId": "string",
  "RunbookTags": [
    "string"
  ],
  "Slug": "string",
  "SpaceId": "string"
}

DELETE /api/{spaceId}/projects/{projectId}/runbooks/{id}

Also reachable at /api/projects/{projectId}/runbooks/{id}, /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{id}.

Path Parameters

• id string (required)
  ID of the Runbook to delete.
• projectId string (required)
• spaceId string (required)

Response

200 — Success

GET /api/{spaceId}/projects/{projectId}/runbooks/{id}/environments

Also reachable at /api/projects/{projectId}/runbooks/{id}/environments, /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{id}/environments.

Path Parameters

• id string (required)
  ID of the Runbook.
• projectId string (required)
  The ID of the project containing this resource. Will be inferred if not provided.
• spaceId string (required)
  The ID of the space containing the resource(s).

Response

200 — The requested list of Runbook Environments

• AllowDynamicInfrastructure boolean
  If set to true, deployments to this environment will be allowed to contain steps that manage infrastructure. This relies on DeploymentActionResource being set to allow managing resource for a step.
• Description string
  Gets or sets a short description of this environment that can be used to explain the purpose of the environment to other users. This field may contain markdown.
• EnvironmentTags array of string
  List of tags assigned to this environment.
• ExtensionSettings array of object
  • ExtensionId string
  • Values string
• Id string
  Gets or sets a unique identifier for this resource.
• LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
• LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
• Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
• Name string
  Gets or sets the name of this environment. This should be short, preferably 5-20 characters.
• Slug string
• SortOrder integer
  Gets or sets a number indicating the priority of this environment in sort order. Environments with a lower sort order will appear in the UI before items with a higher sort order.
• SpaceId string
• UseGuidedFailure boolean
  If set to true, deployments will prompt for manual intervention (Fail/Retry/Ignore) when failures are encountered in activities that support it. May be overridden with the Octopus.UseGuidedFailure special variable.

[
  {
    "AllowDynamicInfrastructure": true,
    "Description": "string",
    "EnvironmentTags": [
      "string"
    ],
    "ExtensionSettings": [
      {
        "ExtensionId": "string",
        "Values": "string"
      }
    ],
    "Id": "string",
    "LastModifiedBy": "string",
    "LastModifiedOn": "2020-01-01T00:00:00.000Z",
    "Links": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "Name": "string",
    "Slug": "string",
    "SortOrder": 0,
    "SpaceId": "string",
    "UseGuidedFailure": true
  }
]

GET /api/{spaceId}/projects/{projectId}/runbooks/{id}/environments/v2

Also reachable at /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{id}/environments/v2.

Path Parameters

• id string (required)
  ID of the Runbook.
• projectId string (required)
  The ID of the project containing this resource. Will be inferred if not provided.
• spaceId string (required)
  The ID of the space containing the resource(s).

Response

200 — The requested list of Runbook Environments

• Environments array of object
  • Description string
    Gets or sets a short description of this environment that can be used to explain the purpose of the environment to other users. This field may contain markdown.
  • EnvironmentTags array of string
    List of tags assigned to this environment.
  • Id string
  • Name string
    Gets or sets the name of this environment. This should be short, preferably 5-20 characters. Minimum length 1.
  • Slug string
    Minimum length 1.
  • SpaceId string
  • Type string

{
  "Environments": [
    {
      "Description": "string",
      "EnvironmentTags": [
        "string"
      ],
      "Id": "string",
      "Name": "string",
      "Slug": "string",
      "SpaceId": "string",
      "Type": "string"
    }
  ]
}

GET /api/{spaceId}/projects/{projectId}/runbooks/{id}/runbookRunTemplate

Also reachable at /api/projects/{projectId}/runbooks/{id}/runbookRunTemplate, /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{id}/runbookRunTemplate.

Path Parameters

• id string (required)
  ID of the Runbook to get a Runbook Run Template for.
• projectId string (required)
  ID of the project the runbook belongs to.
• spaceId string (required)
  The ID of the space containing the resource(s).

Response

200 — The requested Runbook Template

• Id string
  Gets or sets a unique identifier for this resource.
• IsGitResourceModified boolean
• IsLibraryVariableSetModified boolean
• IsRunbookProcessModified boolean
• IsVariableSetModified boolean
• LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
• LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
• Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
• PromoteTo array of object
  • Id string
  • Links object
  • Name string
• TenantPromotions array of object
  • Id string
    Gets or sets a unique identifier for this resource.
  • LastModifiedBy string
    Gets or sets the username of the user who last modified this resource.
  • LastModifiedOn string
    Gets or sets the date/time that this resource was last modified. Format date-time.
  • Links object
    Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
  • Name string
  • PromoteTo array of object

{
  "Id": "string",
  "IsGitResourceModified": true,
  "IsLibraryVariableSetModified": true,
  "IsRunbookProcessModified": true,
  "IsVariableSetModified": true,
  "LastModifiedBy": "string",
  "LastModifiedOn": "2020-01-01T00:00:00.000Z",
  "Links": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "PromoteTo": [
    {
      "Id": "string",
      "Links": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "Name": "string"
    }
  ],
  "TenantPromotions": [
    {
      "Id": "string",
      "LastModifiedBy": "string",
      "LastModifiedOn": "2020-01-01T00:00:00.000Z",
      "Links": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "Name": "string",
      "PromoteTo": [
        {}
      ]
    }
  ]
}

GET /api/{spaceId}/projects/{projectId}/runbooks/{id}/runbookRuns/preview/{environment}

Also reachable at /api/projects/{projectId}/runbooks/{id}/runbookRuns/preview/{environment}, /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{id}/runbookRuns/preview/{environment}.

Gets a Runbook Run Preview that describes what steps will/won’t be run during a Runbook Run on a given environment (and tenant if supplied) for a Runbook.

Path Parameters

• environment string (required)
  ID of the Environment.
• id string (required)
  ID of the Runbook.
• projectId string (required)
  ID of the Project.
• spaceId string (required)
  The ID of the space containing the resource(s).

Query Parameters

• includeDisabledSteps boolean
  Boolean to include/exclude disabled steps from response.
• tenant string
  ID of the Tenant.

Response

200 — Success

• Form object
  • Elements array of object
    Elements of the form.
  • Values object
    Values supplied for the form elements.
• Id string
  Gets or sets a unique identifier for this resource.
• LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
• LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
• Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
• StepsToExecute array of object
  • ActionId string
  • ActionName string
  • ActionNumber string
  • AvailableTagSets array of object
  • CanBeSkipped boolean
  • ExcludedMachines array of object
  • HasNoApplicableMachines boolean
  • IsDisabled boolean
  • MachineNames array of string
  • Machines array of object
  • Roles array of string
  • UnavailableMachines array of object
• UseGuidedFailureModeByDefault boolean

{
  "Form": {
    "Elements": [
      {
        "Control": {},
        "IsValueRequired": true,
        "Name": "string"
      }
    ],
    "Values": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  },
  "Id": "string",
  "LastModifiedBy": "string",
  "LastModifiedOn": "2020-01-01T00:00:00.000Z",
  "Links": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "StepsToExecute": [
    {
      "ActionId": "string",
      "ActionName": "string",
      "ActionNumber": "string",
      "AvailableTagSets": [
        {}
      ],
      "CanBeSkipped": true,
      "ExcludedMachines": [
        {}
      ],
      "HasNoApplicableMachines": true,
      "IsDisabled": true,
      "MachineNames": [
        "string"
      ],
      "Machines": [
        {}
      ],
      "Roles": [
        "string"
      ],
      "UnavailableMachines": [
        {}
      ]
    }
  ],
  "UseGuidedFailureModeByDefault": true
}

GET /api/{spaceId}/projects/{projectId}/runbooks/{id}/runbookRuns/preview/{environment}/{tenant}

Also reachable at /api/projects/{projectId}/runbooks/{id}/runbookRuns/preview/{environment}/{tenant}, /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{id}/runbookRuns/preview/{environment}/{tenant}.

Gets a Runbook Run Preview that describes what steps will/won’t be run during a Runbook Run on a given environment (and tenant if supplied) for a Runbook.

Path Parameters

• environment string (required)
  ID of the Environment.
• id string (required)
  ID of the Runbook.
• projectId string (required)
  ID of the Project.
• spaceId string (required)
  The ID of the space containing the resource(s).
• tenant string (required)
  ID of the Tenant.

Query Parameters

• includeDisabledSteps boolean
  Boolean to include/exclude disabled steps from response.

Response

200 — Success

• Form object
  • Elements array of object
    Elements of the form.
  • Values object
    Values supplied for the form elements.
• Id string
  Gets or sets a unique identifier for this resource.
• LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
• LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
• Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
• StepsToExecute array of object
  • ActionId string
  • ActionName string
  • ActionNumber string
  • AvailableTagSets array of object
  • CanBeSkipped boolean
  • ExcludedMachines array of object
  • HasNoApplicableMachines boolean
  • IsDisabled boolean
  • MachineNames array of string
  • Machines array of object
  • Roles array of string
  • UnavailableMachines array of object
• UseGuidedFailureModeByDefault boolean

{
  "Form": {
    "Elements": [
      {
        "Control": {},
        "IsValueRequired": true,
        "Name": "string"
      }
    ],
    "Values": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  },
  "Id": "string",
  "LastModifiedBy": "string",
  "LastModifiedOn": "2020-01-01T00:00:00.000Z",
  "Links": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "StepsToExecute": [
    {
      "ActionId": "string",
      "ActionName": "string",
      "ActionNumber": "string",
      "AvailableTagSets": [
        {}
      ],
      "CanBeSkipped": true,
      "ExcludedMachines": [
        {}
      ],
      "HasNoApplicableMachines": true,
      "IsDisabled": true,
      "MachineNames": [
        "string"
      ],
      "Machines": [
        {}
      ],
      "Roles": [
        "string"
      ],
      "UnavailableMachines": [
        {}
      ]
    }
  ],
  "UseGuidedFailureModeByDefault": true
}

POST /api/{spaceId}/projects/{projectId}/runbooks/{runbookId}/run

Also reachable at /api/projects/{projectId}/runbooks/{runbookId}/run, /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{runbookId}/run.

Path Parameters

• projectId string (required)
  ID of the project that the runbook belongs to.
• runbookId string (required)
  ID of the runbook to run.
• spaceId string (required)
  The ID of the space containing the resource(s).

Request Body

• ChangeRequestSettings array of object
  Change Request Settings.
  • Type enum
    Allowed values: ServiceNow, JiraServiceManagement.
• Comments string
  Any additional information/context.
• DebugMode string
  If set to true contributes the OctopusPrintVariables and OctopusPrintEvaluatedVariables variables to the runbook run.
• EnvironmentId string
  Legacy single-environment field; prefer EnvironmentIds. If set, this environment is added to the ones the runbook runs in. At least one of EnvironmentIds or EnvironmentId is required.
• EnvironmentIds array of string
  The environments to run the runbook in — the preferred way to specify targets, one run per environment. At least one of EnvironmentIds or EnvironmentId is required.
• ExcludedMachineIds array of string
  A collection of machines in the target environment that should be excluded from the runbook run.
• ExcludedTargetTagIds array of string
  A collection of target tag IDs that should be excluded from the deployment. Only deployment targets that have none of these tags will be deployed to. Tag IDs are in the format “TagSets-{id}/Tags-{id}”.
• FailTargetDiscovery boolean
  Whether to skip or fail cloud discovery steps with no matching target (default false).
• ForcePackageDownload boolean
  Whether to force downloading of already installed packages (flag, default false).
• FormValues object
  Variables.
• Priority string
• ProjectId string
  ID of the project that the runbook belongs to.
• QueueTime string
  The time to execute the runbook run. Format date-time.
• QueueTimeExpiry string
  The time at which the runbook run will timeout if it has not started executing. Format date-time.
• RunbookId string (required)
  ID of the runbook to run.
• RunbookSnapshotNameOrId string
  Name or ID of a specific snapshot to run. Leave unset to run the published snapshot; when you set this, also set UseDefaultSnapshot to false.
• SkipActions array of string
  Actions that are to be skipped for this runbook.
• SpaceId string (required)
  The ID of the space containing the resource(s).
• SpecificMachineIds array of string
  A collection of machines in the target environment that the runbook should be run on. If the collection is empty, all enabled machines are used.
• SpecificTargetTagIds array of string
  A collection of target tag IDs that should be included in the deployment. Only deployment targets that have at least one of these tags will be deployed to. Tag IDs are in the format “TagSets-{id}/Tags-{id}”.
• TenantId string
  Legacy single-tenant field; prefer TenantIds. If set, this tenant is added to the ones the runbook runs for.
• TenantIds array of string
  The tenants to run the runbook for — the preferred way to specify tenants, creating one run per environment/tenant combination. Leave empty for an untenanted run.
• TenantTagNames array of string
  The tenant tags to filter tenants to run the runbook.
• UseDefaultSnapshot boolean
  Whether to run the runbook’s published (default) snapshot. Leave true to run the published snapshot; set to false when you name a specific snapshot in RunbookSnapshotNameOrId.
• UseGuidedFailure boolean
  If set to true, the runbook will prompt for manual intervention (Fail/Retry/Ignore) when failures are encountered in activities that support it. May be overridden with the Octopus.UseGuidedFailure special variable.

Response

200 — OK

{
  "ChangeRequestSettings": [
    {
      "Type": "ServiceNow"
    }
  ],
  "Comments": "string",
  "DebugMode": "string",
  "EnvironmentId": "string",
  "EnvironmentIds": [
    "string"
  ],
  "ExcludedMachineIds": [
    "string"
  ],
  "ExcludedTargetTagIds": [
    "string"
  ],
  "FailTargetDiscovery": true,
  "ForcePackageDownload": true,
  "FormValues": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "Priority": "string",
  "ProjectId": "string",
  "QueueTime": "2020-01-01T00:00:00.000Z",
  "QueueTimeExpiry": "2020-01-01T00:00:00.000Z",
  "RunbookId": "string",
  "RunbookSnapshotNameOrId": "string",
  "SkipActions": [
    "string"
  ],
  "SpaceId": "string",
  "SpecificMachineIds": [
    "string"
  ],
  "SpecificTargetTagIds": [
    "string"
  ],
  "TenantId": "string",
  "TenantIds": [
    "string"
  ],
  "TenantTagNames": [
    "string"
  ],
  "UseDefaultSnapshot": true,
  "UseGuidedFailure": true
}

POST /api/{spaceId}/projects/{projectId}/runbooks/{runbookId}/runbookRuns/previews

Also reachable at /api/projects/{projectId}/runbooks/{runbookId}/runbookRuns/previews, /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{runbookId}/runbookRuns/previews.

Gets a list of Runbook Run Previews that describes what steps will/won’t be run during a Runbook Run on a given environment and tenant for a Runbook.

Path Parameters

• projectId string (required)
  ID of the Project.
• runbookId string (required)
  ID of the Runbook.
• spaceId string (required)
  The ID of the space containing the resource(s).

Request Body

• DeploymentPreviews array of object (required)
  A list of Tenant/Environment mappings to retrieve runbook run previews for.
  • EnvironmentId string
  • TenantId string
• IncludeDisabledSteps boolean
  Boolean to include/exclude disabled steps from response.
• ProjectId string (required)
  ID of the Project.
• RunbookId string (required)
  ID of the Runbook.
• SpaceId string (required)
  The ID of the space containing the resource(s).

Response

200 — The requested list of Runbook Run previews

• Form object
  • Elements array of object
    Elements of the form.
  • Values object
    Values supplied for the form elements.
• Id string
  Gets or sets a unique identifier for this resource.
• LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
• LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
• Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
• StepsToExecute array of object
  • ActionId string
  • ActionName string
  • ActionNumber string
  • AvailableTagSets array of object
  • CanBeSkipped boolean
  • ExcludedMachines array of object
  • HasNoApplicableMachines boolean
  • IsDisabled boolean
  • MachineNames array of string
  • Machines array of object
  • Roles array of string
  • UnavailableMachines array of object
• UseGuidedFailureModeByDefault boolean

{
  "DeploymentPreviews": [
    {
      "EnvironmentId": "string",
      "TenantId": "string"
    }
  ],
  "IncludeDisabledSteps": true,
  "ProjectId": "string",
  "RunbookId": "string",
  "SpaceId": "string"
}

[
  {
    "Form": {
      "Elements": [
        {}
      ],
      "Values": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    },
    "Id": "string",
    "LastModifiedBy": "string",
    "LastModifiedOn": "2020-01-01T00:00:00.000Z",
    "Links": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "StepsToExecute": [
      {
        "ActionId": "string",
        "ActionName": "string",
        "ActionNumber": "string",
        "AvailableTagSets": [
          {}
        ],
        "CanBeSkipped": true,
        "ExcludedMachines": [
          {}
        ],
        "HasNoApplicableMachines": true,
        "IsDisabled": true,
        "MachineNames": [
          "string"
        ],
        "Machines": [
          {}
        ],
        "Roles": [
          "string"
        ],
        "UnavailableMachines": [
          {}
        ]
      }
    ],
    "UseGuidedFailureModeByDefault": true
  }
]

GET /api/{spaceId}/projects/{projectId}/runbooks/{runbookId}/runbookSnapshotTemplate

Also reachable at /api/projects/{projectId}/runbooks/{runbookId}/runbookSnapshotTemplate, /api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{runbookId}/runbookSnapshotTemplate.

Path Parameters

• projectId string (required)
  Project Id of the project containing the runbook.
• runbookId string (required)
  ID of the Runbook.
• spaceId string (required)

Response

200 — Confirmation that a new Runbook Snapshot Template has been created, containing the template

• GitResources array of object
  • ActionName string
    Minimum length 1.
  • DefaultBranch string
    Minimum length 1.
  • FilePathFilters array of string
  • GitCredentialId string
  • GitHubConnectionId string
  • GitResourceSelectedLastRelease object
  • IsResolvable boolean
  • Name string
  • RepositoryUri string
    Minimum length 1.
• Id string
  Gets or sets a unique identifier for this resource.
• LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
• LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
• Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
• NextNameIncrement string
• Packages array of object
  • ActionName string
  • FeedId string
  • FeedName string
  • FixedVersion string
  • IsResolvable boolean
    Gets or sets a value indicating whether the PackageId or FeedId contain no references to other variables. Variables can be used to select different NuGet feeds or packages at deployment time, however, this means that it’s not possible to resolve which feed/package to search when creating a release.
  • NuGetFeedId string
  • NuGetFeedName string
  • NuGetPackageId string
  • PackageId string
  • PackageReferenceName string
  • ProjectName string
  • StepName string
  • VersionSelectedLastRelease string
• RunbookId string
• RunbookProcessId string

{
  "GitResources": [
    {
      "ActionName": "string",
      "DefaultBranch": "string",
      "FilePathFilters": [
        "string"
      ],
      "GitCredentialId": "string",
      "GitHubConnectionId": "string",
      "GitResourceSelectedLastRelease": {
        "GitCommit": "string",
        "GitRef": "string"
      },
      "IsResolvable": true,
      "Name": "string",
      "RepositoryUri": "string"
    }
  ],
  "Id": "string",
  "LastModifiedBy": "string",
  "LastModifiedOn": "2020-01-01T00:00:00.000Z",
  "Links": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "NextNameIncrement": "string",
  "Packages": [
    {
      "ActionName": "string",
      "FeedId": "string",
      "FeedName": "string",
      "FixedVersion": "string",
      "IsResolvable": true,
      "NuGetFeedId": "string",
      "NuGetFeedName": "string",
      "NuGetPackageId": "string",
      "PackageId": "string",
      "PackageReferenceName": "string",
      "ProjectName": "string",
      "StepName": "string",
      "VersionSelectedLastRelease": "string"
    }
  ],
  "RunbookId": "string",
  "RunbookProcessId": "string"
}

GET /api/{spaceId}/projects/{projectId}/{gitRef}/runbooks

Also reachable at /api/projects/{projectId}/{gitRef}/runbooks, /api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/runbooks.

Path Parameters

• gitRef string (required)
  The GitRef containing the resource(s).
• projectId string (required)
  The ID of the project.
• spaceId string (required)
  The ID of the space containing the resource(s).

Query Parameters

• excludedRunbookTags array of string
  A list of tag IDs to exclude runbooks by. Returns runbooks that have none of the specified tags.
• partialName string
  A partial or complete name to search on. This will perform a “contains” style match against the supplied name or name-fragment.
• runbookTags array of string
  A list of tag IDs to filter runbooks by. Returns runbooks that have any of the specified tags.
• skip integer
  Number of items to skip. Defaults to zero. Minimum 0.
• take integer
  Number of items to take. Defaults to 30. Minimum 0.

Response

200 — Success

• Id string
  Gets or sets a unique identifier for this resource.
• ItemType string
• Items array of object
  • CancelQueuedTasks boolean
  • CancelRunningTasks boolean
  • ConnectivityPolicy object
  • DefaultGuidedFailureMode enum
    Allowed values: EnvironmentDefault, Off, On.
  • Description string
  • EnvironmentScope enum
    Allowed values: All, Specified, FromProjectLifecycles.
  • Environments array of string
  • FailTargetDiscovery boolean
  • ForcePackageDownload boolean
  • Id string
    Gets or sets a unique identifier for this resource.
  • LastModifiedBy string
    Gets or sets the username of the user who last modified this resource.
  • LastModifiedOn string
    Gets or sets the date/time that this resource was last modified. Format date-time.
  • Links object
    Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
  • MultiTenancyMode enum
    Allowed values: Untenanted, TenantedOrUntenanted, Tenanted.
  • Name string
  • ProjectId string
  • PublishedRunbookSnapshotId string
  • RunRetentionPolicy object
  • RunbookProcessId string
  • RunbookTags array of string
    List of tags assigned to this runbook.
  • Slug string
  • SpaceId string
• ItemsPerPage integer
• LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
• LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
• LastPageNumber integer
• Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
• NumberOfPages integer
• TotalResults integer

{
  "Id": "string",
  "ItemType": "string",
  "Items": [
    {
      "CancelQueuedTasks": true,
      "CancelRunningTasks": true,
      "ConnectivityPolicy": {
        "AllowDeploymentsToNoTargets": true,
        "ExcludeUnhealthyTargets": true,
        "SkipMachineBehavior": "None",
        "TargetRoles": [
          "string"
        ]
      },
      "DefaultGuidedFailureMode": "EnvironmentDefault",
      "Description": "string",
      "EnvironmentScope": "All",
      "Environments": [
        "string"
      ],
      "FailTargetDiscovery": true,
      "ForcePackageDownload": true,
      "Id": "string",
      "LastModifiedBy": "string",
      "LastModifiedOn": "2020-01-01T00:00:00.000Z",
      "Links": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "MultiTenancyMode": "Untenanted",
      "Name": "string",
      "ProjectId": "string",
      "PublishedRunbookSnapshotId": "string",
      "RunRetentionPolicy": {
        "QuantityToKeep": 0,
        "ShouldKeepForever": true,
        "Strategy": "string",
        "Unit": "Days"
      },
      "RunbookProcessId": "string",
      "RunbookTags": [
        "string"
      ],
      "Slug": "string",
      "SpaceId": "string"
    }
  ],
  "ItemsPerPage": 0,
  "LastModifiedBy": "string",
  "LastModifiedOn": "2020-01-01T00:00:00.000Z",
  "LastPageNumber": 0,
  "Links": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "NumberOfPages": 0,
  "TotalResults": 0
}

POST /api/{spaceId}/projects/{projectId}/{gitRef}/runbooks/v2

Also reachable at /api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/runbooks/v2.

Path Parameters

• gitRef string (required)
• projectId string (required)
• spaceId string (required)

Request Body

• ChangeDescription string
• ConnectivityPolicy object
  • AllowDeploymentsToNoTargets boolean
  • ExcludeUnhealthyTargets boolean
  • SkipMachineBehavior enum
    Allowed values: None, SkipUnavailableMachines.
  • TargetRoles array of string
• DefaultGuidedFailureMode enum
  Allowed values: EnvironmentDefault, Off, On.
• Description string
• EnvironmentScope enum
  Allowed values: All, Specified, FromProjectLifecycles.
• Environments array of string
• ForcePackageDownload boolean
• GitRef string (required)
• MultiTenancyMode enum
  Allowed values: Untenanted, TenantedOrUntenanted, Tenanted.
• Name string (required)
  Minimum length 1.
• ProjectId string (required)
• RunRetentionPolicy object
  • QuantityToKeep integer
  • ShouldKeepForever boolean
  • Strategy string
  • Unit enum
    Allowed values: Days, Items.
• RunbookTags array of string
• Slug string
• SpaceId string (required)

Response

201 — Created

• GitRef string
  Minimum length 1.
• Id string
• Name string
  Minimum length 1.
• ProjectId string
• Slug string
  Minimum length 1.

{
  "ChangeDescription": "string",
  "ConnectivityPolicy": {
    "AllowDeploymentsToNoTargets": true,
    "ExcludeUnhealthyTargets": true,
    "SkipMachineBehavior": "None",
    "TargetRoles": [
      "string"
    ]
  },
  "DefaultGuidedFailureMode": "EnvironmentDefault",
  "Description": "string",
  "EnvironmentScope": "All",
  "Environments": [
    "string"
  ],
  "ForcePackageDownload": true,
  "GitRef": "string",
  "MultiTenancyMode": "Untenanted",
  "Name": "string",
  "ProjectId": "string",
  "RunRetentionPolicy": {
    "QuantityToKeep": 0,
    "ShouldKeepForever": true,
    "Strategy": "string",
    "Unit": "Days"
  },
  "RunbookTags": [
    "string"
  ],
  "Slug": "string",
  "SpaceId": "string"
}

{
  "GitRef": "string",
  "Id": "string",
  "Name": "string",
  "ProjectId": "string",
  "Slug": "string"
}

GET /api/{spaceId}/projects/{projectId}/{gitRef}/runbooks/{id}

Also reachable at /api/projects/{projectId}/{gitRef}/runbooks/{id}, /api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/runbooks/{id}.

Path Parameters

• gitRef string (required)
• id string (required)
  ID of the Runbook to retrieve.
• projectId string (required)
• spaceId string (required)

Response

200 — Returns a runbook

• CancelQueuedTasks boolean
• CancelRunningTasks boolean
• ConnectivityPolicy object
  • AllowDeploymentsToNoTargets boolean
  • ExcludeUnhealthyTargets boolean
  • SkipMachineBehavior enum
    Allowed values: None, SkipUnavailableMachines.
  • TargetRoles array of string
• DefaultGuidedFailureMode enum
  Allowed values: EnvironmentDefault, Off, On.
• Description string
• EnvironmentScope enum
  Allowed values: All, Specified, FromProjectLifecycles.
• Environments array of string
• FailTargetDiscovery boolean
• ForcePackageDownload boolean
• Id string
  Gets or sets a unique identifier for this resource.
• LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
• LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
• Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
• MultiTenancyMode enum
  Allowed values: Untenanted, TenantedOrUntenanted, Tenanted.
• Name string
• ProjectId string
• PublishedRunbookSnapshotId string
• RunRetentionPolicy object
  • QuantityToKeep integer
  • ShouldKeepForever boolean
  • Strategy string
  • Unit enum
    Allowed values: Days, Items.
• RunbookProcessId string
• RunbookTags array of string
  List of tags assigned to this runbook.
• Slug string
• SpaceId string

{
  "CancelQueuedTasks": true,
  "CancelRunningTasks": true,
  "ConnectivityPolicy": {
    "AllowDeploymentsToNoTargets": true,
    "ExcludeUnhealthyTargets": true,
    "SkipMachineBehavior": "None",
    "TargetRoles": [
      "string"
    ]
  },
  "DefaultGuidedFailureMode": "EnvironmentDefault",
  "Description": "string",
  "EnvironmentScope": "All",
  "Environments": [
    "string"
  ],
  "FailTargetDiscovery": true,
  "ForcePackageDownload": true,
  "Id": "string",
  "LastModifiedBy": "string",
  "LastModifiedOn": "2020-01-01T00:00:00.000Z",
  "Links": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "MultiTenancyMode": "Untenanted",
  "Name": "string",
  "ProjectId": "string",
  "PublishedRunbookSnapshotId": "string",
  "RunRetentionPolicy": {
    "QuantityToKeep": 0,
    "ShouldKeepForever": true,
    "Strategy": "string",
    "Unit": "Days"
  },
  "RunbookProcessId": "string",
  "RunbookTags": [
    "string"
  ],
  "Slug": "string",
  "SpaceId": "string"
}

PUT /api/{spaceId}/projects/{projectId}/{gitRef}/runbooks/{id}

Also reachable at /api/projects/{projectId}/{gitRef}/runbooks/{id}, /api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/runbooks/{id}.

Path Parameters

• gitRef string (required)
  The Git branch to commit the change to. This must be a branch — a tag or commit cannot be written to — and the branch must not be protected in the project’s version control settings. Use get_branches to list the project’s branches.
• id string (required)
  The ID of the runbook to update. A runbook stored in Git uses its slug as the ID, which is only unique within its project and Git ref.
• projectId string (required)
  The ID of the project the runbook belongs to. Must be a version-controlled project that stores its runbooks in Git.
• spaceId string (required)

Request Body

• CancelQueuedTasks boolean
  When a new run of this runbook is queued, automatically cancel earlier runs of it that are still queued and now superseded. This is a standing setting on the runbook, not an instruction to cancel anything right now. Omit to leave the current setting unchanged.
• CancelRunningTasks boolean
  When a new run of this runbook is queued, automatically cancel an earlier run of it that is already executing and now superseded. This is a standing setting on the runbook, not an instruction to cancel anything right now. Omit to leave the current setting unchanged.
• ChangeDescription string
  The commit message for the change. Defaults to ‘Update runbook’ when omitted.
• ConnectivityPolicy object
  • AllowDeploymentsToNoTargets boolean
  • ExcludeUnhealthyTargets boolean
  • SkipMachineBehavior enum
    Allowed values: None, SkipUnavailableMachines.
  • TargetRoles array of string
• DefaultGuidedFailureMode enum
  What a run does when a step fails. One of ‘EnvironmentDefault’ (follow the target environment’s setting), ‘Off’ (fail the run immediately), or ‘On’ (pause the run and wait for someone to choose whether to retry, ignore or abort). Resets to ‘Off’ when omitted.
  Allowed values: EnvironmentDefault, Off, On.
• Description string
• EnvironmentScope enum
  Which environments the runbook may be run in. One of ‘All’ (every environment in the space), ‘Specified’ (only the environments listed in Environments), or ‘FromProjectLifecycles’ (only the environments used by the project’s lifecycles). Resets to ‘All’ when omitted.
  Allowed values: All, Specified, FromProjectLifecycles.
• Environments array of string
  The runbook’s complete environment list, used when EnvironmentScope is ‘Specified’. This replaces the current list, so resubmit the existing environments you want to keep. The update is rejected if it would remove an environment that a project trigger still runs this runbook in.
• FailTargetDiscovery boolean
  Fail a run when one of its target discovery steps finds no matching deployment targets, instead of letting the step succeed. Resets to false when omitted.
• ForcePackageDownload boolean
  Re-download every package on each run instead of reusing the copy already cached on the deployment target. Resets to false when omitted.
• GitRef string (required)
  The Git branch to commit the change to. This must be a branch — a tag or commit cannot be written to — and the branch must not be protected in the project’s version control settings. Use get_branches to list the project’s branches.
• Id string (required)
  The ID of the runbook to update. A runbook stored in Git uses its slug as the ID, which is only unique within its project and Git ref.
• MultiTenancyMode enum
  Whether the runbook can be run for tenants. One of ‘Untenanted’ (untenanted runs only), ‘Tenanted’ (a tenant must be supplied for every run), or ‘TenantedOrUntenanted’ (either is allowed). Resets to ‘Untenanted’ when omitted.
  Allowed values: Untenanted, TenantedOrUntenanted, Tenanted.
• Name string (required)
  Minimum length 1.
• ProjectId string (required)
  The ID of the project the runbook belongs to. Must be a version-controlled project that stores its runbooks in Git.
• PublishedRunbookSnapshotId string
  The ID of the runbook snapshot to publish. Resubmit the current value to leave the published snapshot alone.
• RunRetentionPolicy object (required)
  • QuantityToKeep integer
  • ShouldKeepForever boolean
  • Strategy string
  • Unit enum
    Allowed values: Days, Items.
• RunbookProcessId string
  Leave this as the value returned by get_runbook. Octopus manages the link between a runbook and its process.
• RunbookTags array of string
  The runbook’s complete set of tags, each written as “TagSet/Tag” using either the names or the IDs of the tag set and tag (for example “Ops/Nightly”). This replaces the current tags, so resubmit the existing ones you want to keep. Call find_tag_sets to discover which tag sets apply to runbooks.
• Slug string
  A short URL-friendly identifier for the runbook, unique within the project. The current slug is kept when omitted.
• SpaceId string (required)

Response

200 — Confirmation that the Runbook has been modified, containing the updated Runbook

• CancelQueuedTasks boolean
• CancelRunningTasks boolean
• ConnectivityPolicy object
  • AllowDeploymentsToNoTargets boolean
  • ExcludeUnhealthyTargets boolean
  • SkipMachineBehavior enum
    Allowed values: None, SkipUnavailableMachines.
  • TargetRoles array of string
• DefaultGuidedFailureMode enum
  Allowed values: EnvironmentDefault, Off, On.
• Description string
• EnvironmentScope enum
  Allowed values: All, Specified, FromProjectLifecycles.
• Environments array of string
• FailTargetDiscovery boolean
• ForcePackageDownload boolean
• Id string
  Gets or sets a unique identifier for this resource.
• LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
• LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
• Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
• MultiTenancyMode enum
  Allowed values: Untenanted, TenantedOrUntenanted, Tenanted.
• Name string
• ProjectId string
• PublishedRunbookSnapshotId string
• RunRetentionPolicy object
  • QuantityToKeep integer
  • ShouldKeepForever boolean
  • Strategy string
  • Unit enum
    Allowed values: Days, Items.
• RunbookProcessId string
• RunbookTags array of string
  List of tags assigned to this runbook.
• Slug string
• SpaceId string

{
  "CancelQueuedTasks": true,
  "CancelRunningTasks": true,
  "ChangeDescription": "string",
  "ConnectivityPolicy": {
    "AllowDeploymentsToNoTargets": true,
    "ExcludeUnhealthyTargets": true,
    "SkipMachineBehavior": "None",
    "TargetRoles": [
      "string"
    ]
  },
  "DefaultGuidedFailureMode": "EnvironmentDefault",
  "Description": "string",
  "EnvironmentScope": "All",
  "Environments": [
    "string"
  ],
  "FailTargetDiscovery": true,
  "ForcePackageDownload": true,
  "GitRef": "string",
  "Id": "string",
  "MultiTenancyMode": "Untenanted",
  "Name": "string",
  "ProjectId": "string",
  "PublishedRunbookSnapshotId": "string",
  "RunRetentionPolicy": {
    "QuantityToKeep": 0,
    "ShouldKeepForever": true,
    "Strategy": "string",
    "Unit": "Days"
  },
  "RunbookProcessId": "string",
  "RunbookTags": [
    "string"
  ],
  "Slug": "string",
  "SpaceId": "string"
}

{
  "CancelQueuedTasks": true,
  "CancelRunningTasks": true,
  "ConnectivityPolicy": {
    "AllowDeploymentsToNoTargets": true,
    "ExcludeUnhealthyTargets": true,
    "SkipMachineBehavior": "None",
    "TargetRoles": [
      "string"
    ]
  },
  "DefaultGuidedFailureMode": "EnvironmentDefault",
  "Description": "string",
  "EnvironmentScope": "All",
  "Environments": [
    "string"
  ],
  "FailTargetDiscovery": true,
  "ForcePackageDownload": true,
  "Id": "string",
  "LastModifiedBy": "string",
  "LastModifiedOn": "2020-01-01T00:00:00.000Z",
  "Links": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "MultiTenancyMode": "Untenanted",
  "Name": "string",
  "ProjectId": "string",
  "PublishedRunbookSnapshotId": "string",
  "RunRetentionPolicy": {
    "QuantityToKeep": 0,
    "ShouldKeepForever": true,
    "Strategy": "string",
    "Unit": "Days"
  },
  "RunbookProcessId": "string",
  "RunbookTags": [
    "string"
  ],
  "Slug": "string",
  "SpaceId": "string"
}

DELETE /api/{spaceId}/projects/{projectId}/{gitRef}/runbooks/{id}

Also reachable at /api/projects/{projectId}/{gitRef}/runbooks/{id}, /api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/runbooks/{id}.

Path Parameters

• gitRef string (required)
  The GitRef containing the resource(s).
• id string (required)
  ID of the Runbook to delete.
• projectId string (required)
  The ID of the project.
• spaceId string (required)
  The ID of the space containing the resource(s).

Request Body

• ChangeDescription string
  The commit message for updating the Git repository.
• GitRef string (required)
  The GitRef containing the resource(s).
• Id string (required)
  ID of the Runbook to delete.
• ProjectId string (required)
  The ID of the project.
• SpaceId string (required)
  The ID of the space containing the resource(s).

Response

200 — Success

{
  "ChangeDescription": "string",
  "GitRef": "string",
  "Id": "string",
  "ProjectId": "string",
  "SpaceId": "string"
}

GET /api/{spaceId}/projects/{projectId}/{gitRef}/runbooks/{id}/environments

Also reachable at /api/projects/{projectId}/{gitRef}/runbooks/{id}/environments, /api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/runbooks/{id}/environments.

Path Parameters

• gitRef string (required)
  The Git ref to read the runbook from.
• id string (required)
  ID of the Runbook.
• projectId string (required)
  The ID of the project containing this resource.
• spaceId string (required)
  The ID of the space containing the resource(s).

Response

200 — The requested list of Runbook Environments

• AllowDynamicInfrastructure boolean
  If set to true, deployments to this environment will be allowed to contain steps that manage infrastructure. This relies on DeploymentActionResource being set to allow managing resource for a step.
• Description string
  Gets or sets a short description of this environment that can be used to explain the purpose of the environment to other users. This field may contain markdown.
• EnvironmentTags array of string
  List of tags assigned to this environment.
• ExtensionSettings array of object
  • ExtensionId string
  • Values string
• Id string
  Gets or sets a unique identifier for this resource.
• LastModifiedBy string
  Gets or sets the username of the user who last modified this resource.
• LastModifiedOn string
  Gets or sets the date/time that this resource was last modified. Format date-time.
• Links object
  Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.
• Name string
  Gets or sets the name of this environment. This should be short, preferably 5-20 characters.
• Slug string
• SortOrder integer
  Gets or sets a number indicating the priority of this environment in sort order. Environments with a lower sort order will appear in the UI before items with a higher sort order.
• SpaceId string
• UseGuidedFailure boolean
  If set to true, deployments will prompt for manual intervention (Fail/Retry/Ignore) when failures are encountered in activities that support it. May be overridden with the Octopus.UseGuidedFailure special variable.

[
  {
    "AllowDynamicInfrastructure": true,
    "Description": "string",
    "EnvironmentTags": [
      "string"
    ],
    "ExtensionSettings": [
      {
        "ExtensionId": "string",
        "Values": "string"
      }
    ],
    "Id": "string",
    "LastModifiedBy": "string",
    "LastModifiedOn": "2020-01-01T00:00:00.000Z",
    "Links": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    },
    "Name": "string",
    "Slug": "string",
    "SortOrder": 0,
    "SpaceId": "string",
    "UseGuidedFailure": true
  }
]