diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000000..035d938389 --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,3 @@ +{ + "ignores": ["src/pages/docs/api/**"] +} diff --git a/astro.config.mjs b/astro.config.mjs index d65af08e15..a5f2c67a89 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -5,6 +5,8 @@ import { attributeMarkdown, wrapTables } from '/src/themes/octopus/utilities/cus import llmMdEmitter from './src/integrations/llm-md-emitter.ts'; import pruneDist from './src/integrations/prune-dist.ts'; import satteriHeadingId from './src/plugins/satteri-heading-id.js'; +import satteriApiExamples, { apiExampleDirective } from './src/plugins/satteri-api-examples.js'; +import { endpointDirective } from './src/plugins/satteri-endpoint.js'; import satteriWbr from './src/plugins/satteri-wbr.js'; import shikiCodeBlock from './src/plugins/shiki-code-block.js'; @@ -52,10 +54,16 @@ export default defineConfig({ mdastPlugins: [ satteriHeadingId, attributeMarkdown, + // After attributeMarkdown, whose generic handler would otherwise + // render `:::api-example` as an tag, and + // `:endpoint` as an one + apiExampleDirective, + endpointDirective, wrapTables ], hastPlugins: [ - satteriWbr + satteriWbr, + satteriApiExamples ], }), }, diff --git a/cspell.json b/cspell.json index 4777dcd8b2..f88ac75301 100644 --- a/cspell.json +++ b/cspell.json @@ -61,6 +61,7 @@ ".octopus/**", ".vscode/**", ".github/**", + "src/pages/docs/api/**", "src/pages/report/**", "src/fallback/**", "src/scripts/**", diff --git a/src/components/ApiNavigation.astro b/src/components/ApiNavigation.astro new file mode 100644 index 0000000000..15fecfbcc6 --- /dev/null +++ b/src/components/ApiNavigation.astro @@ -0,0 +1,134 @@ +--- +import { accelerator } from '@lib/accelerator'; +import { Translations, Lang } from '@util/Languages'; +import { apiMenu } from '@lib/apiNavigation'; + +const stats = new accelerator.statistics('components/ApiNavigation.astro'); +stats.start(); + +type Props = { + lang: string; + headings: { depth: number; slug: string; text: string }[]; + // One entry per endpoint, in heading order, left on the frontmatter by + // plugins/satteri-api-examples.js from the `:endpoint` directive under each + // heading. Sections without one — and pages that never reach that plugin — + // simply have none. + apiMethods?: + | { text: string; method: string | null; deprecated?: boolean }[] + | null; +}; +const { lang, headings, apiMethods } = Astro.props satisfies Props; + +// The four the API badges in api.css cover. Title case because the badge is an +// image to a screen reader, and reads as a word rather than as shouting. +const METHOD_LABELS: Record = { + get: 'Get', + post: 'Post', + put: 'Put', + delete: 'Delete', +}; + +// Astro escapes a brace in heading text as `${`, so a title that is a route — +// "GET /api/{spaceId}/environments" — survives being read as an expression. The +// methods are collected before that happens, so the two are compared unescaped. +function headingText(text: string): string { + return text.replace(/\$\{/g, '{').trim(); +} + +const _ = Lang(lang); + +// Only the page the reader is on lists its endpoints. Expanding every page +// would put thousands of anchors in the markup of all ~100 of them, and it is +// the rule the site nav follows too: the branch you are inside is the one that +// opens. +const currentPath = Astro.url.pathname.replace(/\/$/, ''); + +// An endpoint per H2, which is the first level of content on a generated API +// page. +// +// The methods are in the same order, an endpoint each, so they pair off by +// position — two endpoints on a page can share a title, which is what rules out +// pairing them by it. The title is checked all the same: if the two lists have +// drifted apart, the nav goes without badges rather than hanging the wrong one +// on a row. +const endpoints = (headings ?? []) + .filter((heading) => heading.depth === 2) + .map((heading, index) => { + const endpoint = apiMethods?.[index]; + const matches = endpoint?.text === headingText(heading.text); + const method = matches ? (endpoint.method ?? '') : ''; + + return { + ...heading, + method: method in METHOD_LABELS ? method : null, + deprecated: matches && endpoint.deprecated === true, + }; + }); + +const pages = apiMenu().map((page) => ({ + ...page, + isCurrent: page.url.replace(/\/$/, '') === currentPath, +})); + +stats.stop(); +--- + + diff --git a/src/layouts/Api.astro b/src/layouts/Api.astro new file mode 100644 index 0000000000..a62b77d0e8 --- /dev/null +++ b/src/layouts/Api.astro @@ -0,0 +1,123 @@ +--- +import { accelerator } from '@lib/accelerator'; +import { PostFiltering } from 'astro-accelerator-utils'; +import type { Frontmatter as OriginalFrontmatter } from 'astro-accelerator-utils/types/Frontmatter'; +import { SITE } from '@config'; +import { buildApiCrumbs } from '@lib/apiNavigation'; +import type { Crumb } from '@util/breadcrumbs'; + +// Theme components +import Head from '@components/HtmlHead.astro'; +import SkipLinks from '@components/SkipLinks.astro'; +import Breadcrumbs from '@components/Breadcrumbs.astro'; +import Authors from '@components/Authors.astro'; +import Taxonomy from '@components/Taxonomy.astro'; + +// Custom components +import ApiNavigation from '../components/ApiNavigation.astro'; +import ArticleHeader from '../components/ArticleHeader.astro'; +import Feedback from '../components/Feedback.astro'; +import Header from '../components/Header.astro'; +import Plausible from 'src/components/Plausible.astro'; +import Footer from 'src/components/Footer.astro'; +import DocsSearch from '../components/DocsSearch.astro'; + +type Props = { + // `apiMethods` is not written by hand: plugins/satteri-api-examples.js leaves + // it on the frontmatter for the left nav, an entry per endpoint. + frontmatter: OriginalFrontmatter & { + apiMethods?: { text: string; method: string | null }[]; + }; + headings: { depth: number; slug: string; text: string }[]; + breadcrumbs?: Crumb[] | null; +}; +const { frontmatter, headings, breadcrumbs } = Astro.props satisfies Props; + +// buildApiCrumbs, not buildCrumbs: the section has no page of its own at +// /docs/api for the generic walk to find, so it splices the crumb in. +const crumbs = buildApiCrumbs(Astro.url, breadcrumbs); + +const lang = frontmatter.lang ?? SITE.default.lang; +const textDirection = frontmatter.dir ?? SITE.default.dir; + +// Logic +const title = await accelerator.markdown.getInlineHtmlFrom( + frontmatter.title ?? SITE.title +); + +const subtitle = frontmatter.subtitle + ? await accelerator.markdown.getInlineHtmlFrom(frontmatter.subtitle) + : null; + +const site_url = SITE.url; +const site_features = SITE.featureFlags; +const search = + accelerator.posts.all().filter(PostFiltering.isSearch).shift() ?? null; +const searchUrl = search && accelerator.urlFormatter.formatAddress(search.url); +const isSearchPage = + accelerator.urlFormatter.formatAddress(Astro.url.pathname) === searchUrl; + +const showSearch = !isSearchPage; + +// The footer prints this; JSON-LD carries it as dateModified. +const lastUpdated = frontmatter.modDate ?? frontmatter.pubDate ?? null; +--- + + + + + +
+ +
+
+ +
+ +
+ { + /* Copy as markdown temporarily disabled until we can get it working with the API docs. Deliberately no "Edit on GitHub" because these are generated and should not be hand edited */ + } +
+
+ + + +
+
+ +
+ +
+
+ { + /* The overlay the header's search field opens. Same single instance as + Default.astro, and not behind `showSearch` for the same reason. */ + } + + + + + + diff --git a/src/lib/accelerator.ts b/src/lib/accelerator.ts index 88689ea5c2..be3bc74df1 100644 --- a/src/lib/accelerator.ts +++ b/src/lib/accelerator.ts @@ -32,13 +32,38 @@ const posts = accelerator.posts; // 1.1 MB of JSON is ~18 ms. // Builds only. In dev the page set changes under you, so keep reading through. const readAll = posts.all.bind(posts); + +// Posts.all() globs every markdown file under src/pages, including the ones +// Astro does not route: anything with an underscore-prefixed path segment. Those +// are not pages, so they have no business in the nav, the breadcrumb trail, the +// taxonomy, or the /report pages - each of which would link to a URL that 404s. +// Astro's own routing rule is the filter. +const PAGES_ROOT = '/src/pages/'; +const isRouted = (post: { file?: string }) => { + const file = post.file ?? ''; + // Only the path below src/pages decides routing. In local development the + // generated API pages are symlinked in, so `file` resolves to wherever the + // generator wrote them - checking the whole absolute path could catch a + // directory of the developer's that happens to start with an underscore. + const index = file.lastIndexOf(PAGES_ROOT); + const routePath = + index === -1 + ? file.slice(file.lastIndexOf('/') + 1) + : file.slice(index + PAGES_ROOT.length); + return !routePath.split('/').some((part) => part.startsWith('_')); +}; + +const readRouted = () => readAll().filter(isRouted); + let allPosts: ReturnType | null = null; if (import.meta.env.PROD) { posts.all = () => { - if (allPosts === null) allPosts = readAll(); + if (allPosts === null) allPosts = readRouted(); return allPosts.slice(); }; +} else { + posts.all = readRouted; } const shadow = (key: string, value: unknown) => diff --git a/src/lib/apiNavigation.ts b/src/lib/apiNavigation.ts new file mode 100644 index 0000000000..7aa51c7827 --- /dev/null +++ b/src/lib/apiNavigation.ts @@ -0,0 +1,127 @@ +import type { MarkdownInstance } from 'astro-accelerator-utils/types/Astro'; +import { accelerator } from './accelerator'; +import { SITE } from '@config'; +import { buildCrumbs, type Crumb } from '@util/breadcrumbs'; + +// The API reference carries its own left nav, built here from the pages that +// opt into src/layouts/Api.astro. Those same pages are pruned out of the main +// site nav in navigationTree.ts, so the two trees never overlap. +// +// Unlike the site nav, this one is flat: an entry per page, and under the page +// the reader is on, an entry per endpoint. The endpoints come from the layout's +// own headings rather than from here — Posts.all() reads the page set back from +// a JSON cache, which leaves the frontmatter intact but drops getHeadings(). + +const API_LAYOUT = '/Api.astro'; + +const PAGES_ROOT = '/src/pages'; + +const API_SECTION_TITLE = 'Api'; + +function urlFromSourcePath(path: string): string { + return path + .slice(PAGES_ROOT.length) + .replace(/\.md$/, '') + .replace(/\/index$/, ''); +} + +// Astro only gives a page module a `url` when its file resolves inside +// src/pages. The generated pages are usually copied in, but they are symlinked +// in during local development, and a symlink resolves to wherever the generator +// wrote it — so those modules arrive with a file outside the site and no url at +// all. The glob keys are the paths the site routes on either way, so the url is +// rebuilt from them and the module's own url is only a fallback. +function urlsByFile(): Map { + // The glob call stays inside the function on purpose. These pages render + // through src/layouts/Api.astro, which imports ApiNavigation.astro, which + // imports this module — so the eager glob closes a cycle back onto itself. + // Vite hoists the imports but builds the map object where the call sits, so + // at module load the first page in the cycle is still initializing and a + // top-level call captures `undefined` for it permanently. Called from in here + // the object is built on the way past, once everything has settled. + const source = import.meta.glob<{ file?: string }>( + '/src/pages/docs/api/**/*.md', + { eager: true } + ); + + return new Map( + Object.entries(source) + .filter(([, post]) => post?.file != null) + .map(([path, post]) => [post.file as string, urlFromSourcePath(path)]) + ); +} + +export type ApiNavPage = { + title: string; + url: string; + order: number; +}; + +export function isApiPage(post: MarkdownInstance): boolean { + return (post?.frontmatter?.layout ?? '').includes(API_LAYOUT); +} + +// Same deal as menuTemplate(): the list is identical for every page in the +// section, so it is built once and read by all of them. +let pages: ApiNavPage[] | null = null; + +export function apiMenu(): ApiNavPage[] { + // Builds only. In dev, rebuild every time so a new or edited page shows up + // in the nav without restarting the server. + if (pages !== null && import.meta.env.PROD) return pages; + + const urls = urlsByFile(); + + const menu = accelerator.posts + .all() + .filter(isApiPage) + .map((post) => ({ + title: post.frontmatter.navTitle ?? post.frontmatter.title, + url: accelerator.urlFormatter.addSlashToAddress( + post.url ?? urls.get(post.file) ?? '/' + ), + order: post.frontmatter.navOrder ?? Number.MAX_SAFE_INTEGER, + })) + // The pages are generated one per API area and carry no navOrder, so the + // fallback is the alphabetical order the index page already lists them in. + .sort((a, b) => a.order - b.order || a.title.localeCompare(b.title)); + + if (import.meta.env.PROD) pages = menu; + return menu; +} + +/** + * Every API page URL, trailing slash trimmed, for the site nav to prune + * against. + */ +export function apiPageUrls(): Set { + return new Set(apiMenu().map((page) => page.url.replace(/\/$/, ''))); +} + +// The API reference has no page of its own at /docs/api yet - `_index.md` is +// underscore-prefixed so Astro does not route it - so the generic breadcrumb +// walk, which builds a crumb per path segment that resolves to a page, skips +// straight from Docs to the endpoint page. Splice the section in by hand so an +// API page reads "Docs / Api / Feeds". +// +// The crumb carries no url on purpose: there is nothing to link to until the +// landing page lands. +export function buildApiCrumbs( + currentUrl: URL, + extraCrumbs?: ReadonlyArray | null +): Crumb[] { + const crumbs = buildCrumbs(currentUrl, extraCrumbs); + const sectionPath = SITE.subfolder + '/api'; + + if (!currentUrl.pathname.startsWith(sectionPath)) return crumbs; + if (crumbs.some((crumb) => crumb.title === API_SECTION_TITLE)) return crumbs; + + // After the /docs crumb, which is the only one the walk finds above us. + const insertAt = crumbs.findIndex( + (crumb) => crumb.url.replace(/\/$/, '') === SITE.subfolder + ); + + const section: Crumb = { url: '', title: API_SECTION_TITLE }; + crumbs.splice(insertAt + 1, 0, section); + return crumbs; +} diff --git a/src/lib/navigationTree.ts b/src/lib/navigationTree.ts index 449620b3f3..8b7e48177a 100644 --- a/src/lib/navigationTree.ts +++ b/src/lib/navigationTree.ts @@ -2,6 +2,7 @@ import type { NavPage } from 'astro-accelerator-utils/types/NavPage'; import { SITE } from '@config'; import { menu } from '@data/navigation'; import { accelerator } from './accelerator'; +import { apiPageUrls } from './apiNavigation'; // Navigation.autoMenu() rebuilds the whole site nav tree from all ~2,700 pages // on every page render, and its getChildren() runs a full scan of that page @@ -18,14 +19,32 @@ const TEMPLATE_URL = new URL('https://octopus.com/__nav-template__'); let template: NavPage[] | null = null; +// The API reference is navigated by its own tree (lib/apiNavigation.ts), so +// its pages are dropped here rather than listed in both. Dropping a node drops +// its children with it, which is what takes the whole section out in one go. +function withoutApiPages(pages: NavPage[]): NavPage[] { + const apiUrls = apiPageUrls(); + const prune = (nodes: NavPage[]): NavPage[] => + nodes + .filter((node) => !apiUrls.has((node.url ?? '').replace(/\/$/, ''))) + .map((node) => ({ ...node, children: prune(node.children ?? []) })); + return prune(pages); +} + +function buildMenu(): NavPage[] { + return withoutApiPages( + accelerator.navigation.menu(TEMPLATE_URL, SITE.subfolder, menu) + ); +} + export function menuTemplate(): NavPage[] { // Builds only. In dev, rebuild every time so a new or renamed page shows up // in the nav without restarting the server. if (!import.meta.env.PROD) { - return accelerator.navigation.menu(TEMPLATE_URL, SITE.subfolder, menu); + return buildMenu(); } if (template === null) { - template = accelerator.navigation.menu(TEMPLATE_URL, SITE.subfolder, menu); + template = buildMenu(); } return template; } diff --git a/src/lib/underConstruction.ts b/src/lib/underConstruction.ts new file mode 100644 index 0000000000..042bd23513 --- /dev/null +++ b/src/lib/underConstruction.ts @@ -0,0 +1,20 @@ +// TEMPORARY - delete this file when the API reference goes live. +// +// The generated API reference under src/pages/docs/api is published, but the +// section is still under construction: there is no landing page, the existing +// /docs/octopus-rest-api content has not been folded in, and nothing links to +// it. Until that work lands we keep it out of the site search index and out of +// sitemap.xml, so neither readers nor Google arrive at it ahead of the pages +// that explain it. +// +// Call sites are src/pages/docs/search.json.ts and src/pages/docs/sitemap.xml.ts. +// Both take their page list from an `import.meta.glob` rooted at +// src/pages/docs, so the paths they pass in look like './api/feeds.md'. + +const UNDER_CONSTRUCTION = [/^api(\/|$)/]; + +/** True for a page that is built and published, but deliberately not indexed. */ +export function isUnderConstruction(globPath: string): boolean { + const path = globPath.replace(/^\.?\//, ''); + return UNDER_CONSTRUCTION.some((pattern) => pattern.test(path)); +} diff --git a/src/pages/docs/api/.gitattributes b/src/pages/docs/api/.gitattributes new file mode 100644 index 0000000000..b674b2f4ee --- /dev/null +++ b/src/pages/docs/api/.gitattributes @@ -0,0 +1,3 @@ +# These files are generated with LF line endings and compared byte for byte by ApiDocsTests, so they must not +# be translated to CRLF on checkout. +*.md text eol=lf diff --git a/src/pages/docs/api/access-tokens.md b/src/pages/docs/api/access-tokens.md new file mode 100644 index 0000000000..047a43e95e --- /dev/null +++ b/src/pages/docs/api/access-tokens.md @@ -0,0 +1,25 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Access Tokens +--- + +## Create an access token for the current user + +:endpoint{method="POST" path="/api/users/access-token"} + +**Response** + +`200` — Contains the created access token. + +- **`AccessToken`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "AccessToken": "string" +} +``` +::: diff --git a/src/pages/docs/api/accounts.md b/src/pages/docs/api/accounts.md new file mode 100644 index 0000000000..839287b30b --- /dev/null +++ b/src/pages/docs/api/accounts.md @@ -0,0 +1,793 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Accounts +--- + +## Get a list of accounts + +:endpoint{method="GET" path="/api/\{spaceId\}/accounts"} + +Also reachable at `/api/accounts`, `/api/spaces/{spaceIdentifier}/accounts`. + +Lists accounts in the supplied Octopus Deploy Space in pages. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`accountType`** :span[array of string]{.type-label} + The type of accounts to return. +- **`name`** :span[string]{.type-label} + The exact name of an Account to be matched. +- **`partialName`** :span[string]{.type-label} + A partial account name used for a sub-string search. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The list of Accounts + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`AccountType`** :span[enum]{.type-label} + Allowed values: `AmazonWebServicesAccount`, `AmazonWebServicesOidcAccount`, `AzureOidc`, `AzureServicePrincipal`, `AzureSubscription`, `GenericOidcAccount`, `GoogleCloudAccount`, `GoogleCloudOidcAccount`, `None`, `SshKeyPair`, `Token`, `UsernamePassword`. + - **`Description`** :span[string]{.type-label} + - **`EnvironmentIds`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`TenantIds`** :span[array of string]{.type-label} + - **`TenantTags`** :span[array of string]{.type-label} + - **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "AccountType": "AmazonWebServicesAccount", + "Description": "string", + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted" + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new account - of the type defined by body content + +:endpoint{method="POST" path="/api/\{spaceId\}/accounts"} + +Also reachable at `/api/accounts`, `/api/spaces/{spaceIdentifier}/accounts`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} *(required)* + - **`AccountType`** :span[string]{.type-label} +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Details": { + "AccountType": "string" + }, + "EnvironmentIds": [ + "string" + ], + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`AccountType`** :span[enum]{.type-label} + Allowed values: `AmazonWebServicesAccount`, `AmazonWebServicesOidcAccount`, `AzureOidc`, `AzureServicePrincipal`, `AzureSubscription`, `GenericOidcAccount`, `GoogleCloudAccount`, `GoogleCloudOidcAccount`, `None`, `SshKeyPair`, `Token`, `UsernamePassword`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + +:::api-example{label="Response"} +```json +{ + "AccountType": "AmazonWebServicesAccount", + "Description": "string", + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted" +} +``` +::: + +## Get a list of Accounts + +:endpoint{method="GET" path="/api/\{spaceId\}/accounts/all"} + +Also reachable at `/api/accounts/all`, `/api/spaces/{spaceIdentifier}/accounts/all`. + +Lists all of the accounts in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested list of Accounts + +- **`AccountType`** :span[enum]{.type-label} + Allowed values: `AmazonWebServicesAccount`, `AmazonWebServicesOidcAccount`, `AzureOidc`, `AzureServicePrincipal`, `AzureSubscription`, `GenericOidcAccount`, `GoogleCloudAccount`, `GoogleCloudOidcAccount`, `None`, `SshKeyPair`, `Token`, `UsernamePassword`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + +:::api-example{label="Response"} +```json +[ + { + "AccountType": "AmazonWebServicesAccount", + "Description": "string", + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted" + } +] +``` +::: + +## List the Azure Environments provided by the SDK + +:endpoint{method="GET" path="/api/accounts/azureenvironments"} + +List the Azure Environments provided by the SDK + +**Response** + +`200` — OK + +## Modify the account identified by the accoutId + +:endpoint{method="PUT" path="/api/\{spaceId\}/accounts/\{accountId\}"} + +Also reachable at `/api/accounts/{accountId}`, `/api/spaces/{spaceIdentifier}/accounts/{accountId}`. + +**Path Parameters** + +- **`accountId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`AccountId`** :span[string]{.type-label} *(required)* +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} *(required)* + - **`AccountType`** :span[string]{.type-label} +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "AccountId": "string", + "Description": "string", + "Details": { + "AccountType": "string" + }, + "EnvironmentIds": [ + "string" + ], + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "string" +} +``` +::: + +**Response** + +`200` — The resource returned from modifying an account + +- **`AccountType`** :span[enum]{.type-label} + Allowed values: `AmazonWebServicesAccount`, `AmazonWebServicesOidcAccount`, `AzureOidc`, `AzureServicePrincipal`, `AzureSubscription`, `GenericOidcAccount`, `GoogleCloudAccount`, `GoogleCloudOidcAccount`, `None`, `SshKeyPair`, `Token`, `UsernamePassword`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + +:::api-example{label="Response"} +```json +{ + "AccountType": "AmazonWebServicesAccount", + "Description": "string", + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted" +} +``` +::: + +## Get an Account by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/accounts/\{id\}"} + +Also reachable at `/api/accounts/{id}`, `/api/spaces/{spaceIdentifier}/accounts/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the account. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Account + +- **`AccountType`** :span[enum]{.type-label} + Allowed values: `AmazonWebServicesAccount`, `AmazonWebServicesOidcAccount`, `AzureOidc`, `AzureServicePrincipal`, `AzureSubscription`, `GenericOidcAccount`, `GoogleCloudAccount`, `GoogleCloudOidcAccount`, `None`, `SshKeyPair`, `Token`, `UsernamePassword`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + +:::api-example{label="Response"} +```json +{ + "AccountType": "AmazonWebServicesAccount", + "Description": "string", + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted" +} +``` +::: + +## Delete an existing Account + +:endpoint{method="DELETE" path="/api/\{spaceId\}/accounts/\{id\}"} + +Also reachable at `/api/accounts/{id}`, `/api/spaces/{spaceIdentifier}/accounts/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Account to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Retrieve the public key portion of the account's associated certificate, if present + +:endpoint{method="GET" path="/api/\{spaceId\}/accounts/\{id\}/pk"} + +Also reachable at `/api/accounts/{id}/pk`, `/api/spaces/{spaceIdentifier}/accounts/{id}/pk`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the account. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## List the Resource Groups associated with an Azure account + +:endpoint{method="GET" path="/api/\{spaceId\}/accounts/\{id\}/resourceGroups"} + +Also reachable at `/api/accounts/{id}/resourceGroups`, `/api/spaces/{spaceIdentifier}/accounts/{id}/resourceGroups`. + +List the Resource Groups associated with an Azure account. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — OK + +## List the storage accounts associated with an Azure account + +:endpoint{method="GET" path="/api/\{spaceId\}/accounts/\{id\}/storageAccounts"} + +Also reachable at `/api/accounts/{id}/storageAccounts`, `/api/spaces/{spaceIdentifier}/accounts/{id}/storageAccounts`. + +List the storage accounts associated with an Azure account. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — OK + +## List projects and deployments which are using an account + +:endpoint{method="GET" path="/api/\{spaceId\}/accounts/\{id\}/usages"} + +Also reachable at `/api/accounts/{id}/usages`, `/api/spaces/{spaceIdentifier}/accounts/{id}/usages`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the account. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The projects and deployments which are using an account. + +- **`CommonTenantVariables`** :span[array of object]{.type-label} + - **`LibraryVariableSets`** :span[array of object]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`DeploymentProcesses`** :span[array of object]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`ProjectSlug`** :span[string]{.type-label} + - **`Steps`** :span[array of object]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSets`** :span[array of object]{.type-label} + - **`LibraryVariableSetId`** :span[string]{.type-label} + - **`LibraryVariableSetName`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectTenantVariables`** :span[array of object]{.type-label} + - **`Projects`** :span[array of object]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`ProjectVariableSets`** :span[array of object]{.type-label} + - **`IsCurrentlyBeingUsedInProject`** :span[boolean]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`ProjectSlug`** :span[string]{.type-label} + - **`Releases`** :span[array of object]{.type-label} + - **`RunbookSnapshots`** :span[array of object]{.type-label} +- **`Releases`** :span[array of object]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`Releases`** :span[array of object]{.type-label} +- **`RunbookProcesses`** :span[array of object]{.type-label} + - **`ProcessId`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`ProjectSlug`** :span[string]{.type-label} + - **`RunbookId`** :span[string]{.type-label} + - **`RunbookName`** :span[string]{.type-label} + - **`Steps`** :span[array of object]{.type-label} +- **`RunbookSnapshots`** :span[array of object]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`RunbookId`** :span[string]{.type-label} + - **`RunbookName`** :span[string]{.type-label} + - **`Snapshots`** :span[array of object]{.type-label} +- **`Targets`** :span[array of object]{.type-label} + - **`TargetId`** :span[string]{.type-label} + - **`TargetName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CommonTenantVariables": [ + { + "LibraryVariableSets": [ + {} + ], + "TenantId": "string" + } + ], + "DeploymentProcesses": [ + { + "ProjectId": "string", + "ProjectName": "string", + "ProjectSlug": "string", + "Steps": [ + {} + ] + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSets": [ + { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string" + } + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectTenantVariables": [ + { + "Projects": [ + {} + ], + "TenantId": "string" + } + ], + "ProjectVariableSets": [ + { + "IsCurrentlyBeingUsedInProject": true, + "ProjectId": "string", + "ProjectName": "string", + "ProjectSlug": "string", + "Releases": [ + {} + ], + "RunbookSnapshots": [ + {} + ] + } + ], + "Releases": [ + { + "ProjectId": "string", + "ProjectName": "string", + "Releases": [ + {} + ] + } + ], + "RunbookProcesses": [ + { + "ProcessId": "string", + "ProjectId": "string", + "ProjectName": "string", + "ProjectSlug": "string", + "RunbookId": "string", + "RunbookName": "string", + "Steps": [ + {} + ] + } + ], + "RunbookSnapshots": [ + { + "ProjectId": "string", + "ProjectName": "string", + "RunbookId": "string", + "RunbookName": "string", + "Snapshots": [ + {} + ] + } + ], + "Targets": [ + { + "TargetId": "string", + "TargetName": "string" + } + ] +} +``` +::: + +## Delete an existing Account + +:endpoint{method="DELETE" path="/api/\{spaceId\}/accounts/\{id\}/v1"} + +Also reachable at `/api/accounts/{id}/v1`, `/api/spaces/{spaceIdentifier}/accounts/{id}/v1`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Account to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the Account was deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## List the websites associated with an Azure account + +:endpoint{method="GET" path="/api/\{spaceId\}/accounts/\{id\}/websites"} + +Also reachable at `/api/accounts/{id}/websites`, `/api/spaces/{spaceIdentifier}/accounts/{id}/websites`. + +List the websites associated with an Azure account. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — OK + +## List the slots associated with an Azure Web Site + +:endpoint{method="GET" path="/api/\{spaceId\}/accounts/\{id\}/\{resourceGroupName\}/websites/\{webSiteName\}/slots"} + +Also reachable at `/api/accounts/{id}/{resourceGroupName}/websites/{webSiteName}/slots`, `/api/spaces/{spaceIdentifier}/accounts/{id}/{resourceGroupName}/websites/{webSiteName}/slots`. + +List the slots associated with an Azure Web Site. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`resourceGroupName`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* +- **`webSiteName`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — OK + +## Get the account types this Octopus Server supports + +:endpoint{method="GET" path="/api/accounttypes"} + +Lists the account types contributed by the extensions installed on this Server, sorted by name. + +**Response** + +`200` — The account types this Octopus Server supports + +- **`AccountTypes`** :span[array of string]{.type-label} + The supported account types, sorted by name. Each value is what an Account's AccountType is set to, and what the AccountType filter when listing accounts accepts. + +:::api-example{label="Response"} +```json +{ + "AccountTypes": [ + "string" + ] +} +``` +::: diff --git a/src/pages/docs/api/action-templates.md b/src/pages/docs/api/action-templates.md new file mode 100644 index 0000000000..d896e47005 --- /dev/null +++ b/src/pages/docs/api/action-templates.md @@ -0,0 +1,2214 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Action Templates +--- + +## Delete an existing Action Template and all its versions + +:endpoint{method="DELETE" path="/api/\{spaceId\}/actionTemplates/\{id\}"} + +Also reachable at `/api/actionTemplates/{id}`, `/api/spaces/{spaceIdentifier}/actionTemplates/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Action Template to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Delete an existing Action Template and all its versions + +:endpoint{method="DELETE" path="/api/\{spaceId\}/actionTemplates/\{id\}/v1"} + +Also reachable at `/api/actionTemplates/{id}/v1`, `/api/spaces/{spaceIdentifier}/actionTemplates/{id}/v1`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Action Template to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the requested Action Template has been deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get a list of Action Templates + +:endpoint{method="GET" path="/api/\{spaceId\}/actiontemplates"} + +Also reachable at `/api/actiontemplates`, `/api/spaces/{spaceIdentifier}/actiontemplates`. + +Lists all of the Action Templates in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + IDs of the action templates to fetch. +- **`isCommunityActionTemplate`** :span[boolean]{.type-label} + Filters the results based on whether the action is a community template. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a \"contains\" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested Action Templates + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`ActionType`** :span[string]{.type-label} + Minimum length 1. + - **`CommunityActionTemplateId`** :span[string]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`GitDependencies`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`Packages`** :span[array of object]{.type-label} + - **`Parameters`** :span[array of object]{.type-label} + - **`Properties`** :span[object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "ActionType": "string", + "CommunityActionTemplateId": "string", + "Description": "string", + "GitDependencies": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Packages": [ + {} + ], + "Parameters": [ + {} + ], + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "SpaceId": "string", + "Version": 0 + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create an Action Template + +:endpoint{method="POST" path="/api/\{spaceId\}/actiontemplates"} + +Also reachable at `/api/actiontemplates`, `/api/spaces/{spaceIdentifier}/actiontemplates`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the Space that contains the Action Template. + +**Request Body** + +- **`ActionType`** :span[string]{.type-label} *(required)* + The action type of the Action Template. Minimum length 1. +- **`CommunityActionTemplateId`** :span[string]{.type-label} + The community action template id if the Action Template is created from a community template. +- **`Description`** :span[string]{.type-label} + The description of the Action Template. +- **`GitDependencies`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitCredentialType`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} *(required)* + - **`RepositoryUri`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} +- **`Inputs`** :span[object]{.type-label} + - **`Value`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + The name of the Action Template. Minimum length 1. +- **`Packages`** :span[array of object]{.type-label} + The list of packages to include in the Action Template. + - **`AcquisitionLocation`** :span[string]{.type-label} + The package-acquisition location. One of PackageAcquisitionLocationResource or a variable-expression. + - **`FeedId`** :span[string]{.type-label} + Feed ID, name or a variable-expression. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + A name for the package-reference. This may be empty. This is used to discriminate the package-references. Package ID isn't suitable because an action may potentially have multiple references to the same package ID (e.g. if you wanted to use different versions of the same package). Also, the package ID may be a variable-expression. + - **`PackageId`** :span[string]{.type-label} + Package ID or a variable-expression. + - **`Properties`** :span[object]{.type-label} + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} + This reference identifier is populated when a step package step contains a package reference It allows us to correlate the reference within the step package inputs to this Server package reference. + - **`Version`** :span[string]{.type-label} + Specific version to use for this package. If not specified, package can be selected at release creation or runbook run time. +- **`Parameters`** :span[array of object]{.type-label} + The list of parameters of the Action Template. + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Properties`** :span[object]{.type-label} + The list of properties of the Action Template. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The id of the Space that contains the Action Template. +- **`StepPackageVersion`** :span[string]{.type-label} + The step package version if the Action Template is created from a step package. +- **`Version`** :span[integer]{.type-label} + The version number of the Action Template. Minimum `0`. + +:::api-example{label="Request"} +```json +{ + "ActionType": "string", + "CommunityActionTemplateId": "string", + "Description": "string", + "GitDependencies": [ + { + "DefaultBranch": "string", + "FilePathFilters": [ + "string" + ], + "GitCredentialId": "string", + "GitCredentialType": "string", + "GitHubConnectionId": "string", + "Name": "string", + "RepositoryUri": "string", + "StepPackageInputsReferenceId": "string" + } + ], + "Inputs": { + "Value": "string" + }, + "Name": "string", + "Packages": [ + { + "AcquisitionLocation": "string", + "FeedId": "string", + "Id": "string", + "Name": "string", + "PackageId": "string", + "Properties": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "StepPackageInputsReferenceId": "string", + "Version": "string" + } + ], + "Parameters": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "Properties": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + } + }, + "SpaceId": "string", + "StepPackageVersion": "string", + "Version": 0 +} +``` +::: + +**Response** + +`201` — Created + +- **`ActionType`** :span[string]{.type-label} + Minimum length 1. +- **`CommunityActionTemplateId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GitDependencies`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitCredentialType`** :span[string]{.type-label} + Minimum length 1. + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Packages`** :span[array of object]{.type-label} + - **`AcquisitionLocation`** :span[string]{.type-label} + The package-acquisition location. One of PackageAcquisitionLocationResource or a variable-expression. + - **`FeedId`** :span[string]{.type-label} + Feed ID, name or a variable-expression. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + A name for the package-reference. This may be empty. This is used to discriminate the package-references. Package ID isn't suitable because an action may potentially have multiple references to the same package ID (e.g. if you wanted to use different versions of the same package). Also, the package ID may be a variable-expression. + - **`PackageId`** :span[string]{.type-label} + Package ID or a variable-expression. + - **`Properties`** :span[object]{.type-label} + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} + This reference identifier is populated when a step package step contains a package reference It allows us to correlate the reference within the step package inputs to this Server package reference. + - **`Version`** :span[string]{.type-label} + Specific version to use for this package. If not specified, package can be selected at release creation or runbook run time. +- **`Parameters`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Properties`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ActionType": "string", + "CommunityActionTemplateId": "string", + "Description": "string", + "GitDependencies": [ + { + "DefaultBranch": "string", + "FilePathFilters": [ + "string" + ], + "GitCredentialId": "string", + "GitCredentialType": "string", + "GitHubConnectionId": "string", + "Name": "string", + "RepositoryUri": "string", + "StepPackageInputsReferenceId": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Packages": [ + { + "AcquisitionLocation": "string", + "FeedId": "string", + "Id": "string", + "Name": "string", + "PackageId": "string", + "Properties": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "StepPackageInputsReferenceId": "string", + "Version": "string" + } + ], + "Parameters": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "Properties": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + } + }, + "SpaceId": "string", + "Version": 0 +} +``` +::: + +## Get all Action Templates + +:endpoint{method="GET" path="/api/\{spaceId\}/actiontemplates/all"} + +Also reachable at `/api/actiontemplates/all`, `/api/spaces/{spaceIdentifier}/actiontemplates/all`. + +Lists the all of the action templates in the supplied Octopus Deploy Space. The results will be sorted by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Action Templates + +- **`ActionType`** :span[string]{.type-label} + Minimum length 1. +- **`CommunityActionTemplateId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GitDependencies`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitCredentialType`** :span[string]{.type-label} + Minimum length 1. + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Packages`** :span[array of object]{.type-label} + - **`AcquisitionLocation`** :span[string]{.type-label} + The package-acquisition location. One of PackageAcquisitionLocationResource or a variable-expression. + - **`FeedId`** :span[string]{.type-label} + Feed ID, name or a variable-expression. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + A name for the package-reference. This may be empty. This is used to discriminate the package-references. Package ID isn't suitable because an action may potentially have multiple references to the same package ID (e.g. if you wanted to use different versions of the same package). Also, the package ID may be a variable-expression. + - **`PackageId`** :span[string]{.type-label} + Package ID or a variable-expression. + - **`Properties`** :span[object]{.type-label} + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} + This reference identifier is populated when a step package step contains a package reference It allows us to correlate the reference within the step package inputs to this Server package reference. + - **`Version`** :span[string]{.type-label} + Specific version to use for this package. If not specified, package can be selected at release creation or runbook run time. +- **`Parameters`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Properties`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "ActionType": "string", + "CommunityActionTemplateId": "string", + "Description": "string", + "GitDependencies": [ + { + "DefaultBranch": "string", + "FilePathFilters": [ + "string" + ], + "GitCredentialId": "string", + "GitCredentialType": "string", + "GitHubConnectionId": "string", + "Name": "string", + "RepositoryUri": "string", + "StepPackageInputsReferenceId": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Packages": [ + { + "AcquisitionLocation": "string", + "FeedId": "string", + "Id": "string", + "Name": "string", + "PackageId": "string", + "Properties": {}, + "StepPackageInputsReferenceId": "string", + "Version": "string" + } + ], + "Parameters": [ + { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "Properties": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + }, + "SpaceId": "string", + "Version": 0 + } +] +``` +::: + +## Get a list of Action Template categories + +:endpoint{method="GET" path="/api/\{spaceId\}/actiontemplates/categories"} + +Also reachable at `/api/actiontemplates/categories`, `/api/spaces/{spaceIdentifier}/actiontemplates/categories`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Action Template categories + +- **`DisplayOrder`** :span[integer]{.type-label} +- **`Id`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} +- **`Name`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "DisplayOrder": 0, + "Id": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } +] +``` +::: + +## List all available action templates including built-in, custom and community contributed step templates + +:endpoint{method="GET" path="/api/\{spaceId\}/actiontemplates/search"} + +Also reachable at `/api/actiontemplates/search`, `/api/spaces/{spaceIdentifier}/actiontemplates/search`. + +Lists all of the Action Templates in the supplied Octopus Deploy Space that fit the search criteria. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`type`** :span[string]{.type-label} + +**Response** + +`200` — The found Action Templates + +- **`Author`** :span[string]{.type-label} +- **`Categories`** :span[array of string]{.type-label} +- **`Category`** :span[string]{.type-label} +- **`CommunityActionTemplateId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`Features`** :span[array of string]{.type-label} +- **`HasUpdate`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} +- **`IsBuiltIn`** :span[boolean]{.type-label} +- **`IsInstalled`** :span[boolean]{.type-label} +- **`Keywords`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`Prerelease`** :span[boolean]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Type`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} +- **`Website`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Author": "string", + "Categories": [ + "string" + ], + "Category": "string", + "CommunityActionTemplateId": "string", + "Description": "string", + "Features": [ + "string" + ], + "HasUpdate": true, + "Id": "string", + "IsBuiltIn": true, + "IsInstalled": true, + "Keywords": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Prerelease": true, + "SpaceId": "string", + "Type": "string", + "Version": "string", + "Website": "string" + } +] +``` +::: + +## Get an Action Template by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/actiontemplates/\{id\}"} + +Also reachable at `/api/actiontemplates/{id}`, `/api/spaces/{spaceIdentifier}/actiontemplates/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the ActionTemplate to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Action Template + +- **`ActionType`** :span[string]{.type-label} + Minimum length 1. +- **`CommunityActionTemplateId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GitDependencies`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitCredentialType`** :span[string]{.type-label} + Minimum length 1. + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Packages`** :span[array of object]{.type-label} + - **`AcquisitionLocation`** :span[string]{.type-label} + The package-acquisition location. One of PackageAcquisitionLocationResource or a variable-expression. + - **`FeedId`** :span[string]{.type-label} + Feed ID, name or a variable-expression. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + A name for the package-reference. This may be empty. This is used to discriminate the package-references. Package ID isn't suitable because an action may potentially have multiple references to the same package ID (e.g. if you wanted to use different versions of the same package). Also, the package ID may be a variable-expression. + - **`PackageId`** :span[string]{.type-label} + Package ID or a variable-expression. + - **`Properties`** :span[object]{.type-label} + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} + This reference identifier is populated when a step package step contains a package reference It allows us to correlate the reference within the step package inputs to this Server package reference. + - **`Version`** :span[string]{.type-label} + Specific version to use for this package. If not specified, package can be selected at release creation or runbook run time. +- **`Parameters`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Properties`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ActionType": "string", + "CommunityActionTemplateId": "string", + "Description": "string", + "GitDependencies": [ + { + "DefaultBranch": "string", + "FilePathFilters": [ + "string" + ], + "GitCredentialId": "string", + "GitCredentialType": "string", + "GitHubConnectionId": "string", + "Name": "string", + "RepositoryUri": "string", + "StepPackageInputsReferenceId": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Packages": [ + { + "AcquisitionLocation": "string", + "FeedId": "string", + "Id": "string", + "Name": "string", + "PackageId": "string", + "Properties": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "StepPackageInputsReferenceId": "string", + "Version": "string" + } + ], + "Parameters": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "Properties": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + } + }, + "SpaceId": "string", + "Version": 0 +} +``` +::: + +## Modify an existing action template + +:endpoint{method="PUT" path="/api/\{spaceId\}/actiontemplates/\{id\}"} + +Also reachable at `/api/actiontemplates/{id}`, `/api/spaces/{spaceIdentifier}/actiontemplates/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the existing Action Template. +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the Space that contains the Action Template. + +**Request Body** + +- **`Description`** :span[string]{.type-label} + The description of the Action Template. +- **`GitDependencies`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitCredentialType`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} *(required)* + - **`RepositoryUri`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* + The id of the existing Action Template. +- **`Inputs`** :span[object]{.type-label} + - **`Value`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + The name of the Action Template. Minimum length 1. +- **`Packages`** :span[array of object]{.type-label} + - **`AcquisitionLocation`** :span[string]{.type-label} + The package-acquisition location. One of PackageAcquisitionLocationResource or a variable-expression. + - **`FeedId`** :span[string]{.type-label} + Feed ID, name or a variable-expression. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + A name for the package-reference. This may be empty. This is used to discriminate the package-references. Package ID isn't suitable because an action may potentially have multiple references to the same package ID (e.g. if you wanted to use different versions of the same package). Also, the package ID may be a variable-expression. + - **`PackageId`** :span[string]{.type-label} + Package ID or a variable-expression. + - **`Properties`** :span[object]{.type-label} + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} + This reference identifier is populated when a step package step contains a package reference It allows us to correlate the reference within the step package inputs to this Server package reference. + - **`Version`** :span[string]{.type-label} + Specific version to use for this package. If not specified, package can be selected at release creation or runbook run time. +- **`Parameters`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Properties`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The id of the Space that contains the Action Template. +- **`StepPackageVersion`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "GitDependencies": [ + { + "DefaultBranch": "string", + "FilePathFilters": [ + "string" + ], + "GitCredentialId": "string", + "GitCredentialType": "string", + "GitHubConnectionId": "string", + "Name": "string", + "RepositoryUri": "string", + "StepPackageInputsReferenceId": "string" + } + ], + "Id": "string", + "Inputs": { + "Value": "string" + }, + "Name": "string", + "Packages": [ + { + "AcquisitionLocation": "string", + "FeedId": "string", + "Id": "string", + "Name": "string", + "PackageId": "string", + "Properties": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "StepPackageInputsReferenceId": "string", + "Version": "string" + } + ], + "Parameters": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "Properties": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + } + }, + "SpaceId": "string", + "StepPackageVersion": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Action Template was modified, including the updated template. + +- **`ActionType`** :span[string]{.type-label} + Minimum length 1. +- **`CommunityActionTemplateId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GitDependencies`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitCredentialType`** :span[string]{.type-label} + Minimum length 1. + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Packages`** :span[array of object]{.type-label} + - **`AcquisitionLocation`** :span[string]{.type-label} + The package-acquisition location. One of PackageAcquisitionLocationResource or a variable-expression. + - **`FeedId`** :span[string]{.type-label} + Feed ID, name or a variable-expression. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + A name for the package-reference. This may be empty. This is used to discriminate the package-references. Package ID isn't suitable because an action may potentially have multiple references to the same package ID (e.g. if you wanted to use different versions of the same package). Also, the package ID may be a variable-expression. + - **`PackageId`** :span[string]{.type-label} + Package ID or a variable-expression. + - **`Properties`** :span[object]{.type-label} + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} + This reference identifier is populated when a step package step contains a package reference It allows us to correlate the reference within the step package inputs to this Server package reference. + - **`Version`** :span[string]{.type-label} + Specific version to use for this package. If not specified, package can be selected at release creation or runbook run time. +- **`Parameters`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Properties`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ActionType": "string", + "CommunityActionTemplateId": "string", + "Description": "string", + "GitDependencies": [ + { + "DefaultBranch": "string", + "FilePathFilters": [ + "string" + ], + "GitCredentialId": "string", + "GitCredentialType": "string", + "GitHubConnectionId": "string", + "Name": "string", + "RepositoryUri": "string", + "StepPackageInputsReferenceId": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Packages": [ + { + "AcquisitionLocation": "string", + "FeedId": "string", + "Id": "string", + "Name": "string", + "PackageId": "string", + "Properties": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "StepPackageInputsReferenceId": "string", + "Version": "string" + } + ], + "Parameters": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "Properties": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + } + }, + "SpaceId": "string", + "Version": 0 +} +``` +::: + +## Update deployment and runbook actions to a specific version of the action template + +:endpoint{method="POST" path="/api/\{spaceId\}/actiontemplates/\{id\}/actionsUpdate"} + +Also reachable at `/api/actiontemplates/{id}/actionsUpdate`, `/api/spaces/{spaceIdentifier}/actiontemplates/{id}/actionsUpdate`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the Action Template. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the Space containing the Action Template. + +**Request Body** + +- **`ActionIdsByProcessId`** :span[object]{.type-label} +- **`ActionsToUpdate`** :span[array of object]{.type-label} *(required)* + The actions to be updated to match the action template. + - **`ActionIds`** :span[array of string]{.type-label} *(required)* + The IDs of the actions to update. + - **`GitRef`** :span[string]{.type-label} + The Git reference for the action to update. + - **`ProcessId`** :span[string]{.type-label} *(required)* + The ID of the deployment process which contains the action(s) to update. Minimum length 1. + - **`ProcessType`** :span[enum]{.type-label} *(required)* + The process type of the deployment process containing the action(s) to update. + Allowed values: `Deployment`, `Runbook`. + - **`ProjectId`** :span[string]{.type-label} + The Project Id for the action to update. +- **`DefaultPropertyValues`** :span[object]{.type-label} + Default values for properties of the action template. +- **`Id`** :span[string]{.type-label} *(required)* + The ID of the Action Template. +- **`Overrides`** :span[object]{.type-label} + Overrides for values of the properties of the action template. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the Space containing the Action Template. +- **`Version`** :span[integer]{.type-label} *(required)* + The version of the Action Template. + +:::api-example{label="Request"} +```json +{ + "ActionIdsByProcessId": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "ActionsToUpdate": [ + { + "ActionIds": [ + "string" + ], + "GitRef": "string", + "ProcessId": "string", + "ProcessType": "Deployment", + "ProjectId": "string" + } + ], + "DefaultPropertyValues": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + } + }, + "Id": "string", + "Overrides": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + } + }, + "SpaceId": "string", + "Version": 0 +} +``` +::: + +**Response** + +`200` — ActionUpdateResultResources with details of the results of the update returned + +- **`Id`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} +- **`ManualMergeRequiredReasonsByPropertyName`** :span[object]{.type-label} +- **`NamesOfNewParametersMissingDefaultValue`** :span[array of string]{.type-label} +- **`Outcome`** :span[enum]{.type-label} + Allowed values: `Success`, `ManualMergeRequired`, `DefaultParamterValueMissing`, `RemovedPackageInUse`. +- **`RemovedPackageUsages`** :span[array of object]{.type-label} + - **`PackageReference`** :span[string]{.type-label} + - **`UsedBy`** :span[enum]{.type-label} + Allowed values: `ProjectVersionStrategy`, `ProjectReleaseCreationStrategy`, `ChannelRule`. + - **`UsedById`** :span[string]{.type-label} + - **`UsedByName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Id": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManualMergeRequiredReasonsByPropertyName": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "NamesOfNewParametersMissingDefaultValue": [ + "string" + ], + "Outcome": "Success", + "RemovedPackageUsages": [ + { + "PackageReference": "string", + "UsedBy": "ProjectVersionStrategy", + "UsedById": "string", + "UsedByName": "string" + } + ] + } +] +``` +::: + +## Create a server task to update deployment and runbook actions to a specific version of the action template + +:endpoint{method="POST" path="/api/\{spaceId\}/actiontemplates/\{id\}/actionsUpdate/bulk"} + +Also reachable at `/api/actiontemplates/{id}/actionsUpdate/bulk`, `/api/spaces/{spaceIdentifier}/actiontemplates/{id}/actionsUpdate/bulk`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the Action Template. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the Space containing the Action Template. + +**Request Body** + +- **`ActionsToUpdate`** :span[array of object]{.type-label} *(required)* + The actions to be updated to match the action template. + - **`ActionIds`** :span[array of string]{.type-label} *(required)* + The IDs of the actions to update. + - **`GitRef`** :span[string]{.type-label} + The Git reference for the action to update. + - **`ProcessId`** :span[string]{.type-label} *(required)* + The ID of the deployment process which contains the action(s) to update. Minimum length 1. + - **`ProcessType`** :span[enum]{.type-label} *(required)* + The process type of the deployment process containing the action(s) to update. + Allowed values: `Deployment`, `Runbook`. + - **`ProjectId`** :span[string]{.type-label} + The Project Id for the action to update. +- **`DefaultPropertyValues`** :span[object]{.type-label} + Default values for properties of the action template. +- **`Id`** :span[string]{.type-label} *(required)* + The ID of the Action Template. +- **`Overrides`** :span[object]{.type-label} + Overrides for values of the properties of the action template. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the Space containing the Action Template. +- **`Version`** :span[integer]{.type-label} *(required)* + The version of the Action Template. + +:::api-example{label="Request"} +```json +{ + "ActionsToUpdate": [ + { + "ActionIds": [ + "string" + ], + "GitRef": "string", + "ProcessId": "string", + "ProcessType": "Deployment", + "ProjectId": "string" + } + ], + "DefaultPropertyValues": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + } + }, + "Id": "string", + "Overrides": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + } + }, + "SpaceId": "string", + "Version": 0 +} +``` +::: + +**Response** + +`200` — Returns the results of the update of the actions updated to match the action template. + +- **`Outcome`** :span[string]{.type-label} + Minimum length 1. +- **`Results`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + - **`ManualMergeRequiredReasonsByPropertyName`** :span[object]{.type-label} + - **`NamesOfNewParametersMissingDefaultValue`** :span[array of string]{.type-label} + - **`Outcome`** :span[enum]{.type-label} + Allowed values: `Success`, `ManualMergeRequired`, `DefaultParamterValueMissing`, `RemovedPackageInUse`. + - **`RemovedPackageUsages`** :span[array of object]{.type-label} +- **`TaskId`** :span[string]{.type-label} +- **`ValidationFailures`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Outcome": "string", + "Results": [ + { + "Id": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManualMergeRequiredReasonsByPropertyName": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "NamesOfNewParametersMissingDefaultValue": [ + "string" + ], + "Outcome": "Success", + "RemovedPackageUsages": [ + {} + ] + } + ], + "TaskId": "string", + "ValidationFailures": [ + "string" + ] +} +``` +::: + +## Get the logo associated with the latest version of action template + +:endpoint{method="GET" path="/api/\{spaceId\}/actiontemplates/\{id\}/logo"} + +Also reachable at `/api/actiontemplates/{id}/logo`, `/api/spaces/{spaceIdentifier}/actiontemplates/{id}/logo`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Action Type or ID of the action type logo. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Update the logo associated with the latest version of the action template + +:endpoint{method="POST" path="/api/\{spaceId\}/actiontemplates/\{id\}/logo"} + +Also reachable at `/api/actiontemplates/{id}/logo`, `/api/spaces/{spaceIdentifier}/actiontemplates/{id}/logo`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the action template for which to set the logo. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the logo was updated + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Update the logo associated with the latest version of the action template + +:endpoint{method="PUT" path="/api/\{spaceId\}/actiontemplates/\{id\}/logo"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the action template for which to set the logo. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the logo was updated + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Update the logo associated with the latest version of the action template + +:endpoint{method="PUT" path="/api/spaces/\{spaceIdentifier\}/actiontemplates/\{id\}/logo"} + +Also reachable at `/api/actiontemplates/{id}/logo`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the action template for which to set the logo. +- **`spaceIdentifier`** :span[string]{.type-label} *(required)* + Identifier (ID or slug) of the space. + +**Response** + +`200` — Confirmation that the logo was updated + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get usages for an Action Template + +:endpoint{method="GET" path="/api/\{spaceId\}/actiontemplates/\{id\}/usage"} + +Also reachable at `/api/actiontemplates/{id}/usage`, `/api/spaces/{spaceIdentifier}/actiontemplates/{id}/usage`. + +Gets a list of all steps/deployment processes that use a given action template. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the resource. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`branch`** :span[string]{.type-label} + Optionally filter usages associated with a config as code branch. +- **`process`** :span[enum]{.type-label} + Optionally filter by process type. + Allowed values: `Deployment`, `Runbook`. +- **`project`** :span[string]{.type-label} + Optionally filter version controlled usages by project. +- **`withUpdates`** :span[boolean]{.type-label} + Optionally filter for only version controlled usages with updates. + +**Response** + +`200` — The requested Action Template usages + +- **`ActionId`** :span[string]{.type-label} + Minimum length 1. +- **`ActionName`** :span[string]{.type-label} + Minimum length 1. +- **`ActionTemplateId`** :span[string]{.type-label} + Minimum length 1. +- **`Branch`** :span[string]{.type-label} +- **`DeploymentProcessId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProcessId`** :span[string]{.type-label} + Minimum length 1. +- **`ProcessType`** :span[enum]{.type-label} + Allowed values: `Deployment`, `Runbook`. +- **`ProjectId`** :span[string]{.type-label} + Minimum length 1. +- **`ProjectName`** :span[string]{.type-label} + Minimum length 1. +- **`ProjectSlug`** :span[string]{.type-label} + Minimum length 1. +- **`Release`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`RunbookName`** :span[string]{.type-label} +- **`StepId`** :span[string]{.type-label} + Minimum length 1. +- **`StepName`** :span[string]{.type-label} + Minimum length 1. +- **`Version`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "ActionId": "string", + "ActionName": "string", + "ActionTemplateId": "string", + "Branch": "string", + "DeploymentProcessId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProcessId": "string", + "ProcessType": "Deployment", + "ProjectId": "string", + "ProjectName": "string", + "ProjectSlug": "string", + "Release": "string", + "RunbookId": "string", + "RunbookName": "string", + "StepId": "string", + "StepName": "string", + "Version": "string" + } +] +``` +::: + +## Get an Action Template by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/actiontemplates/\{id\}/v1"} + +Also reachable at `/api/actiontemplates/{id}/v1`, `/api/spaces/{spaceIdentifier}/actiontemplates/{id}/v1`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the ActionTemplate to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Action Template + +- **`ActionTemplate`** :span[object]{.type-label} + - **`ActionType`** :span[string]{.type-label} + Minimum length 1. + - **`CommunityActionTemplateId`** :span[string]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`GitDependencies`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`Packages`** :span[array of object]{.type-label} + - **`Parameters`** :span[array of object]{.type-label} + - **`Properties`** :span[object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ActionTemplate": { + "ActionType": "string", + "CommunityActionTemplateId": "string", + "Description": "string", + "GitDependencies": [ + { + "DefaultBranch": "string", + "FilePathFilters": [ + "string" + ], + "GitCredentialId": "string", + "GitCredentialType": "string", + "GitHubConnectionId": "string", + "Name": "string", + "RepositoryUri": "string", + "StepPackageInputsReferenceId": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Packages": [ + { + "AcquisitionLocation": "string", + "FeedId": "string", + "Id": "string", + "Name": "string", + "PackageId": "string", + "Properties": {}, + "StepPackageInputsReferenceId": "string", + "Version": "string" + } + ], + "Parameters": [ + { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "Properties": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + }, + "SpaceId": "string", + "Version": 0 + } +} +``` +::: + +## Get all versions of an Action Template + +:endpoint{method="GET" path="/api/\{spaceId\}/actiontemplates/\{id\}/versions"} + +Also reachable at `/api/actiontemplates/{id}/versions`, `/api/spaces/{spaceIdentifier}/actiontemplates/{id}/versions`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the Action Template. +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the Space that contains the Action Template. + +**Response** + +`200` — The list of action template resources for each version. + +- **`ActionType`** :span[string]{.type-label} + Minimum length 1. +- **`CommunityActionTemplateId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GitDependencies`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitCredentialType`** :span[string]{.type-label} + Minimum length 1. + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Packages`** :span[array of object]{.type-label} + - **`AcquisitionLocation`** :span[string]{.type-label} + The package-acquisition location. One of PackageAcquisitionLocationResource or a variable-expression. + - **`FeedId`** :span[string]{.type-label} + Feed ID, name or a variable-expression. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + A name for the package-reference. This may be empty. This is used to discriminate the package-references. Package ID isn't suitable because an action may potentially have multiple references to the same package ID (e.g. if you wanted to use different versions of the same package). Also, the package ID may be a variable-expression. + - **`PackageId`** :span[string]{.type-label} + Package ID or a variable-expression. + - **`Properties`** :span[object]{.type-label} + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} + This reference identifier is populated when a step package step contains a package reference It allows us to correlate the reference within the step package inputs to this Server package reference. + - **`Version`** :span[string]{.type-label} + Specific version to use for this package. If not specified, package can be selected at release creation or runbook run time. +- **`Parameters`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Properties`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "ActionType": "string", + "CommunityActionTemplateId": "string", + "Description": "string", + "GitDependencies": [ + { + "DefaultBranch": "string", + "FilePathFilters": [ + "string" + ], + "GitCredentialId": "string", + "GitCredentialType": "string", + "GitHubConnectionId": "string", + "Name": "string", + "RepositoryUri": "string", + "StepPackageInputsReferenceId": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Packages": [ + { + "AcquisitionLocation": "string", + "FeedId": "string", + "Id": "string", + "Name": "string", + "PackageId": "string", + "Properties": {}, + "StepPackageInputsReferenceId": "string", + "Version": "string" + } + ], + "Parameters": [ + { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "Properties": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + }, + "SpaceId": "string", + "Version": 0 + } +] +``` +::: + +## Get a specific version of an Action Template + +:endpoint{method="GET" path="/api/\{spaceId\}/actiontemplates/\{id\}/versions/\{version\}"} + +Also reachable at `/api/actiontemplates/{id}/versions/{version}`, `/api/spaces/{spaceIdentifier}/actiontemplates/{id}/versions/{version}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the Action Template. +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the Space that contains the Action Template. +- **`version`** :span[string]{.type-label} *(required)* + The version number of the Action Template. + +**Response** + +`200` — The action template resource. + +- **`ActionType`** :span[string]{.type-label} + Minimum length 1. +- **`CommunityActionTemplateId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GitDependencies`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitCredentialType`** :span[string]{.type-label} + Minimum length 1. + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Packages`** :span[array of object]{.type-label} + - **`AcquisitionLocation`** :span[string]{.type-label} + The package-acquisition location. One of PackageAcquisitionLocationResource or a variable-expression. + - **`FeedId`** :span[string]{.type-label} + Feed ID, name or a variable-expression. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + A name for the package-reference. This may be empty. This is used to discriminate the package-references. Package ID isn't suitable because an action may potentially have multiple references to the same package ID (e.g. if you wanted to use different versions of the same package). Also, the package ID may be a variable-expression. + - **`PackageId`** :span[string]{.type-label} + Package ID or a variable-expression. + - **`Properties`** :span[object]{.type-label} + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} + This reference identifier is populated when a step package step contains a package reference It allows us to correlate the reference within the step package inputs to this Server package reference. + - **`Version`** :span[string]{.type-label} + Specific version to use for this package. If not specified, package can be selected at release creation or runbook run time. +- **`Parameters`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Properties`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ActionType": "string", + "CommunityActionTemplateId": "string", + "Description": "string", + "GitDependencies": [ + { + "DefaultBranch": "string", + "FilePathFilters": [ + "string" + ], + "GitCredentialId": "string", + "GitCredentialType": "string", + "GitHubConnectionId": "string", + "Name": "string", + "RepositoryUri": "string", + "StepPackageInputsReferenceId": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Packages": [ + { + "AcquisitionLocation": "string", + "FeedId": "string", + "Id": "string", + "Name": "string", + "PackageId": "string", + "Properties": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "StepPackageInputsReferenceId": "string", + "Version": "string" + } + ], + "Parameters": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "Properties": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + } + }, + "SpaceId": "string", + "Version": 0 +} +``` +::: + +## Get the logo associated with specific version of the action template + +:endpoint{method="GET" path="/api/\{spaceId\}/actiontemplates/\{typeOrId\}/versions/\{version\}/logo"} + +Also reachable at `/api/actiontemplates/{typeOrId}/versions/{version}/logo`, `/api/spaces/{spaceIdentifier}/actiontemplates/{typeOrId}/versions/{version}/logo`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`typeOrId`** :span[string]{.type-label} *(required)* + Action Type or ID of the action type logo. +- **`version`** :span[string]{.type-label} *(required)* + Version of the action type logo. + +**Response** + +`200` — OK + +:::api-example{label="Response"} +```json +"string" +``` +::: diff --git a/src/pages/docs/api/api-keys.md b/src/pages/docs/api/api-keys.md new file mode 100644 index 0000000000..0439c1cc43 --- /dev/null +++ b/src/pages/docs/api/api-keys.md @@ -0,0 +1,371 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Api Keys +--- + +## Get a list of API Keys for a User + +:endpoint{method="GET" path="/api/users/\{userId\}/apikeys"} + +Lists all API keys for a user, returning the most recent results first. + +**Path Parameters** + +- **`userId`** :span[string]{.type-label} *(required)* + ID of the User. + +**Query Parameters** + +- **`partialKeyword`** :span[string]{.type-label} + Optional case-insensitive filter on the API key purpose or hint. +- **`partialPurpose`** :span[string]{.type-label} + Optional case-insensitive filter on the API key purpose. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Success + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`AccessLevel`** :span[enum]{.type-label} + The access level this API key grants. + Allowed values: `FullAccess`, `ReadOnly`, `Custom`. + - **`ActorType`** :span[enum]{.type-label} + Allowed values: `User`, `AiAgent`. + - **`ApiKey`** :span[sensitive value]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`Expires`** :span[string]{.type-label} + Format `date-time`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsLastUsedTimestampKnown`** :span[boolean]{.type-label} + Whether the API key's last-used time is being tracked. False for keys that predate last-used tracking, whose usage history is unknown. When true, a null LastUsedTimeStamp means the key has never been used. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastUsedTimeStamp`** :span[string]{.type-label} + The date and time (UTC) the API key was last used to authenticate; null if it has never been used. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Purpose`** :span[string]{.type-label} + - **`UserId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "AccessLevel": "FullAccess", + "ActorType": "User", + "ApiKey": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Created": "2020-01-01T00:00:00.000Z", + "Expires": "2020-01-01T00:00:00.000Z", + "Id": "string", + "IsLastUsedTimestampKnown": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUsedTimeStamp": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Purpose": "string", + "UserId": "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 +} +``` +::: + +## Generate a new API key for a User + +:endpoint{method="POST" path="/api/users/\{userId\}/apikeys"} + +The API Key returned in the result must be saved by the caller, as it cannot be retrieved subsequently from the Octopus server + +**Path Parameters** + +- **`userId`** :span[string]{.type-label} *(required)* + ID of the user. + +**Request Body** + +- **`ActorType`** :span[enum]{.type-label} + The kind of actor that will hold this API key. Defaults to User when omitted. + Allowed values: `User`, `AiAgent`. +- **`Expires`** :span[string]{.type-label} + The date after which the API key ceases to be usable. Provide a null value to create an API key with the maximum allowable expiry. If unspecified, will use the system default which is 180 days unless otherwise configured. Format `date-time`. +- **`Purpose`** :span[string]{.type-label} + Informational text specifying the intended usage of the api key. +- **`UserId`** :span[string]{.type-label} *(required)* + ID of the user. + +:::api-example{label="Request"} +```json +{ + "ActorType": "User", + "Expires": "2020-01-01T00:00:00.000Z", + "Purpose": "string", + "UserId": "string" +} +``` +::: + +**Response** + +`200` — The created API Key, containing the unencrypted value of the key which must be saved by the caller, as it cannot be retrieved subsequently from the Octopus server. + +- **`ActorType`** :span[enum]{.type-label} + Allowed values: `User`, `AiAgent`. +- **`ApiKey`** :span[string]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`Expires`** :span[string]{.type-label} + Format `date-time`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsLastUsedTimestampKnown`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastUsedTimeStamp`** :span[string]{.type-label} + Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Purpose`** :span[string]{.type-label} +- **`UserId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ActorType": "User", + "ApiKey": "string", + "Created": "2020-01-01T00:00:00.000Z", + "Expires": "2020-01-01T00:00:00.000Z", + "Id": "string", + "IsLastUsedTimestampKnown": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUsedTimeStamp": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Purpose": "string", + "UserId": "string" +} +``` +::: + +## Get a list of API Keys for a User + +:endpoint{method="GET" path="/api/users/\{userId\}/apikeys/v1"} + +Lists all API keys for a user, returning the most recent results first. + +**Path Parameters** + +- **`userId`** :span[string]{.type-label} *(required)* + ID of the User. + +**Query Parameters** + +- **`partialKeyword`** :span[string]{.type-label} + Optional case-insensitive filter on the API key purpose or hint. +- **`partialPurpose`** :span[string]{.type-label} + Optional case-insensitive filter on the API key purpose. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Success + +- **`ApiKeys`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`ItemType`** :span[string]{.type-label} + - **`Items`** :span[array of object]{.type-label} + - **`ItemsPerPage`** :span[integer]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastPageNumber`** :span[integer]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`NumberOfPages`** :span[integer]{.type-label} + - **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ApiKeys": { + "Id": "string", + "ItemType": "string", + "Items": [ + { + "AccessLevel": "FullAccess", + "ActorType": "User", + "ApiKey": {}, + "Created": "2020-01-01T00:00:00.000Z", + "Expires": "2020-01-01T00:00:00.000Z", + "Id": "string", + "IsLastUsedTimestampKnown": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUsedTimeStamp": "2020-01-01T00:00:00.000Z", + "Links": {}, + "Purpose": "string", + "UserId": "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 + } +} +``` +::: + +## Get an API Key by ID + +:endpoint{method="GET" path="/api/users/\{userId\}/apikeys/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the ApiKeyResource to load. +- **`userId`** :span[string]{.type-label} *(required)* + ID of the User that owns the ApiKey. + +**Response** + +`200` — The requested API Key + +- **`AccessLevel`** :span[enum]{.type-label} + The access level this API key grants. + Allowed values: `FullAccess`, `ReadOnly`, `Custom`. +- **`ActorType`** :span[enum]{.type-label} + Allowed values: `User`, `AiAgent`. +- **`ApiKey`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`Expires`** :span[string]{.type-label} + Format `date-time`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsLastUsedTimestampKnown`** :span[boolean]{.type-label} + Whether the API key's last-used time is being tracked. False for keys that predate last-used tracking, whose usage history is unknown. When true, a null LastUsedTimeStamp means the key has never been used. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastUsedTimeStamp`** :span[string]{.type-label} + The date and time (UTC) the API key was last used to authenticate; null if it has never been used. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Purpose`** :span[string]{.type-label} +- **`UserId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AccessLevel": "FullAccess", + "ActorType": "User", + "ApiKey": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Created": "2020-01-01T00:00:00.000Z", + "Expires": "2020-01-01T00:00:00.000Z", + "Id": "string", + "IsLastUsedTimestampKnown": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUsedTimeStamp": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Purpose": "string", + "UserId": "string" +} +``` +::: + +## Revoke an API Key + +:endpoint{method="DELETE" path="/api/users/\{userId\}/apikeys/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the ApiKey to delete. +- **`userId`** :span[string]{.type-label} *(required)* + Id of the User that owns the ApiKey to delete. + +**Response** + +`200` — Confirmation that a User API Key has been deleted + +:::api-example{label="Response"} +```json +{} +``` +::: diff --git a/src/pages/docs/api/artifacts.md b/src/pages/docs/api/artifacts.md new file mode 100644 index 0000000000..aae3250ea8 --- /dev/null +++ b/src/pages/docs/api/artifacts.md @@ -0,0 +1,365 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Artifacts +--- + +## List all of the artifacts in the supplied Octopus Deploy Space, from all releases. The results will be sorted by date from most recently to least recently created + +:endpoint{method="GET" path="/api/\{spaceId\}/artifacts"} + +Also reachable at `/api/artifacts`, `/api/spaces/{spaceIdentifier}/artifacts`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + List of Artifact IDs which if specified, filters the result to only include Artifacts with matching IDs. +- **`order`** :span[string]{.type-label} + asc or desc. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`regarding`** :span[string]{.type-label} + An ID of a resource to filter on. Only artifacts related to this resource will be returned. It can be the ID of the following: Release, RunbookSnapshot, Deployment, Runbook Run, Server Task, Project, Environment or Tenant. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — A paginated list of Artifacts + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Created`** :span[string]{.type-label} + Gets or sets the time at which the artifact was created. Format `date-time`. + - **`Filename`** :span[string]{.type-label} + Gets or sets the filename of the Artifact to create. Minimum length 1. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`LogCorrelationId`** :span[string]{.type-label} + Gets the correlationId of the log block in which the artifact was captured. + - **`ServerTaskId`** :span[string]{.type-label} + Gets or sets the server task with which this artifact is associated. + - **`Source`** :span[string]{.type-label} + Gets or sets a short summary of the source of this attachment. This will typically be the name of a step/machine, or "Uploaded by [username]" if the attachment was uploaded by a person. + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Created": "2020-01-01T00:00:00.000Z", + "Filename": "Performance Test Results.csv", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "LogCorrelationId": "string", + "ServerTaskId": "string", + "Source": "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 +} +``` +::: + +## Create a new artifact + +:endpoint{method="POST" path="/api/\{spaceId\}/artifacts"} + +Also reachable at `/api/artifacts`, `/api/spaces/{spaceIdentifier}/artifacts`. + +Creates a new artifact. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the space. + +**Request Body** + +- **`Filename`** :span[string]{.type-label} *(required)* + The filename of the Artifact to create. Minimum length 1. +- **`LogCorrelationId`** :span[string]{.type-label} + Gets the correlationId of the log block in which the artifact was captured. +- **`ServerTaskId`** :span[string]{.type-label} *(required)* + The server task with which this artifact is associated. +- **`Source`** :span[string]{.type-label} + A short summary of the source of this attachment. This will typically be the name of a step/machine, or "Uploaded by [username]" if the attachment was uploaded by a person. +- **`SpaceId`** :span[string]{.type-label} *(required)* + ID of the space. + +:::api-example{label="Request"} +```json +{ + "Filename": "Performance Test Results.csv", + "LogCorrelationId": "string", + "ServerTaskId": "string", + "Source": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Created`** :span[string]{.type-label} + Gets or sets the time at which the artifact was created. Format `date-time`. +- **`Filename`** :span[string]{.type-label} + Gets or sets the filename of the Artifact to create. Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`LogCorrelationId`** :span[string]{.type-label} + Gets the correlationId of the log block in which the artifact was captured. +- **`ServerTaskId`** :span[string]{.type-label} + Gets or sets the server task with which this artifact is associated. +- **`Source`** :span[string]{.type-label} + Gets or sets a short summary of the source of this attachment. This will typically be the name of a step/machine, or "Uploaded by [username]" if the attachment was uploaded by a person. +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Created": "2020-01-01T00:00:00.000Z", + "Filename": "Performance Test Results.csv", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "LogCorrelationId": "string", + "ServerTaskId": "string", + "Source": "string", + "SpaceId": "string" +} +``` +::: + +## Get an Artifact by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/artifacts/\{id\}"} + +Also reachable at `/api/artifacts/{id}`, `/api/spaces/{spaceIdentifier}/artifacts/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Artifact to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Gets a specific Artifact + +- **`Created`** :span[string]{.type-label} + Gets or sets the time at which the artifact was created. Format `date-time`. +- **`Filename`** :span[string]{.type-label} + Gets or sets the filename of the Artifact to create. Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`LogCorrelationId`** :span[string]{.type-label} + Gets the correlationId of the log block in which the artifact was captured. +- **`ServerTaskId`** :span[string]{.type-label} + Gets or sets the server task with which this artifact is associated. +- **`Source`** :span[string]{.type-label} + Gets or sets a short summary of the source of this attachment. This will typically be the name of a step/machine, or "Uploaded by [username]" if the attachment was uploaded by a person. +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Created": "2020-01-01T00:00:00.000Z", + "Filename": "Performance Test Results.csv", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "LogCorrelationId": "string", + "ServerTaskId": "string", + "Source": "string", + "SpaceId": "string" +} +``` +::: + +## Modify an existing artifact + +:endpoint{method="PUT" path="/api/\{spaceId\}/artifacts/\{id\}"} + +Also reachable at `/api/artifacts/{id}`, `/api/spaces/{spaceIdentifier}/artifacts/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the artifact. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space. + +**Response** + +`200` — Artifacts are files like documents and test results that may be stored alongside a release. + +- **`Created`** :span[string]{.type-label} + Gets or sets the time at which the artifact was created. Format `date-time`. +- **`Filename`** :span[string]{.type-label} + Gets or sets the filename of the Artifact to create. Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`LogCorrelationId`** :span[string]{.type-label} + Gets the correlationId of the log block in which the artifact was captured. +- **`ServerTaskId`** :span[string]{.type-label} + Gets or sets the server task with which this artifact is associated. +- **`Source`** :span[string]{.type-label} + Gets or sets a short summary of the source of this attachment. This will typically be the name of a step/machine, or "Uploaded by [username]" if the attachment was uploaded by a person. +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Created": "2020-01-01T00:00:00.000Z", + "Filename": "Performance Test Results.csv", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "LogCorrelationId": "string", + "ServerTaskId": "string", + "Source": "string", + "SpaceId": "string" +} +``` +::: + +## Delete an existing Artifact + +:endpoint{method="DELETE" path="/api/\{spaceId\}/artifacts/\{id\}"} + +Also reachable at `/api/artifacts/{id}`, `/api/spaces/{spaceIdentifier}/artifacts/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Artifact to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Get the content associated with an artifact + +:endpoint{method="GET" path="/api/\{spaceId\}/artifacts/\{id\}/content"} + +Also reachable at `/api/artifacts/{id}/content`, `/api/spaces/{spaceIdentifier}/artifacts/{id}/content`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the artifact. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space. + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## PUT /api/{spaceId}/artifacts/{id}/content + +:endpoint{method="PUT" path="/api/\{spaceId\}/artifacts/\{id\}/content"} + +Also reachable at `/api/artifacts/{id}/content`, `/api/spaces/{spaceIdentifier}/artifacts/{id}/content`. + +Sets the content associated with an artifact. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the artifact. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`204` — The content was successfully uploaded. diff --git a/src/pages/docs/api/audit-stream.md b/src/pages/docs/api/audit-stream.md new file mode 100644 index 0000000000..3ec051969e --- /dev/null +++ b/src/pages/docs/api/audit-stream.md @@ -0,0 +1,98 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Audit Stream +--- + +## Get the audit stream configuration + +:endpoint{method="GET" path="/api/audit-stream"} + +**Response** + +`200` — The Audit Stream configuration + +- **`Active`** :span[boolean]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StreamConfigurationResource`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Active": true, + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "StreamConfigurationResource": {} +} +``` +::: + +## Modify the audit stream configuration + +:endpoint{method="PUT" path="/api/audit-stream"} + +**Request Body** + +- **`Active`** :span[boolean]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`StreamConfigurationResource`** :span[object]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Active": true, + "Description": "string", + "StreamConfigurationResource": {} +} +``` +::: + +**Response** + +`200` — The modified Audit Stream configuration + +- **`Active`** :span[boolean]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StreamConfigurationResource`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Active": true, + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "StreamConfigurationResource": {} +} +``` +::: diff --git a/src/pages/docs/api/authentication.md b/src/pages/docs/api/authentication.md new file mode 100644 index 0000000000..7270215cdf --- /dev/null +++ b/src/pages/docs/api/authentication.md @@ -0,0 +1,131 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Authentication +--- + +## Get authentication providers + +:endpoint{method="GET" path="/api/authentication"} + +Provides the details of the enabled authentication providers. + +**Response** + +`200` — The requested Authentication Information + +- **`AnyAuthenticationProvidersSupportPasswordManagement`** :span[boolean]{.type-label} +- **`ApiKeyDefaultExpiryDays`** :span[integer]{.type-label} +- **`ApiKeyMaxExpiryDays`** :span[integer]{.type-label} +- **`AuthenticationProviders`** :span[array of object]{.type-label} + - **`CSSLinks`** :span[array of string]{.type-label} + - **`DisplayName`** :span[string]{.type-label} + - **`FormsLoginEnabled`** :span[boolean]{.type-label} + - **`IdentityType`** :span[enum]{.type-label} + Allowed values: `Guest`, `UsernamePassword`, `ActiveDirectory`, `OAuth`. + - **`JavascriptLinks`** :span[array of string]{.type-label} + - **`Links`** :span[object]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`AutoLoginEnabled`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`OctopusIdDynamicRegistrationPending`** :span[boolean]{.type-label} +- **`RememberMeEnabled`** :span[boolean]{.type-label} +- **`UserApiKeysEnabled`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AnyAuthenticationProvidersSupportPasswordManagement": true, + "ApiKeyDefaultExpiryDays": 0, + "ApiKeyMaxExpiryDays": 0, + "AuthenticationProviders": [ + { + "CSSLinks": [ + "string" + ], + "DisplayName": "string", + "FormsLoginEnabled": true, + "IdentityType": "Guest", + "JavascriptLinks": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } + ], + "AutoLoginEnabled": true, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "OctopusIdDynamicRegistrationPending": true, + "RememberMeEnabled": true, + "UserApiKeysEnabled": true +} +``` +::: + +## Determine whether an external server (.e.g Okta) has initiated login from a URL query string and, if so, get the provider's name + +:endpoint{method="POST" path="/api/authentication/checklogininitiated"} + +**Request Body** + +- **`EncodedQueryString`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "EncodedQueryString": "string" +} +``` +::: + +**Response** + +`200` — Whether the external server has initiated login and if so the provider's name + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProviderName`** :span[string]{.type-label} +- **`WasLoginInitiated`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProviderName": "string", + "WasLoginInitiated": true +} +``` +::: diff --git a/src/pages/docs/api/azure-dev-ops.md b/src/pages/docs/api/azure-dev-ops.md new file mode 100644 index 0000000000..1ad9f51a8d --- /dev/null +++ b/src/pages/docs/api/azure-dev-ops.md @@ -0,0 +1,14 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Azure Dev Ops +--- + +## POST /api/azuredevopsissuetracker/connectivitycheck + +:endpoint{method="POST" path="/api/azuredevopsissuetracker/connectivitycheck"} + +**Response** + +`200` — OK diff --git a/src/pages/docs/api/branches.md b/src/pages/docs/api/branches.md new file mode 100644 index 0000000000..72cccca09f --- /dev/null +++ b/src/pages/docs/api/branches.md @@ -0,0 +1,456 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Branches +--- + +## Request the list of Branches for a given Project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/git/branches"} + +Also reachable at `/api/projects/{projectId}/git/branches`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/branches`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`searchByName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested list of Branches + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`CanonicalName`** :span[string]{.type-label} + Minimum length 1. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsProtected`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "CanonicalName": "string", + "Id": "string", + "IsProtected": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "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 +} +``` +::: + +## Create a branch given a project, the base git ref, and the new branch's name + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/git/branches/v2"} + +Also reachable at `/api/projects/{projectId}/git/branches/v2`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/branches/v2`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`BaseGitRef`** :span[string]{.type-label} *(required)* +- **`NewBranchName`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "BaseGitRef": "string", + "NewBranchName": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — The newly-created Branch + +- **`CanonicalName`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsProtected`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "CanonicalName": "string", + "Id": "string", + "IsProtected": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" +} +``` +::: + +## Get a Git branch by name + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/git/branches/\{branchName\}"} + +Also reachable at `/api/projects/{projectId}/git/branches/{branchName}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/branches/{branchName}`. + +Gets a named version control branch for a project. + +**Path Parameters** + +- **`branchName`** :span[string]{.type-label} *(required)* + Name of the branch. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Branch + +- **`CanonicalName`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsProtected`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "CanonicalName": "string", + "Id": "string", + "IsProtected": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" +} +``` +::: + +## Get a Git commit by hash + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/git/commits/\{hash\}"} + +Also reachable at `/api/projects/{projectId}/git/commits/{hash}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/commits/{hash}`. + +Gets a git commit for a project. + +**Path Parameters** + +- **`hash`** :span[string]{.type-label} *(required)* + Hash of the commit. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Commit + +- **`CanonicalName`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "CanonicalName": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" +} +``` +::: + +## Get a Git named reference by name + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/git/refs/\{refName\}"} + +Also reachable at `/api/projects/{projectId}/git/refs/{refName}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/refs/{refName}`. + +Gets a named version control reference for a project. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the project. +- **`refName`** :span[string]{.type-label} *(required)* + Name of the git reference. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Named Git Reference + +- **`CanonicalName`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsProtected`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "CanonicalName": "string", + "Id": "string", + "IsProtected": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" +} +``` +::: + +## Request a list of Git Tags for the project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/git/tags"} + +Also reachable at `/api/projects/{projectId}/git/tags`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/tags`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`searchByName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested Git Tags + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`CanonicalName`** :span[string]{.type-label} + Minimum length 1. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "CanonicalName": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "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 +} +``` +::: + +## Get an individual Git Tag; searching for it by Name + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/git/tags/\{tagName\}"} + +Also reachable at `/api/projects/{projectId}/git/tags/{tagName}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/tags/{tagName}`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`tagName`** :span[string]{.type-label} *(required)* + Name of the tag. + +**Response** + +`200` — The requested Tag + +- **`CanonicalName`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "CanonicalName": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" +} +``` +::: diff --git a/src/pages/docs/api/build-information.md b/src/pages/docs/api/build-information.md new file mode 100644 index 0000000000..5e31cd7c4a --- /dev/null +++ b/src/pages/docs/api/build-information.md @@ -0,0 +1,405 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Build Information +--- + +## Retrieve a list of build information records describing the vcs information for a given package + +:endpoint{method="GET" path="/api/\{spaceId\}/build-information"} + +Also reachable at `/api/build-information`, `/api/spaces/{spaceIdentifier}/build-information`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`filter`** :span[string]{.type-label} + A version to look for. +- **`includeWorkItems`** :span[boolean]{.type-label} +- **`latest`** :span[boolean]{.type-label} + If true, returns only the latest build information. +- **`packageId`** :span[string]{.type-label} + An exact package to look for. +- **`partialPackageId`** :span[string]{.type-label} + A partial package ID used for a sub-string search. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested list of Build Information + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Branch`** :span[string]{.type-label} + - **`BuildEnvironment`** :span[string]{.type-label} + - **`BuildNumber`** :span[string]{.type-label} + - **`BuildUrl`** :span[string]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IncompleteDataWarning`** :span[string]{.type-label} + - **`IssueTrackerName`** :span[string]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`PackageId`** :span[string]{.type-label} + - **`VcsCommitNumber`** :span[string]{.type-label} + - **`VcsCommitUrl`** :span[string]{.type-label} + - **`VcsRoot`** :span[string]{.type-label} + - **`VcsType`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + {} + ], + "Created": "2020-01-01T00:00:00.000Z", + "Id": "string", + "IncompleteDataWarning": "string", + "IssueTrackerName": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create or update a specific build information record describing the vcs information for a given package + +:endpoint{method="POST" path="/api/\{spaceId\}/build-information"} + +Also reachable at `/api/build-information`, `/api/spaces/{spaceIdentifier}/build-information`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`OctopusBuildInformation`** :span[object]{.type-label} *(required)* + - **`Branch`** :span[string]{.type-label} + - **`BuildEnvironment`** :span[string]{.type-label} + - **`BuildNumber`** :span[string]{.type-label} + - **`BuildUrl`** :span[string]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + - **`VcsCommitNumber`** :span[string]{.type-label} + - **`VcsRoot`** :span[string]{.type-label} + - **`VcsType`** :span[string]{.type-label} +- **`OverwriteMode`** :span[enum]{.type-label} + Allowed values: `FailIfExists`, `OverwriteExisting`, `IgnoreIfExists`. +- **`PackageId`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Replace`** :span[boolean]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`Version`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "OctopusBuildInformation": { + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + { + "Comment": "string", + "Id": "string" + } + ], + "VcsCommitNumber": "string", + "VcsRoot": "string", + "VcsType": "string" + }, + "OverwriteMode": "FailIfExists", + "PackageId": "string", + "Replace": true, + "SpaceId": "string", + "Version": "string" +} +``` +::: + +**Response** + +`200` — Build information updated. + +- **`Branch`** :span[string]{.type-label} +- **`BuildEnvironment`** :span[string]{.type-label} +- **`BuildNumber`** :span[string]{.type-label} +- **`BuildUrl`** :span[string]{.type-label} +- **`Commits`** :span[array of object]{.type-label} + - **`Comment`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`LinkUrl`** :span[string]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IncompleteDataWarning`** :span[string]{.type-label} +- **`IssueTrackerName`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`PackageId`** :span[string]{.type-label} +- **`VcsCommitNumber`** :span[string]{.type-label} +- **`VcsCommitUrl`** :span[string]{.type-label} +- **`VcsRoot`** :span[string]{.type-label} +- **`VcsType`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} +- **`WorkItems`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`LinkUrl`** :span[string]{.type-label} + - **`Source`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + { + "Comment": "string", + "Id": "string", + "LinkUrl": "string" + } + ], + "Created": "2020-01-01T00:00:00.000Z", + "Id": "string", + "IncompleteDataWarning": "string", + "IssueTrackerName": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + { + "Description": "string", + "Id": "string", + "LinkUrl": "string", + "Source": "string" + } + ] +} +``` +::: + +## Bulk delete specific Build Information records + +:endpoint{method="DELETE" path="/api/\{spaceId\}/build-information/bulk"} + +Also reachable at `/api/build-information/bulk`, `/api/spaces/{spaceIdentifier}/build-information/bulk`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Ids`** :span[array of string]{.type-label} *(required)* + IDs of the multiple Build Information to delete. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Ids": [ + "string" + ], + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Success + +## Retrieve a specific build information record describing the vcs information for a given package + +:endpoint{method="GET" path="/api/\{spaceId\}/build-information/\{id\}"} + +Also reachable at `/api/build-information/{id}`, `/api/spaces/{spaceIdentifier}/build-information/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The build information id to retrieve. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Build Information + +- **`Branch`** :span[string]{.type-label} +- **`BuildEnvironment`** :span[string]{.type-label} +- **`BuildNumber`** :span[string]{.type-label} +- **`BuildUrl`** :span[string]{.type-label} +- **`Commits`** :span[array of object]{.type-label} + - **`Comment`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`LinkUrl`** :span[string]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IncompleteDataWarning`** :span[string]{.type-label} +- **`IssueTrackerName`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`PackageId`** :span[string]{.type-label} +- **`VcsCommitNumber`** :span[string]{.type-label} +- **`VcsCommitUrl`** :span[string]{.type-label} +- **`VcsRoot`** :span[string]{.type-label} +- **`VcsType`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} +- **`WorkItems`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`LinkUrl`** :span[string]{.type-label} + - **`Source`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + { + "Comment": "string", + "Id": "string", + "LinkUrl": "string" + } + ], + "Created": "2020-01-01T00:00:00.000Z", + "Id": "string", + "IncompleteDataWarning": "string", + "IssueTrackerName": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + { + "Description": "string", + "Id": "string", + "LinkUrl": "string", + "Source": "string" + } + ] +} +``` +::: + +## Delete a specific Build Information record + +:endpoint{method="DELETE" path="/api/\{spaceId\}/build-information/\{id\}"} + +Also reachable at `/api/build-information/{id}`, `/api/spaces/{spaceIdentifier}/build-information/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Build Information to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success diff --git a/src/pages/docs/api/capabilities.md b/src/pages/docs/api/capabilities.md new file mode 100644 index 0000000000..2ade71b3e2 --- /dev/null +++ b/src/pages/docs/api/capabilities.md @@ -0,0 +1,51 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Capabilities +--- + +## Ask the server to return a list of all the Capabilities (Commands and Requests) it supports + +:endpoint{method="GET" path="/api/capabilities"} + +**Response** + +`200` — The requested list of Capabilities + +- **`Capabilities`** :span[array of string]{.type-label} + list of supported Commands and Requests that this server has. + +:::api-example{label="Response"} +```json +{ + "Capabilities": [ + "string" + ] +} +``` +::: + +## Ask the server if a single capability exists or not. If the Capability exists, an HTTP 200 (OK) will be returned. If not, a 404 (Not Found) will be returned + +:endpoint{method="GET" path="/api/capabilities/\{capability\}"} + +**Path Parameters** + +- **`capability`** :span[string]{.type-label} *(required)* + The capability you want to query for. Name matching is case insensitive but otherwise must be a full string match. + +**Response** + +`200` — Indicates that the Capability exists + +- **`Exists`** :span[boolean]{.type-label} + If true, the server has this capability and you can use it. If not, the capability is not available on this server. + +:::api-example{label="Response"} +```json +{ + "Exists": true +} +``` +::: diff --git a/src/pages/docs/api/certificates.md b/src/pages/docs/api/certificates.md new file mode 100644 index 0000000000..9aff95e2c4 --- /dev/null +++ b/src/pages/docs/api/certificates.md @@ -0,0 +1,2163 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Certificates +--- + +## List X.509 certificates managed by Octopus + +:endpoint{method="GET" path="/api/\{spaceId\}/certificates"} + +Also reachable at `/api/certificates`, `/api/spaces/{spaceIdentifier}/certificates`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`archived`** :span[boolean]{.type-label} + If true, returns only archived Certificates. Otherwise, returns only non-archived Certificates. +- **`firstResult`** :span[string]{.type-label} + Certificate ID which if specified, adds the Certificate with matching ID to the result if it is not already included. +- **`ids`** :span[string]{.type-label} + Comma delimited list of Certificate IDs which if specified, filters the result to only include Certificates with matching IDs. +- **`orderBy`** :span[string]{.type-label} + If the value is 'recent' (case-insensitive), then the result will be sorted by Created instead of NotAfter. +- **`partialName`** :span[string]{.type-label} + Alternative parameter to Search; filters Certificates by Name/Subject/Thumbprint. +- **`search`** :span[string]{.type-label} + Filters Certificates by Name/Subject/Thumbprint. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 15. Minimum `0`. +- **`tenant`** :span[string]{.type-label} + Tenant ID which if specified, filters the result to only include Certificates which are related to the provided Tenant. + +**Response** + +`200` — The requested Certificates + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Archived`** :span[string]{.type-label} + Format `date-time`. + - **`CertificateChain`** :span[array of object]{.type-label} + - **`CertificateData`** :span[sensitive value]{.type-label} + - **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. + - **`EnvironmentIds`** :span[array of string]{.type-label} + - **`HasPrivateKey`** :span[boolean]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsExpired`** :span[boolean]{.type-label} + - **`IssuerCommonName`** :span[string]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`IssuerOrganization`** :span[string]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`Notes`** :span[string]{.type-label} + - **`Password`** :span[sensitive value]{.type-label} + - **`ReplacedBy`** :span[string]{.type-label} + - **`SelfSigned`** :span[boolean]{.type-label} + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`SubjectAlternativeNames`** :span[array of string]{.type-label} + - **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. + - **`TenantIds`** :span[array of string]{.type-label} + - **`TenantTags`** :span[array of string]{.type-label} + - **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + {} + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "EnvironmentIds": [ + "string" + ], + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SpaceId": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Version": 0 + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new certificate + +:endpoint{method="POST" path="/api/\{spaceId\}/certificates"} + +Also reachable at `/api/certificates`, `/api/spaces/{spaceIdentifier}/certificates`. + +Adds a new certificate + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`CertificateData`** :span[sensitive value]{.type-label} *(required)* + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Notes`** :span[string]{.type-label} + Maximum length 10240. +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + +:::api-example{label="Request"} +```json +{ + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "EnvironmentIds": [ + "string" + ], + "Name": "string", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted" +} +``` +::: + +**Response** + +`201` — Created + +- **`Archived`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateChain`** :span[array of object]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`CertificateData`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`HasPrivateKey`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsExpired`** :span[boolean]{.type-label} +- **`IssuerCommonName`** :span[string]{.type-label} +- **`IssuerDistinguishedName`** :span[string]{.type-label} +- **`IssuerOrganization`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`NotAfter`** :span[string]{.type-label} + Format `date-time`. +- **`NotBefore`** :span[string]{.type-label} + Format `date-time`. +- **`Notes`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`ReplacedBy`** :span[string]{.type-label} +- **`SelfSigned`** :span[boolean]{.type-label} +- **`SerialNumber`** :span[string]{.type-label} +- **`SignatureAlgorithmName`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SubjectAlternativeNames`** :span[array of string]{.type-label} +- **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`SubjectDistinguishedName`** :span[string]{.type-label} +- **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Thumbprint`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + { + "IssuerDistinguishedName": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SubjectDistinguishedName": "string", + "Thumbprint": "string", + "Version": 0 + } + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "EnvironmentIds": [ + "string" + ], + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SpaceId": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Version": 0 +} +``` +::: + +## Get a list of Certificates + +:endpoint{method="GET" path="/api/\{spaceId\}/certificates/all"} + +Also reachable at `/api/certificates/all`, `/api/spaces/{spaceIdentifier}/certificates/all`. + +Lists X.509 certificates managed by Octopus. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + A set of Certificate IDs to retrieve Certificates for. Example: Certificate-101,Certificate-201. + +**Response** + +`200` — The list of requested Certificates + +- **`Archived`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateChain`** :span[array of object]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`CertificateData`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`HasPrivateKey`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsExpired`** :span[boolean]{.type-label} +- **`IssuerCommonName`** :span[string]{.type-label} +- **`IssuerDistinguishedName`** :span[string]{.type-label} +- **`IssuerOrganization`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`NotAfter`** :span[string]{.type-label} + Format `date-time`. +- **`NotBefore`** :span[string]{.type-label} + Format `date-time`. +- **`Notes`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`ReplacedBy`** :span[string]{.type-label} +- **`SelfSigned`** :span[boolean]{.type-label} +- **`SerialNumber`** :span[string]{.type-label} +- **`SignatureAlgorithmName`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SubjectAlternativeNames`** :span[array of string]{.type-label} +- **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`SubjectDistinguishedName`** :span[string]{.type-label} +- **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Thumbprint`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + { + "IssuerDistinguishedName": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SubjectDistinguishedName": "string", + "Thumbprint": "string", + "Version": 0 + } + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "EnvironmentIds": [ + "string" + ], + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SpaceId": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Version": 0 + } +] +``` +::: + +## Get the global Certificate + +:endpoint{method="GET" path="/api/certificates/certificate-global"} + +Returns the server thumbprint used to identify this Octopus Server to any Tentacles when executing a deployment. Deprecated. + +**Response** + +`200` — The requested global Certificate + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`SignatureAlgorithm`** :span[string]{.type-label} +- **`Thumbprint`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SignatureAlgorithm": "string", + "Thumbprint": "string" +} +``` +::: + +## Create a self-signed Certificate + +:endpoint{method="POST" path="/api/\{spaceId\}/certificates/generate"} + +Also reachable at `/api/certificates/generate`, `/api/spaces/{spaceIdentifier}/certificates/generate`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Archived`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateChain`** :span[array of object]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`CertificateData`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`HasPrivateKey`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsExpired`** :span[boolean]{.type-label} +- **`IssuerCommonName`** :span[string]{.type-label} +- **`IssuerDistinguishedName`** :span[string]{.type-label} +- **`IssuerOrganization`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`NotAfter`** :span[string]{.type-label} + Format `date-time`. +- **`NotBefore`** :span[string]{.type-label} + Format `date-time`. +- **`Notes`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`ReplacedBy`** :span[string]{.type-label} +- **`SelfSigned`** :span[boolean]{.type-label} +- **`SelfSignedCertificateCurve`** :span[string]{.type-label} + Elliptic curve for the generated key pair: nistP256, nistP384 or nistP521. Defaults to nistP384 when omitted. +- **`SerialNumber`** :span[string]{.type-label} +- **`SignatureAlgorithmName`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SubjectAlternativeNames`** :span[array of string]{.type-label} +- **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`SubjectDistinguishedName`** :span[string]{.type-label} +- **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Thumbprint`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + { + "IssuerDistinguishedName": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SubjectDistinguishedName": "string", + "Thumbprint": "string", + "Version": 0 + } + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "EnvironmentIds": [ + "string" + ], + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SelfSignedCertificateCurve": "string", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SpaceId": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Version": 0 +} +``` +::: + +**Response** + +`200` — The newly-created self-signed Certificate. + +- **`Archived`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateChain`** :span[array of object]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`CertificateData`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`HasPrivateKey`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsExpired`** :span[boolean]{.type-label} +- **`IssuerCommonName`** :span[string]{.type-label} +- **`IssuerDistinguishedName`** :span[string]{.type-label} +- **`IssuerOrganization`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`NotAfter`** :span[string]{.type-label} + Format `date-time`. +- **`NotBefore`** :span[string]{.type-label} + Format `date-time`. +- **`Notes`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`ReplacedBy`** :span[string]{.type-label} +- **`SelfSigned`** :span[boolean]{.type-label} +- **`SerialNumber`** :span[string]{.type-label} +- **`SignatureAlgorithmName`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SubjectAlternativeNames`** :span[array of string]{.type-label} +- **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`SubjectDistinguishedName`** :span[string]{.type-label} +- **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Thumbprint`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + { + "IssuerDistinguishedName": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SubjectDistinguishedName": "string", + "Thumbprint": "string", + "Version": 0 + } + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "EnvironmentIds": [ + "string" + ], + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SpaceId": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Version": 0 +} +``` +::: + +## List the X.509 certificates in the supplied Octopus Deploy Space in pages. Current certificates are sorted by soonest expiry first unless OrderBy says otherwise; archived certificates are always sorted by most recently archived + +:endpoint{method="GET" path="/api/\{spaceId\}/certificates/v2"} + +Also reachable at `/api/certificates/v2`, `/api/spaces/{spaceIdentifier}/certificates/v2`. + +Skip and Take are required. TotalResults is always the real count of matching certificates, including when Tenant or FirstResult is supplied. Certificate data and passwords are never returned by this endpoint. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`archived`** :span[boolean]{.type-label} + When true, returns only archived certificates. Otherwise, returns only current (non-archived) certificates. +- **`firstResult`** :span[string]{.type-label} + A certificate to return at the top of the first page even if it does not match the other filters, or is archived. Intended for a selector that has to show the currently selected certificate whatever else it lists. +- **`ids`** :span[array of string]{.type-label} + Filters the certificates using the specified ids. +- **`orderBy`** :span[string]{.type-label} + The order to return current certificates in: Expiry (the default, soonest to expire first) or Created (most recently added first). Ignored when Archived is true, since archived certificates are always returned most recently archived first. An unrecognised value is treated as Expiry. +- **`search`** :span[string]{.type-label} + Filters the certificates using the specified fragment, matched against each certificate's name, subject and thumbprint. +- **`skip`** :span[integer]{.type-label} *(required)* + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} *(required)* + Number of items to take. Defaults to 30. Minimum `0`. +- **`tenant`** :span[string]{.type-label} + Filters the certificates to those the specified Tenant can use, honouring both direct tenant links and tenant tags. + +**Response** + +`200` — Success + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Archived`** :span[string]{.type-label} + Format `date-time`. + - **`CertificateChain`** :span[array of object]{.type-label} + - **`CertificateData`** :span[sensitive value]{.type-label} + - **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. + - **`EnvironmentIds`** :span[array of string]{.type-label} + - **`HasPrivateKey`** :span[boolean]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsExpired`** :span[boolean]{.type-label} + - **`IssuerCommonName`** :span[string]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`IssuerOrganization`** :span[string]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`Notes`** :span[string]{.type-label} + - **`Password`** :span[sensitive value]{.type-label} + - **`ReplacedBy`** :span[string]{.type-label} + - **`SelfSigned`** :span[boolean]{.type-label} + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`SubjectAlternativeNames`** :span[array of string]{.type-label} + - **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. + - **`TenantIds`** :span[array of string]{.type-label} + - **`TenantTags`** :span[array of string]{.type-label} + - **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + {} + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "EnvironmentIds": [ + "string" + ], + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SpaceId": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Version": 0 + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get a Certificate by ID or Thumbprint + +:endpoint{method="GET" path="/api/\{spaceId\}/certificates/\{id\}"} + +Also reachable at `/api/certificates/{id}`, `/api/spaces/{spaceIdentifier}/certificates/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID or Thumbprint of the Certificate. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Certificate + +- **`Archived`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateChain`** :span[array of object]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`CertificateData`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`HasPrivateKey`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsExpired`** :span[boolean]{.type-label} +- **`IssuerCommonName`** :span[string]{.type-label} +- **`IssuerDistinguishedName`** :span[string]{.type-label} +- **`IssuerOrganization`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`NotAfter`** :span[string]{.type-label} + Format `date-time`. +- **`NotBefore`** :span[string]{.type-label} + Format `date-time`. +- **`Notes`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`ReplacedBy`** :span[string]{.type-label} +- **`SelfSigned`** :span[boolean]{.type-label} +- **`SerialNumber`** :span[string]{.type-label} +- **`SignatureAlgorithmName`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SubjectAlternativeNames`** :span[array of string]{.type-label} +- **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`SubjectDistinguishedName`** :span[string]{.type-label} +- **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Thumbprint`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + { + "IssuerDistinguishedName": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SubjectDistinguishedName": "string", + "Thumbprint": "string", + "Version": 0 + } + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "EnvironmentIds": [ + "string" + ], + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SpaceId": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Version": 0 +} +``` +::: + +## Modify a certificate by ID + +:endpoint{method="PUT" path="/api/\{spaceId\}/certificates/\{id\}"} + +Also reachable at `/api/certificates/{id}`, `/api/spaces/{spaceIdentifier}/certificates/{id}`. + +Modifies an existing certificate + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the certificate. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space. + +**Request Body** + +- **`EnvironmentIds`** :span[array of string]{.type-label} + The environments allowed to use this certificate. +- **`Id`** :span[string]{.type-label} *(required)* + The ID of the certificate. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the certificate. Minimum length 1. +- **`Notes`** :span[string]{.type-label} + Additional information on the certificate. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space. +- **`TenantIds`** :span[array of string]{.type-label} + The tenants this certificate should be associated with. +- **`TenantTags`** :span[array of string]{.type-label} + The tags this certificate should be associated with. +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + The kind of deployments where this certificate should be included. + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + +:::api-example{label="Request"} +```json +{ + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "Name": "string", + "Notes": "string", + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted" +} +``` +::: + +**Response** + +`200` — The modified certificate resource + +- **`Archived`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateChain`** :span[array of object]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`CertificateData`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`HasPrivateKey`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsExpired`** :span[boolean]{.type-label} +- **`IssuerCommonName`** :span[string]{.type-label} +- **`IssuerDistinguishedName`** :span[string]{.type-label} +- **`IssuerOrganization`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`NotAfter`** :span[string]{.type-label} + Format `date-time`. +- **`NotBefore`** :span[string]{.type-label} + Format `date-time`. +- **`Notes`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`ReplacedBy`** :span[string]{.type-label} +- **`SelfSigned`** :span[boolean]{.type-label} +- **`SerialNumber`** :span[string]{.type-label} +- **`SignatureAlgorithmName`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SubjectAlternativeNames`** :span[array of string]{.type-label} +- **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`SubjectDistinguishedName`** :span[string]{.type-label} +- **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Thumbprint`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + { + "IssuerDistinguishedName": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SubjectDistinguishedName": "string", + "Thumbprint": "string", + "Version": 0 + } + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "EnvironmentIds": [ + "string" + ], + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SpaceId": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Version": 0 +} +``` +::: + +## Delete an existing Certificate + +:endpoint{method="DELETE" path="/api/\{spaceId\}/certificates/\{id\}"} + +Also reachable at `/api/certificates/{id}`, `/api/spaces/{spaceIdentifier}/certificates/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Certificate to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Archive an existing Certificate + +:endpoint{method="POST" path="/api/\{spaceId\}/certificates/\{id\}/archive"} + +Also reachable at `/api/certificates/{id}/archive`, `/api/spaces/{spaceIdentifier}/certificates/{id}/archive`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Certificate to archive. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Archive an existing Certificate + +:endpoint{method="POST" path="/api/\{spaceId\}/certificates/\{id\}/archive/v1"} + +Also reachable at `/api/certificates/{id}/archive/v1`, `/api/spaces/{spaceIdentifier}/certificates/{id}/archive/v1`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Certificate to archive. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the Certificate has been archived + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Export the certificate + +:endpoint{method="GET" path="/api/\{spaceId\}/certificates/\{id\}/export"} + +Also reachable at `/api/certificates/{id}/export`, `/api/spaces/{spaceIdentifier}/certificates/{id}/export`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the certificate to export. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the space. + +**Query Parameters** + +- **`format`** :span[enum]{.type-label} + The file format in which to export the certificate. + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`includePrivateKey`** :span[boolean]{.type-label} + Whether the private key should be included in the exported file. +- **`password`** :span[string]{.type-label} + The password to read the stored certificate. +- **`pemOptions`** :span[enum]{.type-label} + Whether the exported PEM file should include the certificate chain. + Allowed values: `PrimaryOnly`, `PrimaryAndChain`, `ChainOnly`. + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Replace an existing Certificate with another + +:endpoint{method="POST" path="/api/\{spaceId\}/certificates/\{id\}/replace"} + +Also reachable at `/api/certificates/{id}/replace`, `/api/spaces/{spaceIdentifier}/certificates/{id}/replace`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Certificate to Replace. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`CertificateData`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Id`** :span[string]{.type-label} *(required)* + ID of the Certificate to Replace. +- **`Password`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "CertificateData": "string", + "Id": "string", + "Password": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Certificate has been replaced + +- **`Archived`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateChain`** :span[array of object]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`CertificateData`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`HasPrivateKey`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsExpired`** :span[boolean]{.type-label} +- **`IssuerCommonName`** :span[string]{.type-label} +- **`IssuerDistinguishedName`** :span[string]{.type-label} +- **`IssuerOrganization`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`NotAfter`** :span[string]{.type-label} + Format `date-time`. +- **`NotBefore`** :span[string]{.type-label} + Format `date-time`. +- **`Notes`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`ReplacedBy`** :span[string]{.type-label} +- **`SelfSigned`** :span[boolean]{.type-label} +- **`SerialNumber`** :span[string]{.type-label} +- **`SignatureAlgorithmName`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SubjectAlternativeNames`** :span[array of string]{.type-label} +- **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`SubjectDistinguishedName`** :span[string]{.type-label} +- **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Thumbprint`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + { + "IssuerDistinguishedName": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SubjectDistinguishedName": "string", + "Thumbprint": "string", + "Version": 0 + } + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "EnvironmentIds": [ + "string" + ], + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SpaceId": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Version": 0 +} +``` +::: + +## Unarchive an existing archived Certificate + +:endpoint{method="POST" path="/api/\{spaceId\}/certificates/\{id\}/unarchive"} + +Also reachable at `/api/certificates/{id}/unarchive`, `/api/spaces/{spaceIdentifier}/certificates/{id}/unarchive`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Certificate to unarchive. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Unarchive an existing archived Certificate + +:endpoint{method="POST" path="/api/\{spaceId\}/certificates/\{id\}/unarchive/v1"} + +Also reachable at `/api/certificates/{id}/unarchive/v1`, `/api/spaces/{spaceIdentifier}/certificates/{id}/unarchive/v1`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Certificate to unarchive. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the Certificate has been un-archived + +:::api-example{label="Response"} +```json +{} +``` +::: + +## GET /api/{spaceId}/certificates/{id}/usages + +:endpoint{method="GET" path="/api/\{spaceId\}/certificates/\{id\}/usages"} + +Also reachable at `/api/certificates/{id}/usages`, `/api/spaces/{spaceIdentifier}/certificates/{id}/usages`. + +Get the usages of a certificate + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the certificate. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the space. + +**Response** + +`200` — The requested Certificate usages + +- **`DeploymentTargetUsages`** :span[array of object]{.type-label} + - **`Architecture`** :span[string]{.type-label} + - **`Endpoint`** :span[object]{.type-label} + - **`EnvironmentIds`** :span[array of string]{.type-label} + - **`HasLatestCalamari`** :span[boolean]{.type-label} + - **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`IsInProcess`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MachinePolicyId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OperatingSystem`** :span[string]{.type-label} + - **`OperatingSystemVersion`** :span[string]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`ShellName`** :span[string]{.type-label} + - **`ShellVersion`** :span[string]{.type-label} + - **`SkipInitialHealthCheck`** :span[boolean]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`StatusSummary`** :span[string]{.type-label} + - **`TenantIds`** :span[array of string]{.type-label} + - **`TenantTags`** :span[array of string]{.type-label} + - **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + - **`Thumbprint`** :span[string]{.type-label} + - **`Uri`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetUsages`** :span[array of object]{.type-label} + - **`ContentType`** :span[enum]{.type-label} + Describes the purpose of the variable set. Clients can use this to offer an editing experience appropriately. + Allowed values: `Variables`, `ScriptModule`. + - **`Description`** :span[string]{.type-label} + Gets or sets a description of this variable set that explains the purpose of the variable set to other users. This field may contain markdown. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this variable set. This should be short, preferably 5-20 characters. + - **`SpaceId`** :span[string]{.type-label} + - **`Templates`** :span[array of object]{.type-label} + Gets the variable templates. + - **`VariableSetId`** :span[string]{.type-label} + Gets or sets the id of the associated variable set. + - **`Version`** :span[integer]{.type-label} + Gets or sets the version number. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectUsages`** :span[array of object]{.type-label} + - **`AllowIgnoreChannelRules`** :span[boolean]{.type-label} + - **`AutoCreateRelease`** :span[boolean]{.type-label} + - **`AutoDeployReleaseOverrides`** :span[array of object]{.type-label} + - **`ClonedFromProjectId`** :span[string]{.type-label} + - **`CombineHealthAndSyncStatusInDashboardLiveStatus`** :span[boolean]{.type-label} + - **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. + - **`DefaultPowerShellEdition`** :span[string]{.type-label} + - **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} + - **`DeploymentChangesTemplate`** :span[string]{.type-label} + - **`DeploymentProcessId`** :span[string]{.type-label} + - **`DeprovisioningRunbookId`** :span[string]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`DiscreteChannelRelease`** :span[boolean]{.type-label} + Treats releases of different channels to the same environment as a seperate deployment dimension. 'False' indicates a "hotfix"-style usage of channels (single release active per environment ignoring channels), whereas `True` indicates "microservice"-style usage (single release per environment per channel). + - **`ExecuteDeploymentsOnEventBasedPipeline`** :span[boolean]{.type-label} + - **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`Icon`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IncludedLibraryVariableSetIds`** :span[array of string]{.type-label} + Library variable sets included in the project. Sets are listed in order of precedence, with earlier items in the list overriding any variables with the same name and scope definition appearing later in the list. + - **`IsBadgesEnabled`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`IsVersionControlled`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LifecycleId`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`PersistenceSettings`** :span[object]{.type-label} + - **`ProjectConnectivityPolicy`** :span[object]{.type-label} + - **`ProjectGroupId`** :span[string]{.type-label} + - **`ProjectTags`** :span[array of string]{.type-label} + List of tags assigned to this project. + - **`ProjectTemplateDetails`** :span[object]{.type-label} + - **`ProvisioningRunbookId`** :span[string]{.type-label} + - **`ReleaseCreationStrategy`** :span[object]{.type-label} + - **`ReleaseNotesTemplate`** :span[string]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Templates`** :span[array of object]{.type-label} + - **`TenantedDeploymentMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + - **`VariableSetId`** :span[string]{.type-label} + - **`VersioningStrategy`** :span[object]{.type-label} +- **`TenantUsages`** :span[array of object]{.type-label} + - **`ClonedFromTenantId`** :span[string]{.type-label} + - **`CustomFields`** :span[array of string]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Icon`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`ProjectEnvironments`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`TenantTags`** :span[array of string]{.type-label} + Tags are referenced by CanonicalName like {TagSetName}/{TagName}. + +:::api-example{label="Response"} +```json +{ + "DeploymentTargetUsages": [ + { + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {} + }, + "EnvironmentIds": [ + "string" + ], + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "Roles": [ + "string" + ], + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Uri": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetUsages": [ + { + "ContentType": "Variables", + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpaceId": "string", + "Templates": [ + {} + ], + "VariableSetId": "string", + "Version": 0 + } + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectUsages": [ + { + "AllowIgnoreChannelRules": true, + "AutoCreateRelease": true, + "AutoDeployReleaseOverrides": [ + {} + ], + "ClonedFromProjectId": "string", + "CombineHealthAndSyncStatusInDashboardLiveStatus": true, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultPowerShellEdition": "string", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "DeploymentProcessId": "string", + "DeprovisioningRunbookId": "string", + "Description": "string", + "DiscreteChannelRelease": true, + "ExecuteDeploymentsOnEventBasedPipeline": true, + "ExtensionSettings": [ + {} + ], + "ForcePackageDownload": true, + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IncludedLibraryVariableSetIds": [ + "string" + ], + "IsBadgesEnabled": true, + "IsDisabled": true, + "IsVersionControlled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PersistenceSettings": { + "Type": "Database" + }, + "ProjectConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "ProjectGroupId": "string", + "ProjectTags": [ + "string" + ], + "ProjectTemplateDetails": { + "IsShared": true, + "Slug": "string", + "VersionMask": "string" + }, + "ProvisioningRunbookId": "string", + "ReleaseCreationStrategy": { + "ChannelId": "string", + "ReleaseCreationPackage": {} + }, + "ReleaseNotesTemplate": "string", + "Slug": "string", + "SpaceId": "string", + "Templates": [ + {} + ], + "TenantedDeploymentMode": "Untenanted", + "VariableSetId": "string", + "VersioningStrategy": { + "DonorPackage": {}, + "Template": "string" + } + } + ], + "TenantUsages": [ + { + "ClonedFromTenantId": "string", + "CustomFields": [ + "string" + ], + "Description": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectEnvironments": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ] + } + ] +} +``` +::: + +## Request the list of Certificate Configurations + +:endpoint{method="GET" path="/api/configuration/certificates"} + +Only returns configurations for the global Certificate + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested Certificate Configurations + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`SignatureAlgorithm`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SignatureAlgorithm": "string", + "Thumbprint": "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 +} +``` +::: + +## Get a Certificate Configuration by ID + +:endpoint{method="GET" path="/api/configuration/certificates/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the CertificateConfiguration to load. + +**Response** + +`200` — The certificate configuration matching the supplied ID + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`SignatureAlgorithm`** :span[string]{.type-label} +- **`Thumbprint`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SignatureAlgorithm": "string", + "Thumbprint": "string" +} +``` +::: + +## Get public certificate + +:endpoint{method="GET" path="/api/configuration/certificates/\{id\}/public-cer"} + +Downloads the public portion of the certificate in .cer format + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The Id of the certificate to retrieve the public portion of. + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: diff --git a/src/pages/docs/api/channels.md b/src/pages/docs/api/channels.md new file mode 100644 index 0000000000..94d3d887ad --- /dev/null +++ b/src/pages/docs/api/channels.md @@ -0,0 +1,2005 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Channels +--- + +## Create a Channel + +:endpoint{method="POST" path="/api/\{spaceId\}/channels"} + +Also reachable at `/api/channels`, `/api/spaces/{spaceIdentifier}/channels`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`AutomaticEphemeralEnvironmentDeployments`** :span[boolean]{.type-label} +- **`CustomFieldDefinitions`** :span[array of object]{.type-label} + Custom fields (FieldName plus a human-facing Description) that become mandatory when creating a release in this channel. + - **`Description`** :span[string]{.type-label} + - **`FieldName`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EphemeralEnvironmentNameTemplate`** :span[string]{.type-label} + Maximum length 1000. +- **`GitReferenceRules`** :span[array of string]{.type-label} + Git reference patterns (e.g. 'refs/heads/main', 'refs/heads/feature/*') restricting which branches or tags can create releases in this channel. Only valid for version-controlled (Config-as-Code) projects. +- **`GitResourceRules`** :span[array of object]{.type-label} + Rules restricting which Git refs may be used for external Git dependencies referenced by deployment steps. Each rule targets step Git dependencies via GitDependencyActions (DeploymentActionSlug plus GitDependencyName) and lists the allowed Git reference patterns in Rules. + - **`GitDependencyActions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Rules`** :span[array of string]{.type-label} +- **`IsDefault`** :span[boolean]{.type-label} +- **`LifecycleId`** :span[string]{.type-label} + The lifecycle for this channel. Must be null for ephemeral environment channels. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ParentEnvironmentId`** :span[string]{.type-label} + The parent environment for all ephemeral environments created in this channel. Required for ephemeral environment channels. +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`Rules`** :span[array of object]{.type-label} + Version rules restricting which package versions may be used when creating a release in this channel. Each rule targets step packages via ActionPackages (DeploymentAction is the step name or ID, PackageReference the package reference name or ID) and constrains versions with a NuGet-style VersionRange (e.g. '[1.0,2.0)') and/or a Tag regex matched against the package's pre-release tag (e.g. '^$' for stable versions only). Leave each rule's Id blank; the server assigns it. + - **`ActionPackages`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Tag`** :span[string]{.type-label} + - **`VersionRange`** :span[string]{.type-label} + - **`VersionTagRegex`** :span[string]{.type-label} + - **`VersioningStrategy`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantTags`** :span[array of string]{.type-label} + Canonical tenant tag names in 'TagSet/Tag' format restricting which tenants can deploy releases from this channel. +- **`Type`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "AutomaticEphemeralEnvironmentDeployments": true, + "CustomFieldDefinitions": [ + { + "Description": "string", + "FieldName": "string" + } + ], + "Description": "string", + "EphemeralEnvironmentNameTemplate": "string", + "GitReferenceRules": [ + "string" + ], + "GitResourceRules": [ + { + "GitDependencyActions": [ + {} + ], + "Id": "string", + "Rules": [ + "string" + ] + } + ], + "IsDefault": true, + "LifecycleId": "string", + "Name": "string", + "ParentEnvironmentId": "string", + "ProjectId": "string", + "Rules": [ + { + "ActionPackages": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Tag": "string", + "VersionRange": "string", + "VersionTagRegex": "string", + "VersioningStrategy": "string" + } + ], + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ], + "Type": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`AutomaticEphemeralEnvironmentDeployments`** :span[boolean]{.type-label} +- **`CustomFieldDefinitions`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`FieldName`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EphemeralEnvironmentNameTemplate`** :span[string]{.type-label} +- **`GitReferenceRules`** :span[array of string]{.type-label} +- **`GitResourceRules`** :span[array of object]{.type-label} + - **`GitDependencyActions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Rules`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LifecycleId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ParentEnvironmentId`** :span[string]{.type-label} + The parent environment for all ephemeral environments created in this channel. +- **`ProjectId`** :span[string]{.type-label} +- **`Rules`** :span[array of object]{.type-label} + - **`ActionPackages`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Tag`** :span[string]{.type-label} + - **`VersionRange`** :span[string]{.type-label} + - **`VersionTagRegex`** :span[string]{.type-label} + - **`VersioningStrategy`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`Type`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AutomaticEphemeralEnvironmentDeployments": true, + "CustomFieldDefinitions": [ + { + "Description": "string", + "FieldName": "string" + } + ], + "Description": "string", + "EphemeralEnvironmentNameTemplate": "string", + "GitReferenceRules": [ + "string" + ], + "GitResourceRules": [ + { + "GitDependencyActions": [ + {} + ], + "Id": "string", + "Rules": [ + "string" + ] + } + ], + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ParentEnvironmentId": "string", + "ProjectId": "string", + "Rules": [ + { + "ActionPackages": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Tag": "string", + "VersionRange": "string", + "VersionTagRegex": "string", + "VersioningStrategy": "string" + } + ], + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ], + "Type": "string" +} +``` +::: + +## Get a list of Channels + +:endpoint{method="GET" path="/api/\{spaceId\}/channels/all"} + +Also reachable at `/api/channels/all`, `/api/spaces/{spaceIdentifier}/channels/all`. + +Lists all of the channels in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + A set of Channel IDs to retrieve Channels for. Example: Channel-101,Channel-201. + +**Response** + +`200` — List of all of the channels in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name. + +- **`AutomaticEphemeralEnvironmentDeployments`** :span[boolean]{.type-label} +- **`CustomFieldDefinitions`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`FieldName`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EphemeralEnvironmentNameTemplate`** :span[string]{.type-label} +- **`GitReferenceRules`** :span[array of string]{.type-label} +- **`GitResourceRules`** :span[array of object]{.type-label} + - **`GitDependencyActions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Rules`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LifecycleId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ParentEnvironmentId`** :span[string]{.type-label} + The parent environment for all ephemeral environments created in this channel. +- **`ProjectId`** :span[string]{.type-label} +- **`Rules`** :span[array of object]{.type-label} + - **`ActionPackages`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Tag`** :span[string]{.type-label} + - **`VersionRange`** :span[string]{.type-label} + - **`VersionTagRegex`** :span[string]{.type-label} + - **`VersioningStrategy`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`Type`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "AutomaticEphemeralEnvironmentDeployments": true, + "CustomFieldDefinitions": [ + { + "Description": "string", + "FieldName": "string" + } + ], + "Description": "string", + "EphemeralEnvironmentNameTemplate": "string", + "GitReferenceRules": [ + "string" + ], + "GitResourceRules": [ + { + "GitDependencyActions": [ + {} + ], + "Id": "string", + "Rules": [ + "string" + ] + } + ], + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ParentEnvironmentId": "string", + "ProjectId": "string", + "Rules": [ + { + "ActionPackages": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {}, + "Tag": "string", + "VersionRange": "string", + "VersionTagRegex": "string", + "VersioningStrategy": "string" + } + ], + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ], + "Type": "string" + } +] +``` +::: + +## Perform Channel version rule test against provided Package version + +:endpoint{method="GET" path="/api/\{spaceId\}/channels/rule-test"} + +Also reachable at `/api/channels/rule-test`, `/api/spaces/{spaceIdentifier}/channels/rule-test`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`actions`** :span[array of string]{.type-label} + A list of step names to find a package step which the feed type will determine which version format should be used. +- **`feedId`** :span[string]{.type-label} + A feed ID to determine which version format should be used. +- **`feedType`** :span[enum]{.type-label} + A feed type to determine which version format should be used. + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`preReleaseTag`** :span[string]{.type-label} + A regular expression to test the version pre-release tag against. +- **`projectId`** :span[string]{.type-label} + A deployment process ID in which to search for the steps referenced by the 'Actions' parameter. +- **`version`** :span[string]{.type-label} *(required)* + The version to test. +- **`versionRange`** :span[string]{.type-label} + A version range to test the version against. + +**Response** + +`200` — Result of testing Channel version rules + +- **`Errors`** :span[array of string]{.type-label} +- **`SatisfiesPreReleaseTag`** :span[boolean]{.type-label} +- **`SatisfiesVersionRange`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Errors": [ + "string" + ], + "SatisfiesPreReleaseTag": true, + "SatisfiesVersionRange": true +} +``` +::: + +## Perform Channel version rule test against provided Package version + +:endpoint{method="POST" path="/api/\{spaceId\}/channels/rule-test"} + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`actions`** :span[array of string]{.type-label} + A list of step names to find a package step which the feed type will determine which version format should be used. +- **`feedId`** :span[string]{.type-label} + A feed ID to determine which version format should be used. +- **`feedType`** :span[enum]{.type-label} + A feed type to determine which version format should be used. + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`preReleaseTag`** :span[string]{.type-label} + A regular expression to test the version pre-release tag against. +- **`projectId`** :span[string]{.type-label} + A deployment process ID in which to search for the steps referenced by the 'Actions' parameter. +- **`version`** :span[string]{.type-label} *(required)* + The version to test. +- **`versionRange`** :span[string]{.type-label} + A version range to test the version against. + +**Response** + +`200` — Result of testing Channel version rules + +- **`Errors`** :span[array of string]{.type-label} +- **`SatisfiesPreReleaseTag`** :span[boolean]{.type-label} +- **`SatisfiesVersionRange`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Errors": [ + "string" + ], + "SatisfiesPreReleaseTag": true, + "SatisfiesVersionRange": true +} +``` +::: + +## Perform Channel version rule test against provided Package version + +:endpoint{method="POST" path="/api/spaces/\{spaceIdentifier\}/channels/rule-test"} + +Also reachable at `/api/channels/rule-test`. + +**Path Parameters** + +- **`spaceIdentifier`** :span[string]{.type-label} *(required)* + Identifier (ID or slug) of the space. + +**Query Parameters** + +- **`actions`** :span[array of string]{.type-label} + A list of step names to find a package step which the feed type will determine which version format should be used. +- **`feedId`** :span[string]{.type-label} + A feed ID to determine which version format should be used. +- **`feedType`** :span[enum]{.type-label} + A feed type to determine which version format should be used. + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`preReleaseTag`** :span[string]{.type-label} + A regular expression to test the version pre-release tag against. +- **`projectId`** :span[string]{.type-label} + A deployment process ID in which to search for the steps referenced by the 'Actions' parameter. +- **`version`** :span[string]{.type-label} *(required)* + The version to test. +- **`versionRange`** :span[string]{.type-label} + A version range to test the version against. + +**Response** + +`200` — Result of testing Channel version rules + +- **`Errors`** :span[array of string]{.type-label} +- **`SatisfiesPreReleaseTag`** :span[boolean]{.type-label} +- **`SatisfiesVersionRange`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Errors": [ + "string" + ], + "SatisfiesPreReleaseTag": true, + "SatisfiesVersionRange": true +} +``` +::: + +## Test Channel version rules + +:endpoint{method="GET" path="/api/\{spaceId\}/channels/rule-test/v1"} + +Also reachable at `/api/channels/rule-test/v1`, `/api/spaces/{spaceIdentifier}/channels/rule-test/v1`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`deploymentProcessId`** :span[string]{.type-label} +- **`feedId`** :span[string]{.type-label} +- **`feedType`** :span[enum]{.type-label} + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`preReleaseTagPattern`** :span[string]{.type-label} +- **`stepName`** :span[string]{.type-label} +- **`version`** :span[string]{.type-label} *(required)* +- **`versionRange`** :span[string]{.type-label} +- **`versionTagRegex`** :span[string]{.type-label} + +**Response** + +`200` — The result of testing the Channel version rules + +- **`Errors`** :span[array of string]{.type-label} +- **`SatisfiesPreReleaseTag`** :span[boolean]{.type-label} +- **`SatisfiesVersionRange`** :span[boolean]{.type-label} +- **`SatisfiesVersionTagRegex`** :span[boolean]{.type-label} + Whether the version satisfies the rule's version-tag regex. Defaults to true (no regex, or a legacy caller, counts as satisfied). + +:::api-example{label="Response"} +```json +{ + "Errors": [ + "string" + ], + "SatisfiesPreReleaseTag": true, + "SatisfiesVersionRange": true, + "SatisfiesVersionTagRegex": true +} +``` +::: + +## Test Channel version rules + +:endpoint{method="POST" path="/api/\{spaceId\}/channels/rule-test/v1"} + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`deploymentProcessId`** :span[string]{.type-label} +- **`feedId`** :span[string]{.type-label} +- **`feedType`** :span[enum]{.type-label} + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`preReleaseTagPattern`** :span[string]{.type-label} +- **`stepName`** :span[string]{.type-label} +- **`version`** :span[string]{.type-label} *(required)* +- **`versionRange`** :span[string]{.type-label} +- **`versionTagRegex`** :span[string]{.type-label} + +**Response** + +`200` — The result of testing the Channel version rules + +- **`Errors`** :span[array of string]{.type-label} +- **`SatisfiesPreReleaseTag`** :span[boolean]{.type-label} +- **`SatisfiesVersionRange`** :span[boolean]{.type-label} +- **`SatisfiesVersionTagRegex`** :span[boolean]{.type-label} + Whether the version satisfies the rule's version-tag regex. Defaults to true (no regex, or a legacy caller, counts as satisfied). + +:::api-example{label="Response"} +```json +{ + "Errors": [ + "string" + ], + "SatisfiesPreReleaseTag": true, + "SatisfiesVersionRange": true, + "SatisfiesVersionTagRegex": true +} +``` +::: + +## Test Channel version rules + +:endpoint{method="POST" path="/api/spaces/\{spaceIdentifier\}/channels/rule-test/v1"} + +Also reachable at `/api/channels/rule-test/v1`. + +**Path Parameters** + +- **`spaceIdentifier`** :span[string]{.type-label} *(required)* + Identifier (ID or slug) of the space. + +**Query Parameters** + +- **`deploymentProcessId`** :span[string]{.type-label} +- **`feedId`** :span[string]{.type-label} +- **`feedType`** :span[enum]{.type-label} + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`preReleaseTagPattern`** :span[string]{.type-label} +- **`stepName`** :span[string]{.type-label} +- **`version`** :span[string]{.type-label} *(required)* +- **`versionRange`** :span[string]{.type-label} +- **`versionTagRegex`** :span[string]{.type-label} + +**Response** + +`200` — The result of testing the Channel version rules + +- **`Errors`** :span[array of string]{.type-label} +- **`SatisfiesPreReleaseTag`** :span[boolean]{.type-label} +- **`SatisfiesVersionRange`** :span[boolean]{.type-label} +- **`SatisfiesVersionTagRegex`** :span[boolean]{.type-label} + Whether the version satisfies the rule's version-tag regex. Defaults to true (no regex, or a legacy caller, counts as satisfied). + +:::api-example{label="Response"} +```json +{ + "Errors": [ + "string" + ], + "SatisfiesPreReleaseTag": true, + "SatisfiesVersionRange": true, + "SatisfiesVersionTagRegex": true +} +``` +::: + +## Update an existing Channel + +:endpoint{method="PUT" path="/api/\{spaceId\}/channels/\{id\}"} + +Also reachable at `/api/channels/{id}`, `/api/spaces/{spaceIdentifier}/channels/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Gets or sets a unique identifier for this resource. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`AutomaticEphemeralEnvironmentDeployments`** :span[boolean]{.type-label} +- **`CustomFieldDefinitions`** :span[array of object]{.type-label} + Custom fields (FieldName plus a human-facing Description) that become mandatory when creating a release in this channel. Omit to keep the current definitions; an empty list clears them. + - **`Description`** :span[string]{.type-label} + - **`FieldName`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EphemeralEnvironmentNameTemplate`** :span[string]{.type-label} + Maximum length 1000. +- **`GitReferenceRules`** :span[array of string]{.type-label} + Git reference patterns (e.g. 'refs/heads/main', 'refs/heads/feature/*') restricting which branches or tags can create releases in this channel. Only valid for version-controlled (Config-as-Code) projects. Omit to keep the current rules; an empty list clears them. +- **`GitResourceRules`** :span[array of object]{.type-label} + Rules restricting which Git refs may be used for external Git dependencies referenced by deployment steps. Each rule targets step Git dependencies via GitDependencyActions (DeploymentActionSlug plus GitDependencyName) and lists the allowed Git reference patterns in Rules. Omit to keep the current rules; an empty list clears them. + - **`GitDependencyActions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Rules`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`LifecycleId`** :span[string]{.type-label} + The lifecycle for this channel. Must be null for ephemeral environment channels. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ParentEnvironmentId`** :span[string]{.type-label} + The parent environment for all ephemeral environments created in this channel. Required for ephemeral environment channels. +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`Rules`** :span[array of object]{.type-label} + Version rules restricting which package versions may be used when creating a release in this channel. Each rule targets step packages via ActionPackages (DeploymentAction is the step name or ID, PackageReference the package reference name or ID) and constrains versions with a NuGet-style VersionRange (e.g. '[1.0,2.0)') and/or a Tag regex matched against the package's pre-release tag (e.g. '^$' for stable versions only). Keep each existing rule's Id; leave it blank on new rules. Omit to keep the current rules; an empty list clears them. + - **`ActionPackages`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Tag`** :span[string]{.type-label} + - **`VersionRange`** :span[string]{.type-label} + - **`VersionTagRegex`** :span[string]{.type-label} + - **`VersioningStrategy`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantTags`** :span[array of string]{.type-label} + Canonical tenant tag names in 'TagSet/Tag' format restricting which tenants can deploy releases from this channel. Omit to keep the current tags; an empty collection clears them. + +:::api-example{label="Request"} +```json +{ + "AutomaticEphemeralEnvironmentDeployments": true, + "CustomFieldDefinitions": [ + { + "Description": "string", + "FieldName": "string" + } + ], + "Description": "string", + "EphemeralEnvironmentNameTemplate": "string", + "GitReferenceRules": [ + "string" + ], + "GitResourceRules": [ + { + "GitDependencyActions": [ + {} + ], + "Id": "string", + "Rules": [ + "string" + ] + } + ], + "Id": "string", + "IsDefault": true, + "LifecycleId": "string", + "Name": "string", + "ParentEnvironmentId": "string", + "ProjectId": "string", + "Rules": [ + { + "ActionPackages": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Tag": "string", + "VersionRange": "string", + "VersionTagRegex": "string", + "VersioningStrategy": "string" + } + ], + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ] +} +``` +::: + +**Response** + +`200` — Confirms the Channel was modified, containing the updated Channel + +- **`AutomaticEphemeralEnvironmentDeployments`** :span[boolean]{.type-label} +- **`CustomFieldDefinitions`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`FieldName`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EphemeralEnvironmentNameTemplate`** :span[string]{.type-label} +- **`GitReferenceRules`** :span[array of string]{.type-label} +- **`GitResourceRules`** :span[array of object]{.type-label} + - **`GitDependencyActions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Rules`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LifecycleId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ParentEnvironmentId`** :span[string]{.type-label} + The parent environment for all ephemeral environments created in this channel. +- **`ProjectId`** :span[string]{.type-label} +- **`Rules`** :span[array of object]{.type-label} + - **`ActionPackages`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Tag`** :span[string]{.type-label} + - **`VersionRange`** :span[string]{.type-label} + - **`VersionTagRegex`** :span[string]{.type-label} + - **`VersioningStrategy`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`Type`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AutomaticEphemeralEnvironmentDeployments": true, + "CustomFieldDefinitions": [ + { + "Description": "string", + "FieldName": "string" + } + ], + "Description": "string", + "EphemeralEnvironmentNameTemplate": "string", + "GitReferenceRules": [ + "string" + ], + "GitResourceRules": [ + { + "GitDependencyActions": [ + {} + ], + "Id": "string", + "Rules": [ + "string" + ] + } + ], + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ParentEnvironmentId": "string", + "ProjectId": "string", + "Rules": [ + { + "ActionPackages": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Tag": "string", + "VersionRange": "string", + "VersionTagRegex": "string", + "VersioningStrategy": "string" + } + ], + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ], + "Type": "string" +} +``` +::: + +## Delete a ChannelResource by ID + +:endpoint{method="DELETE" path="/api/\{spaceId\}/channels/\{id\}"} + +Also reachable at `/api/channels/{id}`, `/api/spaces/{spaceIdentifier}/channels/{id}`. + +Deletes an existing channel. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the ChannelResource to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Get a list of ChannelResources for the given ProjectResource + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/channels"} + +Also reachable at `/api/projects/{projectId}/channels`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/channels`. + +Lists all the channels for the given project + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`partialName`** :span[string]{.type-label} + A partial or complete name to limit the set of retrieved Tenants to. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — List of all the channels for the given project + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`AutomaticEphemeralEnvironmentDeployments`** :span[boolean]{.type-label} + - **`CustomFieldDefinitions`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`EphemeralEnvironmentNameTemplate`** :span[string]{.type-label} + - **`GitReferenceRules`** :span[array of string]{.type-label} + - **`GitResourceRules`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDefault`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LifecycleId`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`ParentEnvironmentId`** :span[string]{.type-label} + The parent environment for all ephemeral environments created in this channel. + - **`ProjectId`** :span[string]{.type-label} + - **`Rules`** :span[array of object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`TenantTags`** :span[array of string]{.type-label} + - **`Type`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "AutomaticEphemeralEnvironmentDeployments": true, + "CustomFieldDefinitions": [ + {} + ], + "Description": "string", + "EphemeralEnvironmentNameTemplate": "string", + "GitReferenceRules": [ + "string" + ], + "GitResourceRules": [ + {} + ], + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ParentEnvironmentId": "string", + "ProjectId": "string", + "Rules": [ + {} + ], + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ], + "Type": "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 +} +``` +::: + +## Create a Channel + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/channels"} + +Also reachable at `/api/projects/{projectId}/channels`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/channels`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`AutomaticEphemeralEnvironmentDeployments`** :span[boolean]{.type-label} +- **`CustomFieldDefinitions`** :span[array of object]{.type-label} + Custom fields (FieldName plus a human-facing Description) that become mandatory when creating a release in this channel. + - **`Description`** :span[string]{.type-label} + - **`FieldName`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EphemeralEnvironmentNameTemplate`** :span[string]{.type-label} + Maximum length 1000. +- **`GitReferenceRules`** :span[array of string]{.type-label} + Git reference patterns (e.g. 'refs/heads/main', 'refs/heads/feature/*') restricting which branches or tags can create releases in this channel. Only valid for version-controlled (Config-as-Code) projects. +- **`GitResourceRules`** :span[array of object]{.type-label} + Rules restricting which Git refs may be used for external Git dependencies referenced by deployment steps. Each rule targets step Git dependencies via GitDependencyActions (DeploymentActionSlug plus GitDependencyName) and lists the allowed Git reference patterns in Rules. + - **`GitDependencyActions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Rules`** :span[array of string]{.type-label} +- **`IsDefault`** :span[boolean]{.type-label} +- **`LifecycleId`** :span[string]{.type-label} + The lifecycle for this channel. Must be null for ephemeral environment channels. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ParentEnvironmentId`** :span[string]{.type-label} + The parent environment for all ephemeral environments created in this channel. Required for ephemeral environment channels. +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`Rules`** :span[array of object]{.type-label} + Version rules restricting which package versions may be used when creating a release in this channel. Each rule targets step packages via ActionPackages (DeploymentAction is the step name or ID, PackageReference the package reference name or ID) and constrains versions with a NuGet-style VersionRange (e.g. '[1.0,2.0)') and/or a Tag regex matched against the package's pre-release tag (e.g. '^$' for stable versions only). Leave each rule's Id blank; the server assigns it. + - **`ActionPackages`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Tag`** :span[string]{.type-label} + - **`VersionRange`** :span[string]{.type-label} + - **`VersionTagRegex`** :span[string]{.type-label} + - **`VersioningStrategy`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantTags`** :span[array of string]{.type-label} + Canonical tenant tag names in 'TagSet/Tag' format restricting which tenants can deploy releases from this channel. +- **`Type`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "AutomaticEphemeralEnvironmentDeployments": true, + "CustomFieldDefinitions": [ + { + "Description": "string", + "FieldName": "string" + } + ], + "Description": "string", + "EphemeralEnvironmentNameTemplate": "string", + "GitReferenceRules": [ + "string" + ], + "GitResourceRules": [ + { + "GitDependencyActions": [ + {} + ], + "Id": "string", + "Rules": [ + "string" + ] + } + ], + "IsDefault": true, + "LifecycleId": "string", + "Name": "string", + "ParentEnvironmentId": "string", + "ProjectId": "string", + "Rules": [ + { + "ActionPackages": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Tag": "string", + "VersionRange": "string", + "VersionTagRegex": "string", + "VersioningStrategy": "string" + } + ], + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ], + "Type": "string" +} +``` +::: + +**Response** + +`200` — The newly-created Channel + +- **`AutomaticEphemeralEnvironmentDeployments`** :span[boolean]{.type-label} +- **`CustomFieldDefinitions`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`FieldName`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EphemeralEnvironmentNameTemplate`** :span[string]{.type-label} +- **`GitReferenceRules`** :span[array of string]{.type-label} +- **`GitResourceRules`** :span[array of object]{.type-label} + - **`GitDependencyActions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Rules`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LifecycleId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ParentEnvironmentId`** :span[string]{.type-label} + The parent environment for all ephemeral environments created in this channel. +- **`ProjectId`** :span[string]{.type-label} +- **`Rules`** :span[array of object]{.type-label} + - **`ActionPackages`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Tag`** :span[string]{.type-label} + - **`VersionRange`** :span[string]{.type-label} + - **`VersionTagRegex`** :span[string]{.type-label} + - **`VersioningStrategy`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`Type`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AutomaticEphemeralEnvironmentDeployments": true, + "CustomFieldDefinitions": [ + { + "Description": "string", + "FieldName": "string" + } + ], + "Description": "string", + "EphemeralEnvironmentNameTemplate": "string", + "GitReferenceRules": [ + "string" + ], + "GitResourceRules": [ + { + "GitDependencyActions": [ + {} + ], + "Id": "string", + "Rules": [ + "string" + ] + } + ], + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ParentEnvironmentId": "string", + "ProjectId": "string", + "Rules": [ + { + "ActionPackages": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Tag": "string", + "VersionRange": "string", + "VersionTagRegex": "string", + "VersioningStrategy": "string" + } + ], + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ], + "Type": "string" +} +``` +::: + +## Determine if a git reference satisfies the rules of a channel + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/channels/\{channelId\}/git-reference-rule-validation/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/channels/{channelId}/git-reference-rule-validation/v1`. + +**Path Parameters** + +- **`channelId`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`gitReference`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Represents the result of testing Channel git protection rules. + +- **`Errors`** :span[array of string]{.type-label} +- **`SatisfiesGitReferenceRules`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Errors": [ + "string" + ], + "SatisfiesGitReferenceRules": true +} +``` +::: + +## Determine if a git reference satisfies a channel's Git resource rules + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/channels/\{channelId\}/git-resource-rule-validation/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/channels/{channelId}/git-resource-rule-validation/v1`. + +**Path Parameters** + +- **`channelId`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`deploymentActionSlug`** :span[string]{.type-label} *(required)* +- **`gitDependencyName`** :span[string]{.type-label} *(required)* +- **`gitReference`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Represents the result of testing Channel Git resource rules. + +- **`Errors`** :span[array of string]{.type-label} +- **`SatisfiesGitResourceRules`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Errors": [ + "string" + ], + "SatisfiesGitResourceRules": true +} +``` +::: + +## Get a Channel by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/channels/\{id\}"} + +Also reachable at `/api/projects/{projectId}/channels/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/channels/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID or name of a space channel, or the slug of a templated Channel to load. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The channel matching the supplied Id + +- **`AutomaticEphemeralEnvironmentDeployments`** :span[boolean]{.type-label} +- **`CustomFieldDefinitions`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`FieldName`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EphemeralEnvironmentNameTemplate`** :span[string]{.type-label} +- **`GitReferenceRules`** :span[array of string]{.type-label} +- **`GitResourceRules`** :span[array of object]{.type-label} + - **`GitDependencyActions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Rules`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LifecycleId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ParentEnvironmentId`** :span[string]{.type-label} + The parent environment for all ephemeral environments created in this channel. +- **`ProjectId`** :span[string]{.type-label} +- **`Rules`** :span[array of object]{.type-label} + - **`ActionPackages`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Tag`** :span[string]{.type-label} + - **`VersionRange`** :span[string]{.type-label} + - **`VersionTagRegex`** :span[string]{.type-label} + - **`VersioningStrategy`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`Type`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AutomaticEphemeralEnvironmentDeployments": true, + "CustomFieldDefinitions": [ + { + "Description": "string", + "FieldName": "string" + } + ], + "Description": "string", + "EphemeralEnvironmentNameTemplate": "string", + "GitReferenceRules": [ + "string" + ], + "GitResourceRules": [ + { + "GitDependencyActions": [ + {} + ], + "Id": "string", + "Rules": [ + "string" + ] + } + ], + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ParentEnvironmentId": "string", + "ProjectId": "string", + "Rules": [ + { + "ActionPackages": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Tag": "string", + "VersionRange": "string", + "VersionTagRegex": "string", + "VersioningStrategy": "string" + } + ], + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ], + "Type": "string" +} +``` +::: + +## Update an existing Channel + +:endpoint{method="PUT" path="/api/\{spaceId\}/projects/\{projectId\}/channels/\{id\}"} + +Also reachable at `/api/projects/{projectId}/channels/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/channels/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Gets or sets a unique identifier for this resource. +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`AutomaticEphemeralEnvironmentDeployments`** :span[boolean]{.type-label} +- **`CustomFieldDefinitions`** :span[array of object]{.type-label} + Custom fields (FieldName plus a human-facing Description) that become mandatory when creating a release in this channel. Omit to keep the current definitions; an empty list clears them. + - **`Description`** :span[string]{.type-label} + - **`FieldName`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EphemeralEnvironmentNameTemplate`** :span[string]{.type-label} + Maximum length 1000. +- **`GitReferenceRules`** :span[array of string]{.type-label} + Git reference patterns (e.g. 'refs/heads/main', 'refs/heads/feature/*') restricting which branches or tags can create releases in this channel. Only valid for version-controlled (Config-as-Code) projects. Omit to keep the current rules; an empty list clears them. +- **`GitResourceRules`** :span[array of object]{.type-label} + Rules restricting which Git refs may be used for external Git dependencies referenced by deployment steps. Each rule targets step Git dependencies via GitDependencyActions (DeploymentActionSlug plus GitDependencyName) and lists the allowed Git reference patterns in Rules. Omit to keep the current rules; an empty list clears them. + - **`GitDependencyActions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Rules`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`LifecycleId`** :span[string]{.type-label} + The lifecycle for this channel. Must be null for ephemeral environment channels. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ParentEnvironmentId`** :span[string]{.type-label} + The parent environment for all ephemeral environments created in this channel. Required for ephemeral environment channels. +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`Rules`** :span[array of object]{.type-label} + Version rules restricting which package versions may be used when creating a release in this channel. Each rule targets step packages via ActionPackages (DeploymentAction is the step name or ID, PackageReference the package reference name or ID) and constrains versions with a NuGet-style VersionRange (e.g. '[1.0,2.0)') and/or a Tag regex matched against the package's pre-release tag (e.g. '^$' for stable versions only). Keep each existing rule's Id; leave it blank on new rules. Omit to keep the current rules; an empty list clears them. + - **`ActionPackages`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Tag`** :span[string]{.type-label} + - **`VersionRange`** :span[string]{.type-label} + - **`VersionTagRegex`** :span[string]{.type-label} + - **`VersioningStrategy`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantTags`** :span[array of string]{.type-label} + Canonical tenant tag names in 'TagSet/Tag' format restricting which tenants can deploy releases from this channel. Omit to keep the current tags; an empty collection clears them. + +:::api-example{label="Request"} +```json +{ + "AutomaticEphemeralEnvironmentDeployments": true, + "CustomFieldDefinitions": [ + { + "Description": "string", + "FieldName": "string" + } + ], + "Description": "string", + "EphemeralEnvironmentNameTemplate": "string", + "GitReferenceRules": [ + "string" + ], + "GitResourceRules": [ + { + "GitDependencyActions": [ + {} + ], + "Id": "string", + "Rules": [ + "string" + ] + } + ], + "Id": "string", + "IsDefault": true, + "LifecycleId": "string", + "Name": "string", + "ParentEnvironmentId": "string", + "ProjectId": "string", + "Rules": [ + { + "ActionPackages": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Tag": "string", + "VersionRange": "string", + "VersionTagRegex": "string", + "VersioningStrategy": "string" + } + ], + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ] +} +``` +::: + +**Response** + +`200` — Confirms the Channel was modified, containing the updated Channel + +- **`AutomaticEphemeralEnvironmentDeployments`** :span[boolean]{.type-label} +- **`CustomFieldDefinitions`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`FieldName`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EphemeralEnvironmentNameTemplate`** :span[string]{.type-label} +- **`GitReferenceRules`** :span[array of string]{.type-label} +- **`GitResourceRules`** :span[array of object]{.type-label} + - **`GitDependencyActions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Rules`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LifecycleId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ParentEnvironmentId`** :span[string]{.type-label} + The parent environment for all ephemeral environments created in this channel. +- **`ProjectId`** :span[string]{.type-label} +- **`Rules`** :span[array of object]{.type-label} + - **`ActionPackages`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Tag`** :span[string]{.type-label} + - **`VersionRange`** :span[string]{.type-label} + - **`VersionTagRegex`** :span[string]{.type-label} + - **`VersioningStrategy`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`Type`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AutomaticEphemeralEnvironmentDeployments": true, + "CustomFieldDefinitions": [ + { + "Description": "string", + "FieldName": "string" + } + ], + "Description": "string", + "EphemeralEnvironmentNameTemplate": "string", + "GitReferenceRules": [ + "string" + ], + "GitResourceRules": [ + { + "GitDependencyActions": [ + {} + ], + "Id": "string", + "Rules": [ + "string" + ] + } + ], + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ParentEnvironmentId": "string", + "ProjectId": "string", + "Rules": [ + { + "ActionPackages": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Tag": "string", + "VersionRange": "string", + "VersionTagRegex": "string", + "VersioningStrategy": "string" + } + ], + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ], + "Type": "string" +} +``` +::: + +## Delete a ChannelResource by ID + +:endpoint{method="DELETE" path="/api/\{spaceId\}/projects/\{projectId\}/channels/\{id\}"} + +Also reachable at `/api/projects/{projectId}/channels/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/channels/{id}`. + +Deletes an existing channel. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the ChannelResource to delete. +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Delete a ChannelResource by ID + +:endpoint{method="DELETE" path="/api/\{spaceId\}/projects/\{projectId\}/channels/\{id\}/v2"} + +Also reachable at `/api/projects/{projectId}/channels/{id}/v2`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/channels/{id}/v2`. + +Deletes an existing channel. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the ChannelResource to delete. +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the Channel has been deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get a list of Channels + +:endpoint{method="GET" path="/api/\{spaceId\}/channels" deprecated=true} + +Also reachable at `/api/channels`, `/api/spaces/{spaceIdentifier}/channels`. + +:::div{.warning} +**Deprecated.** This endpoint may be removed in a future release. +::: + +Lists all of the Channels in the supplied Octopus Deploy Space, from all projects, sorted by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + Comma separated list of Ids. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — List of all the Channels in the supplied Octopus Deploy Space, from all projects, sorted by name. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`AutomaticEphemeralEnvironmentDeployments`** :span[boolean]{.type-label} + - **`CustomFieldDefinitions`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`EphemeralEnvironmentNameTemplate`** :span[string]{.type-label} + - **`GitReferenceRules`** :span[array of string]{.type-label} + - **`GitResourceRules`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDefault`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LifecycleId`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`ParentEnvironmentId`** :span[string]{.type-label} + The parent environment for all ephemeral environments created in this channel. + - **`ProjectId`** :span[string]{.type-label} + - **`Rules`** :span[array of object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`TenantTags`** :span[array of string]{.type-label} + - **`Type`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "AutomaticEphemeralEnvironmentDeployments": true, + "CustomFieldDefinitions": [ + {} + ], + "Description": "string", + "EphemeralEnvironmentNameTemplate": "string", + "GitReferenceRules": [ + "string" + ], + "GitResourceRules": [ + {} + ], + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ParentEnvironmentId": "string", + "ProjectId": "string", + "Rules": [ + {} + ], + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ], + "Type": "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 +} +``` +::: + +## Get a Channel by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/channels/\{id\}" deprecated=true} + +Also reachable at `/api/channels/{id}`, `/api/spaces/{spaceIdentifier}/channels/{id}`. + +:::div{.warning} +**Deprecated.** This endpoint may be removed in a future release. +::: + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Channel to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +- **`AutomaticEphemeralEnvironmentDeployments`** :span[boolean]{.type-label} +- **`CustomFieldDefinitions`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`FieldName`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EphemeralEnvironmentNameTemplate`** :span[string]{.type-label} +- **`GitReferenceRules`** :span[array of string]{.type-label} +- **`GitResourceRules`** :span[array of object]{.type-label} + - **`GitDependencyActions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Rules`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LifecycleId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ParentEnvironmentId`** :span[string]{.type-label} + The parent environment for all ephemeral environments created in this channel. +- **`ProjectId`** :span[string]{.type-label} +- **`Rules`** :span[array of object]{.type-label} + - **`ActionPackages`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Tag`** :span[string]{.type-label} + - **`VersionRange`** :span[string]{.type-label} + - **`VersionTagRegex`** :span[string]{.type-label} + - **`VersioningStrategy`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`Type`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AutomaticEphemeralEnvironmentDeployments": true, + "CustomFieldDefinitions": [ + { + "Description": "string", + "FieldName": "string" + } + ], + "Description": "string", + "EphemeralEnvironmentNameTemplate": "string", + "GitReferenceRules": [ + "string" + ], + "GitResourceRules": [ + { + "GitDependencyActions": [ + {} + ], + "Id": "string", + "Rules": [ + "string" + ] + } + ], + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ParentEnvironmentId": "string", + "ProjectId": "string", + "Rules": [ + { + "ActionPackages": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Tag": "string", + "VersionRange": "string", + "VersionTagRegex": "string", + "VersioningStrategy": "string" + } + ], + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ], + "Type": "string" +} +``` +::: diff --git a/src/pages/docs/api/cloud-template.md b/src/pages/docs/api/cloud-template.md new file mode 100644 index 0000000000..c684d8088e --- /dev/null +++ b/src/pages/docs/api/cloud-template.md @@ -0,0 +1,65 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Cloud Template +--- + +## Request the metadata (ie, parameters and values) for a cloud template (eg, cloudformation, terraform, azure ARM template) + +:endpoint{method="POST" path="/api/cloudtemplate/\{id\}/metadata"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of a supported cloud template type, eg `CloudFormation`, `Terraform`, `AzureAppService`, `Kubernetes`, etc. + +**Request Body** + +- **`FeedId`** :span[string]{.type-label} + Id of the feed from which to load the package. Obsolete. +- **`Id`** :span[string]{.type-label} *(required)* + The id of a supported cloud template type, eg `CloudFormation`, `Terraform`, `AzureAppService`, `Kubernetes`, etc. +- **`PackageId`** :span[string]{.type-label} + Id of the package to load and parse. Obsolete. +- **`Template`** :span[string]{.type-label} *(required)* + The cloud template to evaluate and extract parameters and values from. Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "FeedId": "string", + "Id": "string", + "PackageId": "string", + "Template": "string" +} +``` +::: + +**Response** + +`200` — The metadata (ie, parameters and values) for a cloud template (eg, cloudformation, terraform, azure ARM template) + +- **`Metadata`** :span[object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Types`** :span[array of object]{.type-label} +- **`Values`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Metadata": { + "Description": "string", + "Types": [ + { + "Name": "string", + "Properties": [ + {} + ] + } + ] + }, + "Values": "string" +} +``` +::: diff --git a/src/pages/docs/api/community-action-templates.md b/src/pages/docs/api/community-action-templates.md new file mode 100644 index 0000000000..0828f799a0 --- /dev/null +++ b/src/pages/docs/api/community-action-templates.md @@ -0,0 +1,745 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Community Action Templates +--- + +## Get a list of Community Action Templates + +:endpoint{method="GET" path="/api/communityactiontemplates"} + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — List of Community Action Templates. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Author`** :span[string]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`HistoryUrl`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Packages`** :span[array of object]{.type-label} + - **`Parameters`** :span[array of object]{.type-label} + - **`Properties`** :span[object]{.type-label} + - **`Type`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} + - **`Website`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Author": "string", + "Description": "string", + "HistoryUrl": "string", + "Id": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Packages": [ + {} + ], + "Parameters": [ + {} + ], + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Type": "string", + "Version": 0, + "Website": "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 +} +``` +::: + +## Get a Community Action Template by ID + +:endpoint{method="GET" path="/api/communityactiontemplates/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the CommunityActionTemplate to load. + +**Response** + +`200` — The requested Community Action Template. + +- **`Author`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`HistoryUrl`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`Packages`** :span[array of object]{.type-label} + - **`AcquisitionLocation`** :span[string]{.type-label} + The package-acquisition location. One of PackageAcquisitionLocationResource or a variable-expression. + - **`FeedId`** :span[string]{.type-label} + Feed ID, name or a variable-expression. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + A name for the package-reference. This may be empty. This is used to discriminate the package-references. Package ID isn't suitable because an action may potentially have multiple references to the same package ID (e.g. if you wanted to use different versions of the same package). Also, the package ID may be a variable-expression. + - **`PackageId`** :span[string]{.type-label} + Package ID or a variable-expression. + - **`Properties`** :span[object]{.type-label} + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} + This reference identifier is populated when a step package step contains a package reference It allows us to correlate the reference within the step package inputs to this Server package reference. + - **`Version`** :span[string]{.type-label} + Specific version to use for this package. If not specified, package can be selected at release creation or runbook run time. +- **`Parameters`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Properties`** :span[object]{.type-label} +- **`Type`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} +- **`Website`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Author": "string", + "Description": "string", + "HistoryUrl": "string", + "Id": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Packages": [ + { + "AcquisitionLocation": "string", + "FeedId": "string", + "Id": "string", + "Name": "string", + "PackageId": "string", + "Properties": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "StepPackageInputsReferenceId": "string", + "Version": "string" + } + ], + "Parameters": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "Properties": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + } + }, + "Type": "string", + "Version": 0, + "Website": "string" +} +``` +::: + +## Get installed version of the template + +:endpoint{method="GET" path="/api/communityactiontemplates/\{id\}/actiontemplate/\{actiontemplatespaceId\}"} + +Also reachable at `/api/communityactiontemplates/{id}/actiontemplate`. + +**Path Parameters** + +- **`actiontemplatespaceId`** :span[string]{.type-label} *(required)* + Then ID of the space where the Action Template can be located. +- **`id`** :span[string]{.type-label} *(required)* + The ID of the Community Action Template. + +**Response** + +`200` — The installed version of the template. + +- **`ActionType`** :span[string]{.type-label} + Minimum length 1. +- **`CommunityActionTemplateId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GitDependencies`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitCredentialType`** :span[string]{.type-label} + Minimum length 1. + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Packages`** :span[array of object]{.type-label} + - **`AcquisitionLocation`** :span[string]{.type-label} + The package-acquisition location. One of PackageAcquisitionLocationResource or a variable-expression. + - **`FeedId`** :span[string]{.type-label} + Feed ID, name or a variable-expression. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + A name for the package-reference. This may be empty. This is used to discriminate the package-references. Package ID isn't suitable because an action may potentially have multiple references to the same package ID (e.g. if you wanted to use different versions of the same package). Also, the package ID may be a variable-expression. + - **`PackageId`** :span[string]{.type-label} + Package ID or a variable-expression. + - **`Properties`** :span[object]{.type-label} + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} + This reference identifier is populated when a step package step contains a package reference It allows us to correlate the reference within the step package inputs to this Server package reference. + - **`Version`** :span[string]{.type-label} + Specific version to use for this package. If not specified, package can be selected at release creation or runbook run time. +- **`Parameters`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Properties`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ActionType": "string", + "CommunityActionTemplateId": "string", + "Description": "string", + "GitDependencies": [ + { + "DefaultBranch": "string", + "FilePathFilters": [ + "string" + ], + "GitCredentialId": "string", + "GitCredentialType": "string", + "GitHubConnectionId": "string", + "Name": "string", + "RepositoryUri": "string", + "StepPackageInputsReferenceId": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Packages": [ + { + "AcquisitionLocation": "string", + "FeedId": "string", + "Id": "string", + "Name": "string", + "PackageId": "string", + "Properties": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "StepPackageInputsReferenceId": "string", + "Version": "string" + } + ], + "Parameters": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "Properties": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + } + }, + "SpaceId": "string", + "Version": 0 +} +``` +::: + +## Install community step template + +:endpoint{method="POST" path="/api/communityactiontemplates/\{id\}/installation/\{actiontemplatespaceId\}"} + +Also reachable at `/api/communityactiontemplates/{id}/installation`. + +**Path Parameters** + +- **`actiontemplatespaceId`** :span[string]{.type-label} *(required)* + The ID of the Space where the action template should be installed. +- **`id`** :span[string]{.type-label} *(required)* + The ID of the community action template. + +**Response** + +`201` — Created + +- **`ActionType`** :span[string]{.type-label} + Minimum length 1. +- **`CommunityActionTemplateId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GitDependencies`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitCredentialType`** :span[string]{.type-label} + Minimum length 1. + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Packages`** :span[array of object]{.type-label} + - **`AcquisitionLocation`** :span[string]{.type-label} + The package-acquisition location. One of PackageAcquisitionLocationResource or a variable-expression. + - **`FeedId`** :span[string]{.type-label} + Feed ID, name or a variable-expression. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + A name for the package-reference. This may be empty. This is used to discriminate the package-references. Package ID isn't suitable because an action may potentially have multiple references to the same package ID (e.g. if you wanted to use different versions of the same package). Also, the package ID may be a variable-expression. + - **`PackageId`** :span[string]{.type-label} + Package ID or a variable-expression. + - **`Properties`** :span[object]{.type-label} + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} + This reference identifier is populated when a step package step contains a package reference It allows us to correlate the reference within the step package inputs to this Server package reference. + - **`Version`** :span[string]{.type-label} + Specific version to use for this package. If not specified, package can be selected at release creation or runbook run time. +- **`Parameters`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Properties`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ActionType": "string", + "CommunityActionTemplateId": "string", + "Description": "string", + "GitDependencies": [ + { + "DefaultBranch": "string", + "FilePathFilters": [ + "string" + ], + "GitCredentialId": "string", + "GitCredentialType": "string", + "GitHubConnectionId": "string", + "Name": "string", + "RepositoryUri": "string", + "StepPackageInputsReferenceId": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Packages": [ + { + "AcquisitionLocation": "string", + "FeedId": "string", + "Id": "string", + "Name": "string", + "PackageId": "string", + "Properties": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "StepPackageInputsReferenceId": "string", + "Version": "string" + } + ], + "Parameters": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "Properties": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + } + }, + "SpaceId": "string", + "Version": 0 +} +``` +::: + +## Update installed community step template to the latest version + +:endpoint{method="PUT" path="/api/communityactiontemplates/\{id\}/installation/\{actiontemplatespaceId\}"} + +Also reachable at `/api/communityactiontemplates/{id}/installation`. + +**Path Parameters** + +- **`actiontemplatespaceId`** :span[string]{.type-label} *(required)* + The ID of the Space where the action template should be installed. +- **`id`** :span[string]{.type-label} *(required)* + The ID of the community action template. + +**Response** + +`200` — The updated Action Template. + +- **`ActionType`** :span[string]{.type-label} + Minimum length 1. +- **`CommunityActionTemplateId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GitDependencies`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitCredentialType`** :span[string]{.type-label} + Minimum length 1. + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Packages`** :span[array of object]{.type-label} + - **`AcquisitionLocation`** :span[string]{.type-label} + The package-acquisition location. One of PackageAcquisitionLocationResource or a variable-expression. + - **`FeedId`** :span[string]{.type-label} + Feed ID, name or a variable-expression. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + A name for the package-reference. This may be empty. This is used to discriminate the package-references. Package ID isn't suitable because an action may potentially have multiple references to the same package ID (e.g. if you wanted to use different versions of the same package). Also, the package ID may be a variable-expression. + - **`PackageId`** :span[string]{.type-label} + Package ID or a variable-expression. + - **`Properties`** :span[object]{.type-label} + - **`StepPackageInputsReferenceId`** :span[string]{.type-label} + This reference identifier is populated when a step package step contains a package reference It allows us to correlate the reference within the step package inputs to this Server package reference. + - **`Version`** :span[string]{.type-label} + Specific version to use for this package. If not specified, package can be selected at release creation or runbook run time. +- **`Parameters`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Properties`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ActionType": "string", + "CommunityActionTemplateId": "string", + "Description": "string", + "GitDependencies": [ + { + "DefaultBranch": "string", + "FilePathFilters": [ + "string" + ], + "GitCredentialId": "string", + "GitCredentialType": "string", + "GitHubConnectionId": "string", + "Name": "string", + "RepositoryUri": "string", + "StepPackageInputsReferenceId": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Packages": [ + { + "AcquisitionLocation": "string", + "FeedId": "string", + "Id": "string", + "Name": "string", + "PackageId": "string", + "Properties": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "StepPackageInputsReferenceId": "string", + "Version": "string" + } + ], + "Parameters": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "Properties": { + "additionalProp1": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp2": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "additionalProp3": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + } + }, + "SpaceId": "string", + "Version": 0 +} +``` +::: + +## Get the logo associated with the community step template + +:endpoint{method="GET" path="/api/communityactiontemplates/\{id\}/logo"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the community action template. + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: diff --git a/src/pages/docs/api/compliance-policies.md b/src/pages/docs/api/compliance-policies.md new file mode 100644 index 0000000000..d3312a1355 --- /dev/null +++ b/src/pages/docs/api/compliance-policies.md @@ -0,0 +1,550 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Compliance Policies +--- + +## Request the published versions for a policy + +:endpoint{method="GET" path="/api/platformhub/policies/\{slug\}/versions"} + +**Path Parameters** + +- **`slug`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested policy version + +- **`Description`** :span[string]{.type-label} +- **`GitCommit`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Minimum length 1. +- **`IsActive`** :span[boolean]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`PublishedDate`** :span[string]{.type-label} + Format `date-time`. +- **`RegoConditions`** :span[string]{.type-label} + Minimum length 1. +- **`RegoScope`** :span[string]{.type-label} + Minimum length 1. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. +- **`Version`** :span[string]{.type-label} + Minimum length 1. +- **`ViolationAction`** :span[string]{.type-label} + Minimum length 1. +- **`ViolationReason`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Description": "string", + "GitCommit": "string", + "GitRef": "string", + "Id": "string", + "IsActive": true, + "Name": "string", + "PublishedDate": "2020-01-01T00:00:00.000Z", + "RegoConditions": "string", + "RegoScope": "string", + "Slug": "string", + "Version": "string", + "ViolationAction": "string", + "ViolationReason": "string" + } +] +``` +::: + +## Request the published versions for a policy + +:endpoint{method="GET" path="/api/platformhub/policies/\{slug\}/versions/v2"} + +**Path Parameters** + +- **`slug`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Success + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + Minimum length 1. + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`IsActive`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PublishedDate`** :span[string]{.type-label} + Format `date-time`. + - **`RegoConditions`** :span[string]{.type-label} + Minimum length 1. + - **`RegoScope`** :span[string]{.type-label} + Minimum length 1. + - **`Slug`** :span[string]{.type-label} + Minimum length 1. + - **`Version`** :span[string]{.type-label} + Minimum length 1. + - **`ViolationAction`** :span[string]{.type-label} + Minimum length 1. + - **`ViolationReason`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "Description": "string", + "GitCommit": "string", + "GitRef": "string", + "Id": "string", + "IsActive": true, + "Name": "string", + "PublishedDate": "2020-01-01T00:00:00.000Z", + "RegoConditions": "string", + "RegoScope": "string", + "Slug": "string", + "Version": "string", + "ViolationAction": "string", + "ViolationReason": "string" + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Modify the activation status for a policy version + +:endpoint{method="POST" path="/api/platformhub/policies/\{slug\}/versions/\{version\}/modify-status"} + +**Path Parameters** + +- **`slug`** :span[string]{.type-label} *(required)* +- **`version`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`IsActive`** :span[boolean]{.type-label} *(required)* +- **`Slug`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Version`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "IsActive": true, + "Slug": "string", + "Version": "string" +} +``` +::: + +**Response** + +`200` — The requested policy version + +- **`Description`** :span[string]{.type-label} +- **`GitCommit`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Minimum length 1. +- **`IsActive`** :span[boolean]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`PublishedDate`** :span[string]{.type-label} + Format `date-time`. +- **`RegoConditions`** :span[string]{.type-label} + Minimum length 1. +- **`RegoScope`** :span[string]{.type-label} + Minimum length 1. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. +- **`Version`** :span[string]{.type-label} + Minimum length 1. +- **`ViolationAction`** :span[string]{.type-label} + Minimum length 1. +- **`ViolationReason`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "GitCommit": "string", + "GitRef": "string", + "Id": "string", + "IsActive": true, + "Name": "string", + "PublishedDate": "2020-01-01T00:00:00.000Z", + "RegoConditions": "string", + "RegoScope": "string", + "Slug": "string", + "Version": "string", + "ViolationAction": "string", + "ViolationReason": "string" +} +``` +::: + +## Request a paginated set of CompliancePolicyResource sorted by name + +:endpoint{method="GET" path="/api/platformhub/\{gitRef\}/policies"} + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`partialName`** :span[string]{.type-label} +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — A paginated set of CompliancePolicyResource sorted by name + +- **`FilteredItemsCount`** :span[integer]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`Policies`** :span[array of object]{.type-label} + - **`ConditionsRego`** :span[string]{.type-label} + Minimum length 1. + - **`Description`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + Minimum length 1. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`ScopeRego`** :span[string]{.type-label} + Minimum length 1. + - **`Slug`** :span[string]{.type-label} + Minimum length 1. + - **`ViolationAction`** :span[string]{.type-label} + Minimum length 1. + - **`ViolationReason`** :span[string]{.type-label} +- **`TotalItemsCount`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "FilteredItemsCount": 0, + "ItemsPerPage": 0, + "Policies": [ + { + "ConditionsRego": "string", + "Description": "string", + "GitRef": "string", + "Name": "string", + "ScopeRego": "string", + "Slug": "string", + "ViolationAction": "string", + "ViolationReason": "string" + } + ], + "TotalItemsCount": 0 +} +``` +::: + +## Create a new policy + +:endpoint{method="POST" path="/api/platformhub/\{gitRef\}/policies"} + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChangeDescription`** :span[string]{.type-label} +- **`ConditionsRego`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Description`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ScopeRego`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Slug`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ViolationAction`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ViolationReason`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "ChangeDescription": "string", + "ConditionsRego": "string", + "Description": "string", + "GitRef": "string", + "Name": "string", + "ScopeRego": "string", + "Slug": "string", + "ViolationAction": "string", + "ViolationReason": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`ConditionsRego`** :span[string]{.type-label} + Minimum length 1. +- **`Description`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} + Minimum length 1. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ScopeRego`** :span[string]{.type-label} + Minimum length 1. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. +- **`ViolationAction`** :span[string]{.type-label} + Minimum length 1. +- **`ViolationReason`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConditionsRego": "string", + "Description": "string", + "GitRef": "string", + "Name": "string", + "ScopeRego": "string", + "Slug": "string", + "ViolationAction": "string", + "ViolationReason": "string" +} +``` +::: + +## Request a single CompliancePolicyResource by slug and git reference + +:endpoint{method="GET" path="/api/platformhub/\{gitRef\}/policies/\{slug\}"} + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`slug`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Represents a Compliance Policy + +- **`ConditionsRego`** :span[string]{.type-label} + Minimum length 1. +- **`Description`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} + Minimum length 1. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ScopeRego`** :span[string]{.type-label} + Minimum length 1. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. +- **`ViolationAction`** :span[string]{.type-label} + Minimum length 1. +- **`ViolationReason`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConditionsRego": "string", + "Description": "string", + "GitRef": "string", + "Name": "string", + "ScopeRego": "string", + "Slug": "string", + "ViolationAction": "string", + "ViolationReason": "string" +} +``` +::: + +## Modify an existing policy + +:endpoint{method="PUT" path="/api/platformhub/\{gitRef\}/policies/\{slug\}"} + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`slug`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChangeDescription`** :span[string]{.type-label} +- **`ConditionsRego`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Description`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ScopeRego`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Slug`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ViolationAction`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ViolationReason`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "ChangeDescription": "string", + "ConditionsRego": "string", + "Description": "string", + "GitRef": "string", + "Name": "string", + "ScopeRego": "string", + "Slug": "string", + "ViolationAction": "string", + "ViolationReason": "string" +} +``` +::: + +**Response** + +`200` — Represents a Compliance Policy + +- **`ConditionsRego`** :span[string]{.type-label} + Minimum length 1. +- **`Description`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} + Minimum length 1. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ScopeRego`** :span[string]{.type-label} + Minimum length 1. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. +- **`ViolationAction`** :span[string]{.type-label} + Minimum length 1. +- **`ViolationReason`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConditionsRego": "string", + "Description": "string", + "GitRef": "string", + "Name": "string", + "ScopeRego": "string", + "Slug": "string", + "ViolationAction": "string", + "ViolationReason": "string" +} +``` +::: + +## Create new version of policy + +:endpoint{method="POST" path="/api/platformhub/\{gitRef\}/policies/\{slug\}/publish"} + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`slug`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`Slug`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Version`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "GitRef": "string", + "Slug": "string", + "Version": "string" +} +``` +::: + +**Response** + +`200` — The requested policy version + +- **`Description`** :span[string]{.type-label} +- **`GitCommit`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Minimum length 1. +- **`IsActive`** :span[boolean]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`PublishedDate`** :span[string]{.type-label} + Format `date-time`. +- **`RegoConditions`** :span[string]{.type-label} + Minimum length 1. +- **`RegoScope`** :span[string]{.type-label} + Minimum length 1. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. +- **`Version`** :span[string]{.type-label} + Minimum length 1. +- **`ViolationAction`** :span[string]{.type-label} + Minimum length 1. +- **`ViolationReason`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "GitCommit": "string", + "GitRef": "string", + "Id": "string", + "IsActive": true, + "Name": "string", + "PublishedDate": "2020-01-01T00:00:00.000Z", + "RegoConditions": "string", + "RegoScope": "string", + "Slug": "string", + "Version": "string", + "ViolationAction": "string", + "ViolationReason": "string" +} +``` +::: diff --git a/src/pages/docs/api/configuration.md b/src/pages/docs/api/configuration.md new file mode 100644 index 0000000000..042343cef5 --- /dev/null +++ b/src/pages/docs/api/configuration.md @@ -0,0 +1,196 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Configuration +--- + +## Return a list of configuration section settings + +:endpoint{method="GET" path="/api/configuration"} + +**Response** + +`200` — The list of configuration section settings + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "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 +} +``` +::: + +## Return a single configuration section for the given id + +:endpoint{method="GET" path="/api/configuration/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested configuration section + +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" +} +``` +::: + +## Return a structure that describes how to dynamically render the configuration section + +:endpoint{method="GET" path="/api/configuration/\{id\}/metadata"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested configuration section metadata + +- **`Description`** :span[string]{.type-label} +- **`Types`** :span[array of object]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Properties`** :span[array of object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Types": [ + { + "Name": "string", + "Properties": [ + {} + ] + } + ] +} +``` +::: + +## Return the current configuration for a specific configuration section + +:endpoint{method="GET" path="/api/configuration/\{id\}/values"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The current configuration for the specified configuration section + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Update the configuration values for a specific configuration section + +:endpoint{method="PUT" path="/api/configuration/\{id\}/values"} + +Refer to the configuration/{id}/metadata endpoint for details on the specific data structure required for a given configuration section id. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Request Body** + +A `string` payload. + +:::api-example{label="Request"} +```json +"string" +``` +::: + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: diff --git a/src/pages/docs/api/dashboard-configuration.md b/src/pages/docs/api/dashboard-configuration.md new file mode 100644 index 0000000000..a6275f2528 --- /dev/null +++ b/src/pages/docs/api/dashboard-configuration.md @@ -0,0 +1,210 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Dashboard Configuration +--- + +## Get dashboard configuration + +:endpoint{method="GET" path="/api/\{spaceId\}/dashboardconfiguration"} + +Also reachable at `/api/dashboardconfiguration`, `/api/spaces/{spaceIdentifier}/dashboardconfiguration`. + +Gets the dashboard configuration of the authenticated user for the current space + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Dashboard Configuration + +- **`HideInactiveProjects`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IncludedEnvironmentIds`** :span[array of string]{.type-label} +- **`IncludedEnvironmentTags`** :span[array of string]{.type-label} +- **`IncludedProjectGroupIds`** :span[array of string]{.type-label} +- **`IncludedProjectIds`** :span[array of string]{.type-label} +- **`IncludedProjectTags`** :span[array of string]{.type-label} +- **`IncludedTenantIds`** :span[array of string]{.type-label} +- **`IncludedTenantTags`** :span[array of string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectLimit`** :span[integer]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "HideInactiveProjects": true, + "Id": "string", + "IncludedEnvironmentIds": [ + "string" + ], + "IncludedEnvironmentTags": [ + "string" + ], + "IncludedProjectGroupIds": [ + "string" + ], + "IncludedProjectIds": [ + "string" + ], + "IncludedProjectTags": [ + "string" + ], + "IncludedTenantIds": [ + "string" + ], + "IncludedTenantTags": [ + "string" + ], + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectLimit": 0, + "SpaceId": "string" +} +``` +::: + +## Modify dashboard configuration + +:endpoint{method="PUT" path="/api/\{spaceId\}/dashboardconfiguration"} + +Also reachable at `/api/dashboardconfiguration`, `/api/spaces/{spaceIdentifier}/dashboardconfiguration`. + +Modifies the dashboard configuration for the current user per space + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the space for the DashboardConfiguration. + +**Request Body** + +- **`HideInactiveProjects`** :span[boolean]{.type-label} + Whether to hide inactive projects on the dashboard. +- **`IncludedEnvironmentIds`** :span[array of string]{.type-label} + The ids of environments to be displayed on the dashboard. +- **`IncludedEnvironmentTags`** :span[array of string]{.type-label} + The canonical tag names of environments to display on the dashboard. +- **`IncludedProjectGroupIds`** :span[array of string]{.type-label} + The ids of project groups to be displayed on the dashboard. +- **`IncludedProjectIds`** :span[array of string]{.type-label} + The ids of projects to be displayed on the dashboard. +- **`IncludedProjectTags`** :span[array of string]{.type-label} + The canonical tag names of projects to display on the dashboard. +- **`IncludedTenantIds`** :span[array of string]{.type-label} + The ids of tenants to be displayed on the dashboard. +- **`IncludedTenantTags`** :span[array of string]{.type-label} + The canonical tag names to display on the dashboard. +- **`ProjectLimit`** :span[integer]{.type-label} + The maximum number of projects to display on the dashboard. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The id of the space for the DashboardConfiguration. + +:::api-example{label="Request"} +```json +{ + "HideInactiveProjects": true, + "IncludedEnvironmentIds": [ + "string" + ], + "IncludedEnvironmentTags": [ + "string" + ], + "IncludedProjectGroupIds": [ + "string" + ], + "IncludedProjectIds": [ + "string" + ], + "IncludedProjectTags": [ + "string" + ], + "IncludedTenantIds": [ + "string" + ], + "IncludedTenantTags": [ + "string" + ], + "ProjectLimit": 0, + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Dashboard Configuration was modified, containing the new configuration + +- **`HideInactiveProjects`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IncludedEnvironmentIds`** :span[array of string]{.type-label} +- **`IncludedEnvironmentTags`** :span[array of string]{.type-label} +- **`IncludedProjectGroupIds`** :span[array of string]{.type-label} +- **`IncludedProjectIds`** :span[array of string]{.type-label} +- **`IncludedProjectTags`** :span[array of string]{.type-label} +- **`IncludedTenantIds`** :span[array of string]{.type-label} +- **`IncludedTenantTags`** :span[array of string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectLimit`** :span[integer]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "HideInactiveProjects": true, + "Id": "string", + "IncludedEnvironmentIds": [ + "string" + ], + "IncludedEnvironmentTags": [ + "string" + ], + "IncludedProjectGroupIds": [ + "string" + ], + "IncludedProjectIds": [ + "string" + ], + "IncludedProjectTags": [ + "string" + ], + "IncludedTenantIds": [ + "string" + ], + "IncludedTenantTags": [ + "string" + ], + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectLimit": 0, + "SpaceId": "string" +} +``` +::: diff --git a/src/pages/docs/api/dashboard.md b/src/pages/docs/api/dashboard.md new file mode 100644 index 0000000000..addb4abaef --- /dev/null +++ b/src/pages/docs/api/dashboard.md @@ -0,0 +1,517 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Dashboard +--- + +## Return information required to render the Octopus dashboard + +:endpoint{method="GET" path="/api/\{spaceId\}/dashboard"} + +Also reachable at `/api/dashboard`, `/api/spaces/{spaceIdentifier}/dashboard`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`highestLatestVersionPerProjectAndEnvironment`** :span[boolean]{.type-label} +- **`projectId`** :span[string]{.type-label} +- **`releaseId`** :span[string]{.type-label} +- **`selectedTags`** :span[array of string]{.type-label} +- **`selectedTenants`** :span[array of string]{.type-label} +- **`showAll`** :span[boolean]{.type-label} + +**Response** + +`200` — The requested Dashboard + +- **`Environments`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsFiltered`** :span[boolean]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`CompletedTime`** :span[string]{.type-label} + Format `date-time`. + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`DeploymentId`** :span[string]{.type-label} + - **`Duration`** :span[string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ErrorMessage`** :span[string]{.type-label} + - **`HasPendingInterruptions`** :span[boolean]{.type-label} + - **`HasPendingPreconditions`** :span[boolean]{.type-label} + - **`HasWarningsOrErrors`** :span[boolean]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsCompleted`** :span[boolean]{.type-label} + - **`IsCurrent`** :span[boolean]{.type-label} + - **`IsPrevious`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`PendingInterruptionTypes`** :span[array of enum]{.type-label} + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. + - **`PendingPreconditionTypes`** :span[array of string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + Format `date-time`. + - **`ReleaseId`** :span[string]{.type-label} + - **`ReleaseVersion`** :span[string]{.type-label} + - **`StartTime`** :span[string]{.type-label} + Format `date-time`. + - **`State`** :span[enum]{.type-label} + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. + - **`TaskId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectGroups`** :span[array of object]{.type-label} + - **`EnvironmentIds`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} +- **`ProjectLimit`** :span[integer]{.type-label} +- **`Projects`** :span[array of object]{.type-label} + - **`CanPerformUntenantedDeployment`** :span[boolean]{.type-label} + - **`EnvironmentIds`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`ProjectGroupId`** :span[string]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`TenantedDeploymentMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Tenants`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`ProjectEnvironments`** :span[object]{.type-label} + - **`TenantTags`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Environments": [ + { + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } + ], + "Id": "string", + "IsFiltered": true, + "Items": [ + { + "ChannelId": "string", + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Created": "2020-01-01T00:00:00.000Z", + "DeploymentId": "string", + "Duration": "string", + "EnvironmentId": "string", + "ErrorMessage": "string", + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "IsCurrent": true, + "IsPrevious": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "ReleaseId": "string", + "ReleaseVersion": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued", + "TaskId": "string", + "TenantId": "string" + } + ], + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectGroups": [ + { + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } + ], + "ProjectLimit": 0, + "Projects": [ + { + "CanPerformUntenantedDeployment": true, + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectGroupId": "string", + "Slug": "string", + "TenantedDeploymentMode": "Untenanted" + } + ], + "Tenants": [ + { + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectEnvironments": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "TenantTags": [ + "string" + ] + } + ] +} +``` +::: + +## Return the information required to render the dynamic dashboard. Deprecated + +:endpoint{method="GET" path="/api/\{spaceId\}/dashboard/dynamic"} + +Also reachable at `/api/dashboard/dynamic`, `/api/spaces/{spaceIdentifier}/dashboard/dynamic`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`environments`** :span[array of string]{.type-label} +- **`includePrevious`** :span[boolean]{.type-label} +- **`projects`** :span[array of string]{.type-label} + +**Response** + +`200` — The requested Dynamic Dashboared + +- **`Environments`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsFiltered`** :span[boolean]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`CompletedTime`** :span[string]{.type-label} + Format `date-time`. + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`DeploymentId`** :span[string]{.type-label} + - **`Duration`** :span[string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ErrorMessage`** :span[string]{.type-label} + - **`HasPendingInterruptions`** :span[boolean]{.type-label} + - **`HasPendingPreconditions`** :span[boolean]{.type-label} + - **`HasWarningsOrErrors`** :span[boolean]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsCompleted`** :span[boolean]{.type-label} + - **`IsCurrent`** :span[boolean]{.type-label} + - **`IsPrevious`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`PendingInterruptionTypes`** :span[array of enum]{.type-label} + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. + - **`PendingPreconditionTypes`** :span[array of string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + Format `date-time`. + - **`ReleaseId`** :span[string]{.type-label} + - **`ReleaseVersion`** :span[string]{.type-label} + - **`StartTime`** :span[string]{.type-label} + Format `date-time`. + - **`State`** :span[enum]{.type-label} + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. + - **`TaskId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectGroups`** :span[array of object]{.type-label} + - **`EnvironmentIds`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} +- **`ProjectLimit`** :span[integer]{.type-label} +- **`Projects`** :span[array of object]{.type-label} + - **`CanPerformUntenantedDeployment`** :span[boolean]{.type-label} + - **`EnvironmentIds`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`ProjectGroupId`** :span[string]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`TenantedDeploymentMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Tenants`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`ProjectEnvironments`** :span[object]{.type-label} + - **`TenantTags`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Environments": [ + { + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } + ], + "Id": "string", + "IsFiltered": true, + "Items": [ + { + "ChannelId": "string", + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Created": "2020-01-01T00:00:00.000Z", + "DeploymentId": "string", + "Duration": "string", + "EnvironmentId": "string", + "ErrorMessage": "string", + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "IsCurrent": true, + "IsPrevious": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "ReleaseId": "string", + "ReleaseVersion": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued", + "TaskId": "string", + "TenantId": "string" + } + ], + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectGroups": [ + { + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } + ], + "ProjectLimit": 0, + "Projects": [ + { + "CanPerformUntenantedDeployment": true, + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectGroupId": "string", + "Slug": "string", + "TenantedDeploymentMode": "Untenanted" + } + ], + "Tenants": [ + { + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectEnvironments": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "TenantTags": [ + "string" + ] + } + ] +} +``` +::: diff --git a/src/pages/docs/api/deployment-freeze.md b/src/pages/docs/api/deployment-freeze.md new file mode 100644 index 0000000000..615fb83b39 --- /dev/null +++ b/src/pages/docs/api/deployment-freeze.md @@ -0,0 +1,767 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Deployment Freeze +--- + +## Get DeploymentFreezes + +:endpoint{method="GET" path="/api/deploymentfreezes"} + +Gets a paginated set of DeploymentFreezes. + +**Query Parameters** + +- **`effectiveDate`** :span[string]{.type-label} + URL encoded timestamp to search recurring deployment freezes at a given point in time. Format `date-time`. +- **`environmentIds`** :span[array of string]{.type-label} + List of Environment IDs which if specified, filters the result to only include DeploymentFreeze with matching Environment IDs. +- **`ids`** :span[array of string]{.type-label} + List of DeploymentFreeze IDs which if specified, filters the result to only include DeploymentFreeze with matching IDs. +- **`includeComplete`** :span[boolean]{.type-label} + Set to false to only return active Deployment Freezes. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`projectIds`** :span[array of string]{.type-label} + List of Project IDs which if specified, filters the result to only include DeploymentFreeze with matching Project IDs. +- **`skip`** :span[integer]{.type-label} *(required)* + Number of items to skip. Defaults to zero. Minimum `0`. +- **`status`** :span[string]{.type-label} +- **`take`** :span[integer]{.type-label} *(required)* + Number of items to take. Defaults to 30. Minimum `0`. +- **`tenantIds`** :span[array of string]{.type-label} + List of Tenant IDs which if specified, filters the result to only include DeploymentFreeze with matching Tenant IDs. + +**Response** + +`200` — Requested list of DeploymentFreezes + +- **`Count`** :span[integer]{.type-label} +- **`DeploymentFreezes`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`End`** :span[string]{.type-label} + Format `date-time`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`ProjectEnvironmentScope`** :span[object]{.type-label} + - **`RecurringSchedule`** :span[object]{.type-label} + - **`Start`** :span[string]{.type-label} + Format `date-time`. + - **`TenantProjectEnvironmentScope`** :span[array of object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Count": 0, + "DeploymentFreezes": [ + { + "Description": "string", + "End": "2020-01-01T00:00:00.000Z", + "Id": "string", + "Name": "string", + "ProjectEnvironmentScope": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "RecurringSchedule": { + "EndAfterOccurrences": 0, + "EndDate": "2020-01-01T00:00:00.000Z", + "EndOnDate": "2020-01-01T00:00:00.000Z", + "EndType": "Never", + "StartDate": "2020-01-01T00:00:00.000Z", + "Type": "Daily", + "Unit": 0, + "UserUtcOffsetInMinutes": 0 + }, + "Start": "2020-01-01T00:00:00.000Z", + "TenantProjectEnvironmentScope": [ + {} + ] + } + ] +} +``` +::: + +## Create a new deployment freeze + +:endpoint{method="POST" path="/api/deploymentfreezes"} + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`End`** :span[string]{.type-label} *(required)* + Format `date-time`. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. Maximum length 200. +- **`ProjectEnvironmentScope`** :span[object]{.type-label} +- **`Start`** :span[string]{.type-label} *(required)* + Format `date-time`. + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "End": "2020-01-01T00:00:00.000Z", + "Name": "string", + "ProjectEnvironmentScope": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "Start": "2020-01-01T00:00:00.000Z" +} +``` +::: + +**Response** + +`201` — Created + +- **`Description`** :span[string]{.type-label} +- **`End`** :span[string]{.type-label} + Format `date-time`. +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ProjectEnvironmentScope`** :span[object]{.type-label} +- **`RecurringSchedule`** :span[object]{.type-label} + - **`EndAfterOccurrences`** :span[integer]{.type-label} + - **`EndDate`** :span[string]{.type-label} + Format `date-time`. + - **`EndOnDate`** :span[string]{.type-label} + Format `date-time`. + - **`EndType`** :span[enum]{.type-label} + Allowed values: `Never`, `OnDate`, `AfterOccurrences`. + - **`StartDate`** :span[string]{.type-label} + Format `date-time`. + - **`Type`** :span[enum]{.type-label} + Allowed values: `Daily`, `Weekly`, `Monthly`, `Annually`. + - **`Unit`** :span[integer]{.type-label} + - **`UserUtcOffsetInMinutes`** :span[integer]{.type-label} +- **`Start`** :span[string]{.type-label} + Format `date-time`. +- **`TenantProjectEnvironmentScope`** :span[array of object]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "End": "2020-01-01T00:00:00.000Z", + "Id": "string", + "Name": "string", + "ProjectEnvironmentScope": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "RecurringSchedule": { + "EndAfterOccurrences": 0, + "EndDate": "2020-01-01T00:00:00.000Z", + "EndOnDate": "2020-01-01T00:00:00.000Z", + "EndType": "Never", + "StartDate": "2020-01-01T00:00:00.000Z", + "Type": "Daily", + "Unit": 0, + "UserUtcOffsetInMinutes": 0 + }, + "Start": "2020-01-01T00:00:00.000Z", + "TenantProjectEnvironmentScope": [ + { + "EnvironmentId": "string", + "ProjectId": "string", + "TenantId": "string" + } + ] +} +``` +::: + +## Get a deployment freeze by ID + +:endpoint{method="GET" path="/api/deploymentfreezes/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the deployment freeze. + +**Response** + +`200` — The requested deployment freeze + +- **`Description`** :span[string]{.type-label} +- **`End`** :span[string]{.type-label} + Format `date-time`. +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ProjectEnvironmentScope`** :span[object]{.type-label} +- **`RecurringSchedule`** :span[object]{.type-label} + - **`EndAfterOccurrences`** :span[integer]{.type-label} + - **`EndDate`** :span[string]{.type-label} + Format `date-time`. + - **`EndOnDate`** :span[string]{.type-label} + Format `date-time`. + - **`EndType`** :span[enum]{.type-label} + Allowed values: `Never`, `OnDate`, `AfterOccurrences`. + - **`StartDate`** :span[string]{.type-label} + Format `date-time`. + - **`Type`** :span[enum]{.type-label} + Allowed values: `Daily`, `Weekly`, `Monthly`, `Annually`. + - **`Unit`** :span[integer]{.type-label} + - **`UserUtcOffsetInMinutes`** :span[integer]{.type-label} +- **`Start`** :span[string]{.type-label} + Format `date-time`. +- **`TenantProjectEnvironmentScope`** :span[array of object]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "End": "2020-01-01T00:00:00.000Z", + "Id": "string", + "Name": "string", + "ProjectEnvironmentScope": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "RecurringSchedule": { + "EndAfterOccurrences": 0, + "EndDate": "2020-01-01T00:00:00.000Z", + "EndOnDate": "2020-01-01T00:00:00.000Z", + "EndType": "Never", + "StartDate": "2020-01-01T00:00:00.000Z", + "Type": "Daily", + "Unit": 0, + "UserUtcOffsetInMinutes": 0 + }, + "Start": "2020-01-01T00:00:00.000Z", + "TenantProjectEnvironmentScope": [ + { + "EnvironmentId": "string", + "ProjectId": "string", + "TenantId": "string" + } + ] +} +``` +::: + +## Create a new deployment freeze + +:endpoint{method="PUT" path="/api/deploymentfreezes/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`End`** :span[string]{.type-label} *(required)* + Format `date-time`. +- **`Id`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. Maximum length 200. +- **`ProjectEnvironmentScope`** :span[object]{.type-label} +- **`RecurringSchedule`** :span[object]{.type-label} + - **`EndAfterOccurrences`** :span[integer]{.type-label} + - **`EndDate`** :span[string]{.type-label} + Format `date-time`. + - **`EndOnDate`** :span[string]{.type-label} + Format `date-time`. + - **`EndType`** :span[enum]{.type-label} + Allowed values: `Never`, `OnDate`, `AfterOccurrences`. + - **`StartDate`** :span[string]{.type-label} + Format `date-time`. + - **`Type`** :span[enum]{.type-label} + Allowed values: `Daily`, `Weekly`, `Monthly`, `Annually`. + - **`Unit`** :span[integer]{.type-label} + - **`UserUtcOffsetInMinutes`** :span[integer]{.type-label} +- **`Start`** :span[string]{.type-label} *(required)* + Format `date-time`. +- **`TenantProjectEnvironmentScope`** :span[array of object]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} *(required)* + - **`ProjectId`** :span[string]{.type-label} *(required)* + - **`TenantId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "End": "2020-01-01T00:00:00.000Z", + "Id": "string", + "Name": "string", + "ProjectEnvironmentScope": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "RecurringSchedule": { + "EndAfterOccurrences": 0, + "EndDate": "2020-01-01T00:00:00.000Z", + "EndOnDate": "2020-01-01T00:00:00.000Z", + "EndType": "Never", + "StartDate": "2020-01-01T00:00:00.000Z", + "Type": "Daily", + "Unit": 0, + "UserUtcOffsetInMinutes": 0 + }, + "Start": "2020-01-01T00:00:00.000Z", + "TenantProjectEnvironmentScope": [ + { + "EnvironmentId": "string", + "ProjectId": "string", + "TenantId": "string" + } + ] +} +``` +::: + +**Response** + +`200` — Modifies an existing deployment freeze + +- **`Description`** :span[string]{.type-label} +- **`End`** :span[string]{.type-label} + Format `date-time`. +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ProjectEnvironmentScope`** :span[object]{.type-label} +- **`RecurringSchedule`** :span[object]{.type-label} + - **`EndAfterOccurrences`** :span[integer]{.type-label} + - **`EndDate`** :span[string]{.type-label} + Format `date-time`. + - **`EndOnDate`** :span[string]{.type-label} + Format `date-time`. + - **`EndType`** :span[enum]{.type-label} + Allowed values: `Never`, `OnDate`, `AfterOccurrences`. + - **`StartDate`** :span[string]{.type-label} + Format `date-time`. + - **`Type`** :span[enum]{.type-label} + Allowed values: `Daily`, `Weekly`, `Monthly`, `Annually`. + - **`Unit`** :span[integer]{.type-label} + - **`UserUtcOffsetInMinutes`** :span[integer]{.type-label} +- **`Start`** :span[string]{.type-label} + Format `date-time`. +- **`TenantProjectEnvironmentScope`** :span[array of object]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "End": "2020-01-01T00:00:00.000Z", + "Id": "string", + "Name": "string", + "ProjectEnvironmentScope": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "RecurringSchedule": { + "EndAfterOccurrences": 0, + "EndDate": "2020-01-01T00:00:00.000Z", + "EndOnDate": "2020-01-01T00:00:00.000Z", + "EndType": "Never", + "StartDate": "2020-01-01T00:00:00.000Z", + "Type": "Daily", + "Unit": 0, + "UserUtcOffsetInMinutes": 0 + }, + "Start": "2020-01-01T00:00:00.000Z", + "TenantProjectEnvironmentScope": [ + { + "EnvironmentId": "string", + "ProjectId": "string", + "TenantId": "string" + } + ] +} +``` +::: + +## Delete a deployment freeze + +:endpoint{method="DELETE" path="/api/deploymentfreezes/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the DeploymentFreeze to delete. + +**Response** + +`200` — Success + +## Override a deployment freeze to create a deployment + +:endpoint{method="POST" path="/api/\{spaceId\}/deployments/override"} + +Also reachable at `/api/deployments/override`, `/api/spaces/{spaceIdentifier}/deployments/override`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`CreateDeploymentCommand`** :span[object]{.type-label} *(required)* + - **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Changes`** :span[array of object]{.type-label} + - **`ChangesMarkdown`** :span[string]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`Comments`** :span[string]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`DebugMode`** :span[string]{.type-label} + - **`DeployedBy`** :span[string]{.type-label} + - **`DeployedById`** :span[string]{.type-label} + - **`DeployedToMachineIds`** :span[array of string]{.type-label} + - **`DeploymentProcessId`** :span[string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} *(required)* + - **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. + - **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`FailureEncountered`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`ForcePackageRedeployment`** :span[boolean]{.type-label} + - **`FormValues`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ManifestVariableSetId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Priority`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. + - **`ReleaseId`** :span[string]{.type-label} *(required)* + - **`SkipActions`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. + - **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`TaskId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + - **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. +- **`FreezeIds`** :span[array of string]{.type-label} *(required)* +- **`Reason`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "CreateDeploymentCommand": { + "ChangeRequestSettings": [ + { + "Type": "ServiceNow" + } + ], + "Changes": [ + { + "BuildInformation": [ + {} + ], + "Commits": [ + {} + ], + "ReleaseNotes": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChangesMarkdown": "string", + "ChannelId": "string", + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "DeploymentProcessId": "string", + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + {} + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "ForcePackageRedeployment": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ReleaseId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true + }, + "FreezeIds": [ + "string" + ], + "Reason": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Deployment`** :span[object]{.type-label} + - **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Changes`** :span[array of object]{.type-label} + - **`ChangesMarkdown`** :span[string]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`Comments`** :span[string]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`DebugMode`** :span[string]{.type-label} + - **`DeployedBy`** :span[string]{.type-label} + - **`DeployedById`** :span[string]{.type-label} + - **`DeployedToMachineIds`** :span[array of string]{.type-label} + - **`DeploymentProcessId`** :span[string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. + - **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`FailureEncountered`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`ForcePackageRedeployment`** :span[boolean]{.type-label} + - **`FormValues`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ManifestVariableSetId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Priority`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. + - **`ReleaseId`** :span[string]{.type-label} + - **`SkipActions`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. + - **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`TaskId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + - **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. + +:::api-example{label="Response"} +```json +{ + "Deployment": { + "ChangeRequestSettings": [ + { + "Type": "ServiceNow" + } + ], + "Changes": [ + { + "BuildInformation": [ + {} + ], + "Commits": [ + {} + ], + "ReleaseNotes": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChangesMarkdown": "string", + "ChannelId": "string", + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "DeploymentProcessId": "string", + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + {} + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "ForcePackageRedeployment": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ReleaseId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true + } +} +``` +::: diff --git a/src/pages/docs/api/deployment-processes.md b/src/pages/docs/api/deployment-processes.md new file mode 100644 index 0000000000..2fdee89986 --- /dev/null +++ b/src/pages/docs/api/deployment-processes.md @@ -0,0 +1,1396 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Deployment Processes +--- + +## List all the deployment processes + +:endpoint{method="GET" path="/api/\{spaceId\}/deploymentprocesses"} + +Also reachable at `/api/deploymentprocesses`, `/api/spaces/{spaceIdentifier}/deploymentprocesses`. + +Lists all the deployment processes in the supplied Octopus Deploy Space, sorted by Id. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + A list of DeploymentProcess IDs, to limit the matching of DeploymentProcesses to those with a particular ID. Example: ["deploymentprocess-Projects-1", "deploymentprocess-Projects-2"]. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested list of Deployment Processes + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastSnapshotId`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ProjectId`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Steps`** :span[array of object]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "SpaceId": "string", + "Steps": [ + {} + ], + "Version": 0 + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get a Release Snapshot Template + +:endpoint{method="GET" path="/api/\{spaceId\}/deploymentprocesses/\{deploymentProcessId\}/template"} + +Also reachable at `/api/deploymentprocesses/{deploymentProcessId}/template`, `/api/spaces/{spaceIdentifier}/deploymentprocesses/{deploymentProcessId}/template`. + +**Path Parameters** + +- **`deploymentProcessId`** :span[string]{.type-label} *(required)* + The ID of the Deployment Process to use. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`channel`** :span[string]{.type-label} + The channel ID to get the channel from. +- **`releaseId`** :span[string]{.type-label} + The ID of the release to get variables from. + +**Response** + +`200` — The requested Release Template. + +- **`DeploymentProcessId`** :span[string]{.type-label} +- **`GitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`GitResourceSelectedLastRelease`** :span[object]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastReleaseVersion`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NextVersionIncrement`** :span[string]{.type-label} +- **`Packages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`FeedId`** :span[string]{.type-label} + - **`FeedName`** :span[string]{.type-label} + - **`FixedVersion`** :span[string]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + - **`NuGetFeedName`** :span[string]{.type-label} + - **`NuGetPackageId`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`VersionSelectedLastRelease`** :span[string]{.type-label} +- **`VersioningPackageReferenceName`** :span[string]{.type-label} +- **`VersioningPackageStepName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DeploymentProcessId": "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", + "LastReleaseVersion": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NextVersionIncrement": "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" + } + ], + "VersioningPackageReferenceName": "string", + "VersioningPackageStepName": "string" +} +``` +::: + +## Get a specific snapshotted version of a deployment process + +:endpoint{method="GET" path="/api/\{spaceId\}/deploymentprocesses/\{id\}"} + +Also reachable at `/api/deploymentprocesses/{id}`, `/api/spaces/{spaceIdentifier}/deploymentprocesses/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the snapshotted deployment process, for example "deploymentprocess-Projects-1-s-4-ABCDE". +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Get a specific snapshotted version of a deployment process + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +## Get the deployment process for a project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/deploymentprocesses"} + +Also reachable at `/api/projects/{projectId}/deploymentprocesses`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/deploymentprocesses`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Contains the deployment process for a project + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +## Modify a deployment process + +:endpoint{method="PUT" path="/api/\{spaceId\}/projects/\{projectId\}/deploymentprocesses"} + +Also reachable at `/api/projects/{projectId}/deploymentprocesses`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/deploymentprocesses`. + +Modifies a deployment process. Only allowed for deployment processes owned by a project (cannot be used to change the deployment process owned by a release). + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChangeDescription`** :span[string]{.type-label} +- **`LastSnapshotId`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`Steps`** :span[array of object]{.type-label} *(required)* + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "ChangeDescription": "string", + "LastSnapshotId": "string", + "ProjectId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +**Response** + +`200` — Confirmation that the Deployment Process has been modified, containing the new Process + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +## Get the resolved deployment process for a project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/deploymentprocesses/resolved"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/deploymentprocesses/resolved`. + +This request returns the deployment process with all process template usages resolved out to the deployment steps that are executed. If a process template usage cannot be resolved (e.g. if the process template is no longer shared with the space), the usage will be excluded from the response. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The deployment process for a project + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +## Get all of the information necessary for creating or editing a release using this deployment process + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/deploymentprocesses/template"} + +Also reachable at `/api/projects/{projectId}/deploymentprocesses/template`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/deploymentprocesses/template`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the Project to use. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`channel`** :span[string]{.type-label} + The channel ID to get the channel from. +- **`releaseId`** :span[string]{.type-label} + The ID of the release to get variables from. + +**Response** + +`200` — The requested Release Template + +- **`DeploymentProcessId`** :span[string]{.type-label} +- **`GitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`GitResourceSelectedLastRelease`** :span[object]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastReleaseVersion`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NextVersionIncrement`** :span[string]{.type-label} +- **`Packages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`FeedId`** :span[string]{.type-label} + - **`FeedName`** :span[string]{.type-label} + - **`FixedVersion`** :span[string]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + - **`NuGetFeedName`** :span[string]{.type-label} + - **`NuGetPackageId`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`VersionSelectedLastRelease`** :span[string]{.type-label} +- **`VersioningPackageReferenceName`** :span[string]{.type-label} +- **`VersioningPackageStepName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DeploymentProcessId": "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", + "LastReleaseVersion": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NextVersionIncrement": "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" + } + ], + "VersioningPackageReferenceName": "string", + "VersioningPackageStepName": "string" +} +``` +::: + +## Validate the deployment process for common non-blocking issues, such as missing deployment targets for tags used within the process steps + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/deploymentprocesses/validate"} + +Also reachable at `/api/projects/{projectId}/deploymentprocesses/validate`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/deploymentprocesses/validate`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Contains the result of validation, such as warnings for the deployment process + +- **`Details`** :span[object]{.type-label} +- **`HasWarnings`** :span[boolean]{.type-label} +- **`TagsWithoutTargetsByStepId`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Details": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HasWarnings": true, + "TagsWithoutTargetsByStepId": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + } +} +``` +::: + +## Get the deployment process for a version-controlled project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/deploymentprocesses"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/deploymentprocesses`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/deploymentprocesses`. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Contains the deployment process for a project + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +## Modify a deployment process + +:endpoint{method="PUT" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/deploymentprocesses"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/deploymentprocesses`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/deploymentprocesses`. + +Modifies a deployment process. Only allowed for deployment processes owned by a project (cannot be used to change the deployment process owned by a release). + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChangeDescription`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`LastSnapshotId`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`Steps`** :span[array of object]{.type-label} *(required)* + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "ChangeDescription": "string", + "GitRef": "string", + "LastSnapshotId": "string", + "ProjectId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +**Response** + +`200` — Confirmation that the Deployment Process has been modified, containing the new Process + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +## Get the resolved deployment process for a version-controlled project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/deploymentprocesses/resolved"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/deploymentprocesses/resolved`. + +This request returns the deployment process with all process template usages resolved out to the deployment steps that are executed. If a process template usage cannot be resolved (e.g. if the process template is no longer shared with the space), the usage will be excluded from the response. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The deployment process for a project + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +## Get all of the information necessary for creating or editing a release using this deployment process + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/deploymentprocesses/template"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/deploymentprocesses/template`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/deploymentprocesses/template`. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* + GitRef for the project variables. +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the Project to use. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`channel`** :span[string]{.type-label} + The channel ID to get the channel from. +- **`releaseId`** :span[string]{.type-label} + The ID of the release to get variables from. + +**Response** + +`200` — The requested Release Template + +- **`DeploymentProcessId`** :span[string]{.type-label} +- **`GitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`GitResourceSelectedLastRelease`** :span[object]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastReleaseVersion`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NextVersionIncrement`** :span[string]{.type-label} +- **`Packages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`FeedId`** :span[string]{.type-label} + - **`FeedName`** :span[string]{.type-label} + - **`FixedVersion`** :span[string]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + - **`NuGetFeedName`** :span[string]{.type-label} + - **`NuGetPackageId`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`VersionSelectedLastRelease`** :span[string]{.type-label} +- **`VersioningPackageReferenceName`** :span[string]{.type-label} +- **`VersioningPackageStepName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DeploymentProcessId": "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", + "LastReleaseVersion": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NextVersionIncrement": "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" + } + ], + "VersioningPackageReferenceName": "string", + "VersioningPackageStepName": "string" +} +``` +::: + +## Validate the deployment process for common non-blocking issues, such as missing deployment targets for tags used within the process steps + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/deploymentprocesses/validate"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/deploymentprocesses/validate`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/deploymentprocesses/validate`. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Contains the result of validation, such as warnings for the deployment process + +- **`Details`** :span[object]{.type-label} +- **`HasWarnings`** :span[boolean]{.type-label} +- **`TagsWithoutTargetsByStepId`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Details": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HasWarnings": true, + "TagsWithoutTargetsByStepId": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + } +} +``` +::: + +## Modify a deployment process + +:endpoint{method="PUT" path="/api/\{spaceId\}/deploymentprocesses/\{id\}" deprecated=true} + +Also reachable at `/api/deploymentprocesses/{id}`, `/api/spaces/{spaceIdentifier}/deploymentprocesses/{id}`. + +:::div{.warning} +**Deprecated.** This endpoint may be removed in a future release. +::: + +Modifies a deployment process. Only allowed for deployment processes owned by a project (cannot be used to change the deployment process owned by a release). + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the deployment process to update. Example `deploymentprocess-Projects-1`. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} *(required)* + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +**Response** + +`200` — Success + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: diff --git a/src/pages/docs/api/deployment-settings.md b/src/pages/docs/api/deployment-settings.md new file mode 100644 index 0000000000..c48d232881 --- /dev/null +++ b/src/pages/docs/api/deployment-settings.md @@ -0,0 +1,587 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Deployment Settings +--- + +## Get deployment settings by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/deploymentsettings"} + +Also reachable at `/api/projects/{projectId}/deploymentsettings`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/deploymentsettings`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + The Project ID to get the deployment settings from. Example `Projects-1`. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested Deployment Settings. + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} +- **`CancelRunningTasks`** :span[boolean]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} +- **`DeploymentChangesTemplate`** :span[string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`ReleaseNotesTemplate`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`VersioningStrategy`** :span[object]{.type-label} + - **`DonorPackage`** :span[object]{.type-label} + - **`Template`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CancelQueuedTasks": true, + "CancelRunningTasks": true, + "ConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "FailTargetDiscovery": true, + "ForcePackageDownload": true, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ReleaseNotesTemplate": "string", + "SpaceId": "string", + "VersioningStrategy": { + "DonorPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + }, + "Template": "string" + } +} +``` +::: + +## Get deployment settings by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/deploymentsettings"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/deploymentsettings`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/deploymentsettings`. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* + The Project ID to get the deployment settings from. Example `Projects-1`. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested Deployment Settings. + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} +- **`CancelRunningTasks`** :span[boolean]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} +- **`DeploymentChangesTemplate`** :span[string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`ReleaseNotesTemplate`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`VersioningStrategy`** :span[object]{.type-label} + - **`DonorPackage`** :span[object]{.type-label} + - **`Template`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CancelQueuedTasks": true, + "CancelRunningTasks": true, + "ConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "FailTargetDiscovery": true, + "ForcePackageDownload": true, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ReleaseNotesTemplate": "string", + "SpaceId": "string", + "VersioningStrategy": { + "DonorPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + }, + "Template": "string" + } +} +``` +::: + +## Modify deployment settings + +:endpoint{method="PUT" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/deploymentsettings"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/deploymentsettings`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/deploymentsettings`. + +Modifies deployment settings for a project. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* + Git reference to use when modifying deployment settings. +- **`projectId`** :span[string]{.type-label} *(required)* + The Project ID to get the deployment settings from. Example `Projects-1`. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} + When enabled, creating a new deployment will cancel all previously queued deployments to the same project/environment/tenant. +- **`CancelRunningTasks`** :span[boolean]{.type-label} + When enabled, completing a deployment will cancel older running or paused deployments to the same project/environment/tenant. +- **`ChangeDescription`** :span[string]{.type-label} + Used as the Git commit message. Omit to use the default message 'Update deployment settings'. +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + The action related to when a deployment error occurs. (IE: Enabling guided failure will pause the deployment failure to allow error correction before proceeding). + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} + If true, and the version of the package being deployed is already present on the machine, its re-deployment will be skipped. +- **`DeploymentChangesTemplate`** :span[string]{.type-label} + A markdown template generated for each deployment's changes. +- **`FailTargetDiscovery`** :span[boolean]{.type-label} + Option to fail a step if no matching targets found in cloud discovery steps. +- **`ForcePackageDownload`** :span[boolean]{.type-label} + Option to force re-downloading packages for deployment. +- **`GitRef`** :span[string]{.type-label} *(required)* + Git reference to use when modifying deployment settings. +- **`ProjectId`** :span[string]{.type-label} *(required)* + The Project ID to get the deployment settings from. Example `Projects-1`. +- **`ReleaseNotesTemplate`** :span[string]{.type-label} + Template text pre-filled as the release notes when a release of this project is created; may contain Octopus variable expressions. Omitting this clears the project's existing template. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`VersioningStrategy`** :span[object]{.type-label} + - **`DonorPackage`** :span[object]{.type-label} + - **`Template`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "CancelQueuedTasks": true, + "CancelRunningTasks": true, + "ChangeDescription": "string", + "ConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "FailTargetDiscovery": true, + "ForcePackageDownload": true, + "GitRef": "string", + "ProjectId": "string", + "ReleaseNotesTemplate": "string", + "SpaceId": "string", + "VersioningStrategy": { + "DonorPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + }, + "Template": "string" + } +} +``` +::: + +**Response** + +`200` — Confirmation that the Deployment Settings were modified, contains the updated Deployment Settings + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} +- **`CancelRunningTasks`** :span[boolean]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} +- **`DeploymentChangesTemplate`** :span[string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`ReleaseNotesTemplate`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`VersioningStrategy`** :span[object]{.type-label} + - **`DonorPackage`** :span[object]{.type-label} + - **`Template`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CancelQueuedTasks": true, + "CancelRunningTasks": true, + "ConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "FailTargetDiscovery": true, + "ForcePackageDownload": true, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ReleaseNotesTemplate": "string", + "SpaceId": "string", + "VersioningStrategy": { + "DonorPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + }, + "Template": "string" + } +} +``` +::: + +## Get deployment settings by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/deploymentsettings/\{id\}" deprecated=true} + +Also reachable at `/api/deploymentsettings/{id}`, `/api/spaces/{spaceIdentifier}/deploymentsettings/{id}`. + +:::div{.warning} +**Deprecated.** This endpoint may be removed in a future release. +::: + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the DeploymentSettings to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} +- **`CancelRunningTasks`** :span[boolean]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} +- **`DeploymentChangesTemplate`** :span[string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`ReleaseNotesTemplate`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`VersioningStrategy`** :span[object]{.type-label} + - **`DonorPackage`** :span[object]{.type-label} + - **`Template`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CancelQueuedTasks": true, + "CancelRunningTasks": true, + "ConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "FailTargetDiscovery": true, + "ForcePackageDownload": true, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ReleaseNotesTemplate": "string", + "SpaceId": "string", + "VersioningStrategy": { + "DonorPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + }, + "Template": "string" + } +} +``` +::: + +## Modify deployment settings + +:endpoint{method="PUT" path="/api/\{spaceId\}/deploymentsettings/\{projectId\}" deprecated=true} + +Also reachable at `/api/deploymentsettings/{projectId}`, `/api/projects/{projectId}/deploymentsettings`, `/api/spaces/{spaceIdentifier}/deploymentsettings/{projectId}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/deploymentsettings`, `/api/{spaceId}/projects/{projectId}/deploymentsettings`. + +:::div{.warning} +**Deprecated.** This endpoint may be removed in a future release. +::: + +Modifies deployment settings for a project. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + The Project ID to get the deployment settings from. Example `Projects-1`. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} + When enabled, creating a new deployment will cancel all previously queued deployments to the same project/environment/tenant. +- **`CancelRunningTasks`** :span[boolean]{.type-label} + When enabled, completing a deployment will cancel older running or paused deployments to the same project/environment/tenant. +- **`ChangeDescription`** :span[string]{.type-label} + The description for the deployment settings modification. +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + The action related to when a deployment error occurs. (IE: Enabling guided failure will pause the deployment failure to allow error correction before proceeding). + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} + If true, and the version of the package being deployed is already present on the machine, its re-deployment will be skipped. +- **`DeploymentChangesTemplate`** :span[string]{.type-label} + A markdown template generated for each deployment's changes. +- **`FailTargetDiscovery`** :span[boolean]{.type-label} + Fail cloud discovery steps if no targets found. +- **`ForcePackageDownload`** :span[boolean]{.type-label} + Option to force re-downloading packages for deployment. +- **`ProjectId`** :span[string]{.type-label} *(required)* + The Project ID to get the deployment settings from. Example `Projects-1`. +- **`ReleaseNotesTemplate`** :span[string]{.type-label} + Template text pre-filled as the release notes when a release of this project is created; may contain Octopus variable expressions. Omitting this clears the project's existing template. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`VersioningStrategy`** :span[object]{.type-label} + - **`DonorPackage`** :span[object]{.type-label} + - **`Template`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "CancelQueuedTasks": true, + "CancelRunningTasks": true, + "ChangeDescription": "string", + "ConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "FailTargetDiscovery": true, + "ForcePackageDownload": true, + "ProjectId": "string", + "ReleaseNotesTemplate": "string", + "SpaceId": "string", + "VersioningStrategy": { + "DonorPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + }, + "Template": "string" + } +} +``` +::: + +**Response** + +`200` — Confirmation that the Deployment Settings were modified, contains the updated Deployment Settings + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} +- **`CancelRunningTasks`** :span[boolean]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} +- **`DeploymentChangesTemplate`** :span[string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`ReleaseNotesTemplate`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`VersioningStrategy`** :span[object]{.type-label} + - **`DonorPackage`** :span[object]{.type-label} + - **`Template`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CancelQueuedTasks": true, + "CancelRunningTasks": true, + "ConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "FailTargetDiscovery": true, + "ForcePackageDownload": true, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ReleaseNotesTemplate": "string", + "SpaceId": "string", + "VersioningStrategy": { + "DonorPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + }, + "Template": "string" + } +} +``` +::: diff --git a/src/pages/docs/api/deployment-target-tags.md b/src/pages/docs/api/deployment-target-tags.md new file mode 100644 index 0000000000..6e7b07a373 --- /dev/null +++ b/src/pages/docs/api/deployment-target-tags.md @@ -0,0 +1,142 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Deployment Target Tags +--- + +## Get a DeploymentTargetTag by ID or Slug + +:endpoint{method="GET" path="/api/\{spaceId\}/deploymentTargetTags/\{tag\}"} + +Also reachable at `/api/deploymentTargetTags/{tag}`, `/api/spaces/{spaceIdentifier}/deploymentTargetTags/{tag}`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`tag`** :span[string]{.type-label} *(required)* + ID or Slug of the DeploymentTargetTag. + +**Response** + +`200` — The requested DeploymentTargetTag + +- **`SpaceId`** :span[string]{.type-label} +- **`Tag`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "SpaceId": "string", + "Tag": "string" +} +``` +::: + +## Get DeploymentTargetTags by DeploymentTargetTag IDs and Machine ID (deployment target ID) + +:endpoint{method="GET" path="/api/\{spaceId\}/deploymenttargettags"} + +Also reachable at `/api/deploymenttargettags`, `/api/spaces/{spaceIdentifier}/deploymenttargettags`. + +Gets a paginated list of DeploymentTargetTag. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the Space to which the DeploymentTargetTags belong. + +**Query Parameters** + +- **`machineIds`** :span[array of string]{.type-label} + The Machine ID to filter by. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`tags`** :span[array of string]{.type-label} + The DeploymentTargetTag IDs to filter by. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested DeploymentTargetTags. + +- **`Count`** :span[integer]{.type-label} +- **`DeploymentTargetTags`** :span[array of object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Tag`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Count": 0, + "DeploymentTargetTags": [ + { + "SpaceId": "string", + "Tag": "string" + } + ] +} +``` +::: + +## Create a new DeploymentTargetTag + +:endpoint{method="POST" path="/api/\{spaceId\}/deploymenttargettags"} + +Also reachable at `/api/deploymenttargettags`, `/api/spaces/{spaceIdentifier}/deploymenttargettags`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space for the DeploymentTargetTag. + +**Request Body** + +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space for the DeploymentTargetTag. +- **`Tag`** :span[string]{.type-label} *(required)* + The name or tag of the DeploymentTargetTag. Minimum length 1. Maximum length 200. + +:::api-example{label="Request"} +```json +{ + "SpaceId": "string", + "Tag": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`SpaceId`** :span[string]{.type-label} +- **`Tag`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "SpaceId": "string", + "Tag": "string" +} +``` +::: + +## Delete a DeploymentTargetTag + +:endpoint{method="DELETE" path="/api/\{spaceId\}/deploymenttargettags/\{tag\}"} + +Also reachable at `/api/deploymenttargettags/{tag}`, `/api/spaces/{spaceIdentifier}/deploymenttargettags/{tag}`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`tag`** :span[string]{.type-label} *(required)* + The Tag of the DeploymentTargetTag to delete. + +**Response** + +`200` — Success diff --git a/src/pages/docs/api/deployment-targets.md b/src/pages/docs/api/deployment-targets.md new file mode 100644 index 0000000000..6db0fe2c0c --- /dev/null +++ b/src/pages/docs/api/deployment-targets.md @@ -0,0 +1,1596 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Deployment Targets +--- + +## List all of the registered machines in the supplied Octopus Deploy Space, from all environments. The results will be sorted alphabetically by name + +:endpoint{method="GET" path="/api/\{spaceId\}/machines"} + +Also reachable at `/api/machines`, `/api/spaces/{spaceIdentifier}/machines`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`commStyles`** :span[array of string]{.type-label} + List of communication styles which if specified, filters the result to only include Deployment Targets with matching communication styles. +- **`deploymentTargetTypes`** :span[array of string]{.type-label} + List of deployment target types which if specified, filters the result to only include Deployment Targets with matching types. +- **`environmentIds`** :span[array of string]{.type-label} + List of Environment IDs which if specified, filters the result to only include Deployment Targets with matching Environment IDs. +- **`healthStatuses`** :span[array of string]{.type-label} + List of health statuses which if specified, filters the result to only include Deployment Targets with matching health statuses. +- **`ids`** :span[array of string]{.type-label} + List of Deployment Target IDs which if specified, filters the result to only include Deployment Targets with matching IDs. +- **`isDisabled`** :span[boolean]{.type-label} + A filter to return only disabled/enabled Deployment Targets. +- **`name`** :span[string]{.type-label} + The exact name of a deployment target to be matched. +- **`operatingSystemNames`** :span[array of string]{.type-label} + List of operating system names which if specified, filters the result to only include Deployment Targets with matching operating systems. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`roles`** :span[array of string]{.type-label} + List of roles which if specified, filters the result to only include Deployment Targets with matching roles. +- **`shellNames`** :span[array of string]{.type-label} + List of shell names which if specified, filters the result to only include Deployment Targets with matching shells. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`targetTags`** :span[array of string]{.type-label} + List of Target Tags which if specified, filters the result to only include Deployment Targets with matching Target Tags. +- **`tenantIds`** :span[array of string]{.type-label} + List of Tenant IDs which if specified, filters the result to only include Deployment Targets with matching Tenant IDs. +- **`tenantTags`** :span[array of string]{.type-label} + List of Tenant Tags which if specified, filters the result to only include Deployment Targets with matching Tenant Tags. + +**Response** + +`200` — The list of alphabetically sorted deployment targets that matched the request. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Architecture`** :span[string]{.type-label} + - **`Endpoint`** :span[object]{.type-label} + - **`EnvironmentIds`** :span[array of string]{.type-label} + - **`HasLatestCalamari`** :span[boolean]{.type-label} + - **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`IsInProcess`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MachinePolicyId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OperatingSystem`** :span[string]{.type-label} + - **`OperatingSystemVersion`** :span[string]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`ShellName`** :span[string]{.type-label} + - **`ShellVersion`** :span[string]{.type-label} + - **`SkipInitialHealthCheck`** :span[boolean]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`StatusSummary`** :span[string]{.type-label} + - **`TenantIds`** :span[array of string]{.type-label} + - **`TenantTags`** :span[array of string]{.type-label} + - **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + - **`Thumbprint`** :span[string]{.type-label} + - **`Uri`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {} + }, + "EnvironmentIds": [ + "string" + ], + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "Roles": [ + "string" + ], + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Uri": "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 +} +``` +::: + +## Create a MachineResource + +:endpoint{method="POST" path="/api/\{spaceId\}/machines"} + +Also reachable at `/api/machines`, `/api/spaces/{spaceIdentifier}/machines`. + +Creates a new deployment target. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Endpoint`** :span[object]{.type-label} + - **`CommunicationStyle`** :span[enum]{.type-label} + This is for legacy support in client. Server no longer uses this for determining endpoint types, it uses DeploymentTargetType. + Allowed values: `None`, `TentaclePassive`, `TentacleActive`, `Ssh`, `OfflineDrop`, `AzureWebApp`, `Ftp`, `AzureCloudService`, `AzureServiceFabricCluster`, `Kubernetes`, `StepPackage`, `KubernetesTentacle`, `AwsEcsCluster`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`EnvironmentIds`** :span[array of string]{.type-label} *(required)* +- **`IsDisabled`** :span[boolean]{.type-label} +- **`MachinePolicyId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Roles`** :span[array of string]{.type-label} *(required)* +- **`SkipInitialHealthCheck`** :span[boolean]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Thumbprint`** :span[string]{.type-label} +- **`Uri`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "EnvironmentIds": [ + "string" + ], + "IsDisabled": true, + "MachinePolicyId": "string", + "Name": "string", + "Roles": [ + "string" + ], + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Uri": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Architecture`** :span[string]{.type-label} +- **`Endpoint`** :span[object]{.type-label} + - **`CommunicationStyle`** :span[enum]{.type-label} + This is for legacy support in client. Server no longer uses this for determining endpoint types, it uses DeploymentTargetType. + Allowed values: `None`, `TentaclePassive`, `TentacleActive`, `Ssh`, `OfflineDrop`, `AzureWebApp`, `Ftp`, `AzureCloudService`, `AzureServiceFabricCluster`, `Kubernetes`, `StepPackage`, `KubernetesTentacle`, `AwsEcsCluster`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`HasLatestCalamari`** :span[boolean]{.type-label} +- **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsInProcess`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachinePolicyId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`OperatingSystem`** :span[string]{.type-label} +- **`OperatingSystemVersion`** :span[string]{.type-label} +- **`Roles`** :span[array of string]{.type-label} +- **`ShellName`** :span[string]{.type-label} +- **`ShellVersion`** :span[string]{.type-label} +- **`SkipInitialHealthCheck`** :span[boolean]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`StatusSummary`** :span[string]{.type-label} +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Thumbprint`** :span[string]{.type-label} +- **`Uri`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "EnvironmentIds": [ + "string" + ], + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "Roles": [ + "string" + ], + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Uri": "string" +} +``` +::: + +## Get a list of Deployment Targets + +:endpoint{method="GET" path="/api/\{spaceId\}/machines/all"} + +Also reachable at `/api/machines/all`, `/api/spaces/{spaceIdentifier}/machines/all`. + +Lists all of the Deployment Targets in the supplied Space. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + A comma separated list of Machine resource ids used to filter a query. +- **`thumbprint`** :span[string]{.type-label} + A thumbprint used to filter a query. + +**Response** + +`200` — Requested list of Deployment Targets + +- **`Architecture`** :span[string]{.type-label} +- **`Endpoint`** :span[object]{.type-label} + - **`CommunicationStyle`** :span[enum]{.type-label} + This is for legacy support in client. Server no longer uses this for determining endpoint types, it uses DeploymentTargetType. + Allowed values: `None`, `TentaclePassive`, `TentacleActive`, `Ssh`, `OfflineDrop`, `AzureWebApp`, `Ftp`, `AzureCloudService`, `AzureServiceFabricCluster`, `Kubernetes`, `StepPackage`, `KubernetesTentacle`, `AwsEcsCluster`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`HasLatestCalamari`** :span[boolean]{.type-label} +- **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsInProcess`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachinePolicyId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`OperatingSystem`** :span[string]{.type-label} +- **`OperatingSystemVersion`** :span[string]{.type-label} +- **`Roles`** :span[array of string]{.type-label} +- **`ShellName`** :span[string]{.type-label} +- **`ShellVersion`** :span[string]{.type-label} +- **`SkipInitialHealthCheck`** :span[boolean]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`StatusSummary`** :span[string]{.type-label} +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Thumbprint`** :span[string]{.type-label} +- **`Uri`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "EnvironmentIds": [ + "string" + ], + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "Roles": [ + "string" + ], + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Uri": "string" + } +] +``` +::: + +## Get a list of Deployment Targets + +:endpoint{method="GET" path="/api/\{spaceId\}/machines/all/v1"} + +Also reachable at `/api/machines/all/v1`, `/api/spaces/{spaceIdentifier}/machines/all/v1`. + +Lists all of the Deployment Targets in the supplied Space. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + A comma separated list of Machine resource ids used to filter a query. +- **`thumbprint`** :span[string]{.type-label} + A thumbprint used to filter a query. + +**Response** + +`200` — Requested list of Deployment Targets + +- **`DeploymentTargets`** :span[array of object]{.type-label} + - **`Architecture`** :span[string]{.type-label} + - **`Endpoint`** :span[object]{.type-label} + - **`EnvironmentIds`** :span[array of string]{.type-label} + - **`HasLatestCalamari`** :span[boolean]{.type-label} + - **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`IsInProcess`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MachinePolicyId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OperatingSystem`** :span[string]{.type-label} + - **`OperatingSystemVersion`** :span[string]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`ShellName`** :span[string]{.type-label} + - **`ShellVersion`** :span[string]{.type-label} + - **`SkipInitialHealthCheck`** :span[boolean]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`StatusSummary`** :span[string]{.type-label} + - **`TenantIds`** :span[array of string]{.type-label} + - **`TenantTags`** :span[array of string]{.type-label} + - **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + - **`Thumbprint`** :span[string]{.type-label} + - **`Uri`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DeploymentTargets": [ + { + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {} + }, + "EnvironmentIds": [ + "string" + ], + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "Roles": [ + "string" + ], + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Uri": "string" + } + ] +} +``` +::: + +## Interrogate a deployment target for communication details so that it may be added to the installation + +:endpoint{method="GET" path="/api/\{spaceId\}/machines/discover"} + +Also reachable at `/api/machines/discover`, `/api/spaces/{spaceIdentifier}/machines/discover`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`host`** :span[string]{.type-label} *(required)* +- **`port`** :span[integer]{.type-label} +- **`proxyId`** :span[string]{.type-label} +- **`type`** :span[enum]{.type-label} + Allowed values: `TentaclePassive`, `TentacleActive`, `Ssh`. + +**Response** + +`200` — The machine which was discovered + +- **`Architecture`** :span[string]{.type-label} +- **`Endpoint`** :span[object]{.type-label} + - **`CommunicationStyle`** :span[enum]{.type-label} + This is for legacy support in client. Server no longer uses this for determining endpoint types, it uses DeploymentTargetType. + Allowed values: `None`, `TentaclePassive`, `TentacleActive`, `Ssh`, `OfflineDrop`, `AzureWebApp`, `Ftp`, `AzureCloudService`, `AzureServiceFabricCluster`, `Kubernetes`, `StepPackage`, `KubernetesTentacle`, `AwsEcsCluster`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`HasLatestCalamari`** :span[boolean]{.type-label} +- **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsInProcess`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachinePolicyId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`OperatingSystem`** :span[string]{.type-label} +- **`OperatingSystemVersion`** :span[string]{.type-label} +- **`ShellName`** :span[string]{.type-label} +- **`ShellVersion`** :span[string]{.type-label} +- **`SkipInitialHealthCheck`** :span[boolean]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`StatusSummary`** :span[string]{.type-label} +- **`Thumbprint`** :span[string]{.type-label} +- **`Uri`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "StatusSummary": "string", + "Thumbprint": "string", + "Uri": "string" +} +``` +::: + +## Get all operating system names for deployment targets + +:endpoint{method="GET" path="/api/\{spaceId\}/machines/operatingsystem/names/all"} + +Also reachable at `/api/machines/operatingsystem/names/all`, `/api/spaces/{spaceIdentifier}/machines/operatingsystem/names/all`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The operating system names + +:::api-example{label="Response"} +```json +[ + "string" +] +``` +::: + +## Get all operating system shell names for deployment targets + +:endpoint{method="GET" path="/api/\{spaceId\}/machines/operatingsystem/shells/all"} + +Also reachable at `/api/machines/operatingsystem/shells/all`, `/api/spaces/{spaceIdentifier}/machines/operatingsystem/shells/all`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The operating system shell names + +:::api-example{label="Response"} +```json +[ + "string" +] +``` +::: + +## List all of the registered machines in the supplied Octopus Deploy Space, from all environments. The results are sorted by health status, healthiest first, then alphabetically by name + +:endpoint{method="GET" path="/api/\{spaceId\}/machines/v2"} + +Also reachable at `/api/machines/v2`, `/api/spaces/{spaceIdentifier}/machines/v2`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`commStyles`** :span[array of string]{.type-label} + List of communication styles which if specified, filters the result to only include Deployment Targets with matching communication styles. +- **`deploymentTargetTypes`** :span[array of string]{.type-label} + List of deployment target types which if specified, filters the result to only include Deployment Targets with matching types. +- **`environmentIds`** :span[array of string]{.type-label} + List of Environment IDs which if specified, filters the result to only include Deployment Targets with matching Environment IDs. +- **`healthStatuses`** :span[array of string]{.type-label} + List of health statuses which if specified, filters the result to only include Deployment Targets with matching health statuses. +- **`ids`** :span[array of string]{.type-label} + List of Deployment Target IDs which if specified, filters the result to only include Deployment Targets with matching IDs. +- **`isDisabled`** :span[boolean]{.type-label} + A filter to return only disabled/enabled Deployment Targets. +- **`name`** :span[string]{.type-label} + The exact name of a deployment target to be matched. +- **`operatingSystemNames`** :span[array of string]{.type-label} + List of operating system names which if specified, filters the result to only include Deployment Targets with matching operating systems. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`roles`** :span[array of string]{.type-label} + List of roles which if specified, filters the result to only include Deployment Targets with matching roles. +- **`shellNames`** :span[array of string]{.type-label} + List of shell names which if specified, filters the result to only include Deployment Targets with matching shells. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`targetTags`** :span[array of string]{.type-label} + List of Target Tags which if specified, filters the result to only include Deployment Targets with matching Target Tags. +- **`tenantIds`** :span[array of string]{.type-label} + List of Tenant IDs which if specified, filters the result to only include Deployment Targets with matching Tenant IDs. +- **`tenantTags`** :span[array of string]{.type-label} + List of Tenant Tags which if specified, filters the result to only include Deployment Targets with matching Tenant Tags. + +**Response** + +`200` — The list of alphabetically sorted deployment targets that matched the request. + +- **`DeploymentTargets`** :span[object]{.type-label} + - **`ItemType`** :span[string]{.type-label} + - **`Items`** :span[array of object]{.type-label} + - **`ItemsPerPage`** :span[integer]{.type-label} + - **`LastPageNumber`** :span[integer]{.type-label} + - **`NumberOfPages`** :span[integer]{.type-label} + - **`TotalResults`** :span[integer]{.type-label} +- **`TargetCountPerHealthStatus`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DeploymentTargets": { + "ItemType": "string", + "Items": [ + { + "Architecture": "string", + "Endpoint": {}, + "EnvironmentIds": [ + "string" + ], + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {}, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "Roles": [ + "string" + ], + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Uri": "string" + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 + }, + "TargetCountPerHealthStatus": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + } +} +``` +::: + +## Get an existing Deployment Target + +:endpoint{method="GET" path="/api/\{spaceId\}/machines/\{id\}"} + +Also reachable at `/api/machines/{id}`, `/api/spaces/{spaceIdentifier}/machines/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the Machine. +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the space that contains the Machine. + +**Response** + +`200` — The Deployment Target resource to return. + +- **`Architecture`** :span[string]{.type-label} +- **`Endpoint`** :span[object]{.type-label} + - **`CommunicationStyle`** :span[enum]{.type-label} + This is for legacy support in client. Server no longer uses this for determining endpoint types, it uses DeploymentTargetType. + Allowed values: `None`, `TentaclePassive`, `TentacleActive`, `Ssh`, `OfflineDrop`, `AzureWebApp`, `Ftp`, `AzureCloudService`, `AzureServiceFabricCluster`, `Kubernetes`, `StepPackage`, `KubernetesTentacle`, `AwsEcsCluster`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`HasLatestCalamari`** :span[boolean]{.type-label} +- **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsInProcess`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachinePolicyId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`OperatingSystem`** :span[string]{.type-label} +- **`OperatingSystemVersion`** :span[string]{.type-label} +- **`Roles`** :span[array of string]{.type-label} +- **`ShellName`** :span[string]{.type-label} +- **`ShellVersion`** :span[string]{.type-label} +- **`SkipInitialHealthCheck`** :span[boolean]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`StatusSummary`** :span[string]{.type-label} +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Thumbprint`** :span[string]{.type-label} +- **`Uri`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "EnvironmentIds": [ + "string" + ], + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "Roles": [ + "string" + ], + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Uri": "string" +} +``` +::: + +## Delete an existing Deployment Target + +:endpoint{method="DELETE" path="/api/\{spaceId\}/machines/\{id\}"} + +Also reachable at `/api/machines/{id}`, `/api/spaces/{spaceIdentifier}/machines/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Deployment Target to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The SpaceId of the deployment target to delete. + +**Response** + +`200` — Success + +## Get a list of the latest deployments by project for the given Deployment Target + +:endpoint{method="GET" path="/api/\{spaceId\}/machines/\{id\}/latestdeployments"} + +Also reachable at `/api/machines/{id}/latestdeployments`, `/api/spaces/{spaceIdentifier}/machines/{id}/latestdeployments`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Deployment Target. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`partialName`** :span[string]{.type-label} +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested list of latest deployments per project for the Deployment Target + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectLogo`** :span[string]{.type-label} + Minimum length 1. + - **`ProjectName`** :span[string]{.type-label} + Minimum length 1. + - **`ServerTask`** :span[object]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "ProjectId": "string", + "ProjectLogo": "string", + "ProjectName": "string", + "ServerTask": { + "Arguments": {}, + "CanRerun": true, + "Completed": "string", + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Description": "string", + "Duration": "string", + "ErrorMessage": "string", + "EstimatedRemainingQueueDurationSeconds": 0, + "FinishedSuccessfully": true, + "HasBeenPickedUpByProcessor": true, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUpdatedTime": "2020-01-01T00:00:00.000Z", + "Links": {}, + "Name": "string", + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ServerNode": "string", + "SpaceId": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued" + } + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get a list of Tasks for the given Deployment Target + +:endpoint{method="GET" path="/api/\{spaceId\}/machines/\{id\}/tasks"} + +Also reachable at `/api/machines/{id}/tasks`, `/api/spaces/{spaceIdentifier}/machines/{id}/tasks`. + +Get a history of related Tasks (ie. Deployments) for a Deployment Target. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Deployment Target. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`type`** :span[enum]{.type-label} + The type of Task to retrieve. If left blank, all Tasks are retrieved. + Allowed values: `Deployment`, `RunbookRun`. + +**Response** + +`200` — The requested list of Tasks for the Deployment Target + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Arguments`** :span[object]{.type-label} + Gets or sets any arguments to the task. + - **`CanRerun`** :span[boolean]{.type-label} + If true, then the task can be used as the basis for a new task with the same effect. + - **`Completed`** :span[string]{.type-label} + Gets or sets a value indicating the completion status of the task. May be "Timed out", "Queued...", "Executing...", or the time at which the task completed for completed tasks. + - **`CompletedTime`** :span[string]{.type-label} + Gets or sets the date/time that the task completed. Will be null if the task has not yet completed. Format `date-time`. + - **`Description`** :span[string]{.type-label} + Gets or sets a short, human-understandable description of this task. An example might be "Manual database backup". This is the name that will be shown in the task list. + - **`Duration`** :span[string]{.type-label} + Gets or sets a string indicating how long the task took to run. + - **`ErrorMessage`** :span[string]{.type-label} + Gets or sets a short summary of the errors encountered when the task ran (if any). + - **`EstimatedRemainingQueueDurationSeconds`** :span[integer]{.type-label} + - **`FinishedSuccessfully`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task ran to completion successfully. + - **`HasBeenPickedUpByProcessor`** :span[boolean]{.type-label} + Gets or sets a boolean value indicating whether the Octopus Server is processing this task. + - **`HasPendingInterruptions`** :span[boolean]{.type-label} + True if the task has any pending interruptions. + - **`HasPendingPreconditions`** :span[boolean]{.type-label} + True if the task has any pending preconditions. + - **`HasWarningsOrErrors`** :span[boolean]{.type-label} + True if any warnings or non-fatal errors were recorded in the task log during execution. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsCompleted`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task has completed (that is, not queued, not running, and not paused; may have finished successfully or failed). + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastUpdatedTime`** :span[string]{.type-label} + Gets or sets the time that the Octopus server last updated the status of this task. For a running task this should happen at least every couple of minutes. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of the task to create. This name must be one of the list of possible names documented in the create API operation documentation. + - **`PendingInterruptionTypes`** :span[array of enum]{.type-label} + Contains a list of the types of any pending interruptions. + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. + - **`PendingPreconditionTypes`** :span[array of string]{.type-label} + Contains a list of the types of any pending preconditions. + - **`ProjectId`** :span[string]{.type-label} + If the task belongs to a project (e.g. a deployment), the ID of the project it belongs to. + - **`QueueTime`** :span[string]{.type-label} + Gets or sets the time at which the task was queued. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Gets or sets the time at which the task will timeout if it has not started executing. Format `date-time`. + - **`ServerNode`** :span[string]{.type-label} + Gets the ID of the Octopus server that created and will control this task. + - **`SpaceId`** :span[string]{.type-label} + - **`StartTime`** :span[string]{.type-label} + Gets or sets the time at which the task started executing. Format `date-time`. + - **`State`** :span[enum]{.type-label} + Gets or sets the current state of the task. + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Arguments": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "CanRerun": true, + "Completed": "string", + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Description": "string", + "Duration": "string", + "ErrorMessage": "string", + "EstimatedRemainingQueueDurationSeconds": 0, + "FinishedSuccessfully": true, + "HasBeenPickedUpByProcessor": true, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUpdatedTime": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ServerNode": "string", + "SpaceId": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued" + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get a list of Tasks for the given Deployment Target + +:endpoint{method="GET" path="/api/\{spaceId\}/machines/\{id\}/tasks/v1"} + +Also reachable at `/api/machines/{id}/tasks/v1`, `/api/spaces/{spaceIdentifier}/machines/{id}/tasks/v1`. + +Get a history of related Tasks (ie. Deployments) for a Deployment Target. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Deployment Target. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`type`** :span[enum]{.type-label} + The type of Task to retrieve. If left blank, all Tasks are retrieved. + Allowed values: `Deployment`, `RunbookRun`. + +**Response** + +`200` — The requested list of Tasks for the Deployment Target + +- **`ResourceCollection`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`ItemType`** :span[string]{.type-label} + - **`Items`** :span[array of object]{.type-label} + - **`ItemsPerPage`** :span[integer]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastPageNumber`** :span[integer]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`NumberOfPages`** :span[integer]{.type-label} + - **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ResourceCollection": { + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Arguments": {}, + "CanRerun": true, + "Completed": "string", + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Description": "string", + "Duration": "string", + "ErrorMessage": "string", + "EstimatedRemainingQueueDurationSeconds": 0, + "FinishedSuccessfully": true, + "HasBeenPickedUpByProcessor": true, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUpdatedTime": "2020-01-01T00:00:00.000Z", + "Links": {}, + "Name": "string", + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ServerNode": "string", + "SpaceId": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued" + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 + } +} +``` +::: + +## List all the variable set names (projects and library variable sets) that have variables that are scoped to only the given machine + +:endpoint{method="GET" path="/api/\{spaceId\}/machines/\{machineId\}/singlyScopedVariableDetails"} + +Also reachable at `/api/machines/{machineId}/singlyScopedVariableDetails`, `/api/spaces/{spaceIdentifier}/machines/{machineId}/singlyScopedVariableDetails`. + +**Path Parameters** + +- **`machineId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The names of LibraryVariableSets and VariableSets which contain one or more variables scoped to the requested machine. Along with boolean indication to show that there are unviewable/editable projects/libraries which also contain scoped variables. + +- **`Resource`** :span[object]{.type-label} + - **`HasUnauthorizedLibraryVariableSetVariables`** :span[boolean]{.type-label} + - **`HasUnauthorizedProjectVariables`** :span[boolean]{.type-label} + - **`VariableMap`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Resource": { + "HasUnauthorizedLibraryVariableSetVariables": true, + "HasUnauthorizedProjectVariables": true, + "VariableMap": { + "additionalProp1": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "additionalProp2": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "additionalProp3": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + } + } + } +} +``` +::: + +## Modify an existing Deployment Target (identified by ID) + +:endpoint{method="PUT" path="/api/\{spaceId\}/machines/\{machineid\}"} + +Also reachable at `/api/machines/{machineid}`, `/api/spaces/{spaceIdentifier}/machines/{machineid}`. + +**Path Parameters** + +- **`machineid`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Endpoint`** :span[object]{.type-label} + - **`CommunicationStyle`** :span[enum]{.type-label} + This is for legacy support in client. Server no longer uses this for determining endpoint types, it uses DeploymentTargetType. + Allowed values: `None`, `TentaclePassive`, `TentacleActive`, `Ssh`, `OfflineDrop`, `AzureWebApp`, `Ftp`, `AzureCloudService`, `AzureServiceFabricCluster`, `Kubernetes`, `StepPackage`, `KubernetesTentacle`, `AwsEcsCluster`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`EnvironmentIds`** :span[array of string]{.type-label} *(required)* +- **`IsDisabled`** :span[boolean]{.type-label} +- **`MachineId`** :span[string]{.type-label} *(required)* +- **`MachinePolicyId`** :span[string]{.type-label} + Note: If this is unset, but the endpoint requires a policy, Octopus will update the machine with the _default_ machine policy. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Roles`** :span[array of string]{.type-label} *(required)* +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Thumbprint`** :span[string]{.type-label} +- **`Uri`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "EnvironmentIds": [ + "string" + ], + "IsDisabled": true, + "MachineId": "string", + "MachinePolicyId": "string", + "Name": "string", + "Roles": [ + "string" + ], + "Slug": "string", + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Uri": "string" +} +``` +::: + +**Response** + +`200` — The MachineResource following requested changes. + +- **`Architecture`** :span[string]{.type-label} +- **`Endpoint`** :span[object]{.type-label} + - **`CommunicationStyle`** :span[enum]{.type-label} + This is for legacy support in client. Server no longer uses this for determining endpoint types, it uses DeploymentTargetType. + Allowed values: `None`, `TentaclePassive`, `TentacleActive`, `Ssh`, `OfflineDrop`, `AzureWebApp`, `Ftp`, `AzureCloudService`, `AzureServiceFabricCluster`, `Kubernetes`, `StepPackage`, `KubernetesTentacle`, `AwsEcsCluster`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`HasLatestCalamari`** :span[boolean]{.type-label} +- **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsInProcess`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachinePolicyId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`OperatingSystem`** :span[string]{.type-label} +- **`OperatingSystemVersion`** :span[string]{.type-label} +- **`Roles`** :span[array of string]{.type-label} +- **`ShellName`** :span[string]{.type-label} +- **`ShellVersion`** :span[string]{.type-label} +- **`SkipInitialHealthCheck`** :span[boolean]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`StatusSummary`** :span[string]{.type-label} +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} +- **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Thumbprint`** :span[string]{.type-label} +- **`Uri`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "EnvironmentIds": [ + "string" + ], + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "Roles": [ + "string" + ], + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Uri": "string" +} +``` +::: diff --git a/src/pages/docs/api/deployments.md b/src/pages/docs/api/deployments.md new file mode 100644 index 0000000000..72a0706dce --- /dev/null +++ b/src/pages/docs/api/deployments.md @@ -0,0 +1,1319 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Deployments +--- + +## Get a list of Deployments + +:endpoint{method="GET" path="/api/\{spaceId\}/deployments"} + +Also reachable at `/api/deployments`, `/api/spaces/{spaceIdentifier}/deployments`. + +Lists all of the Deployments in the supplied Space. The results will be sorted from most recent to least recent deployment. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space to which the Deployments belong. + +**Query Parameters** + +- **`channels`** :span[array of string]{.type-label} + Channel Ids to filter results to only Deployments with the given Channel Ids. +- **`environments`** :span[array of string]{.type-label} + Environment Ids to filter results to only Deployments with the given Environment Ids. +- **`ids`** :span[array of string]{.type-label} + Deployment Ids to filter results to only Deployments with the given Ids. +- **`partialName`** :span[string]{.type-label} + A partial name, to limit the set of Deployments to those with a name that includes the partial name. +- **`projects`** :span[array of string]{.type-label} + Project Ids to filter results to only Deployments with the given Project Ids. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`taskState`** :span[enum]{.type-label} + Task State to filter results to only Deployments with the given Task State. + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. +- **`tenants`** :span[array of string]{.type-label} + Tenant Ids to filter results to only Deployments with the given Tenant Ids. + +**Response** + +`200` — The requested Deployments + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Changes`** :span[array of object]{.type-label} + - **`ChangesMarkdown`** :span[string]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`Comments`** :span[string]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`DebugMode`** :span[string]{.type-label} + - **`DeployedBy`** :span[string]{.type-label} + - **`DeployedById`** :span[string]{.type-label} + - **`DeployedToMachineIds`** :span[array of string]{.type-label} + - **`DeploymentProcessId`** :span[string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. + - **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`FailureEncountered`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`ForcePackageRedeployment`** :span[boolean]{.type-label} + - **`FormValues`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ManifestVariableSetId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Priority`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. + - **`ReleaseId`** :span[string]{.type-label} + - **`SkipActions`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. + - **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`TaskId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + - **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "ChangeRequestSettings": [ + {} + ], + "Changes": [ + {} + ], + "ChangesMarkdown": "string", + "ChannelId": "string", + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "DeploymentProcessId": "string", + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + {} + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "ForcePackageRedeployment": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ReleaseId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a Deployment + +:endpoint{method="POST" path="/api/\{spaceId\}/deployments"} + +Also reachable at `/api/deployments`, `/api/spaces/{spaceIdentifier}/deployments`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `ServiceNow`, `JiraServiceManagement`. +- **`Changes`** :span[array of object]{.type-label} + - **`BuildInformation`** :span[array of object]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + Aggregate of distinct commits from all VersionMetadata. + - **`ReleaseNotes`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} + Aggregate of distinct work items from all VersionMetadata. +- **`ChangesMarkdown`** :span[string]{.type-label} +- **`ChannelId`** :span[string]{.type-label} +- **`Comments`** :span[string]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DebugMode`** :span[string]{.type-label} +- **`DeployedBy`** :span[string]{.type-label} +- **`DeployedById`** :span[string]{.type-label} +- **`DeployedToMachineIds`** :span[array of string]{.type-label} +- **`DeploymentProcessId`** :span[string]{.type-label} +- **`EnvironmentId`** :span[string]{.type-label} *(required)* +- **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. +- **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`Steps`** :span[array of object]{.type-label} *(required)* +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`FailureEncountered`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`ForcePackageRedeployment`** :span[boolean]{.type-label} +- **`FormValues`** :span[object]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ManifestVariableSetId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`Priority`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. +- **`ReleaseId`** :span[string]{.type-label} *(required)* +- **`SkipActions`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. +- **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`TaskId`** :span[string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. + +:::api-example{label="Request"} +```json +{ + "ChangeRequestSettings": [ + { + "Type": "ServiceNow" + } + ], + "Changes": [ + { + "BuildInformation": [ + {} + ], + "Commits": [ + {} + ], + "ReleaseNotes": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChangesMarkdown": "string", + "ChannelId": "string", + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "DeploymentProcessId": "string", + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + { + "CorrelationId": "string", + "Slug": "string" + } + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "ForcePackageRedeployment": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ReleaseId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true +} +``` +::: + +**Response** + +`201` — Created + +- **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `ServiceNow`, `JiraServiceManagement`. +- **`Changes`** :span[array of object]{.type-label} + - **`BuildInformation`** :span[array of object]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + Aggregate of distinct commits from all VersionMetadata. + - **`ReleaseNotes`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} + Aggregate of distinct work items from all VersionMetadata. +- **`ChangesMarkdown`** :span[string]{.type-label} +- **`ChannelId`** :span[string]{.type-label} +- **`Comments`** :span[string]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DebugMode`** :span[string]{.type-label} +- **`DeployedBy`** :span[string]{.type-label} +- **`DeployedById`** :span[string]{.type-label} +- **`DeployedToMachineIds`** :span[array of string]{.type-label} +- **`DeploymentProcessId`** :span[string]{.type-label} +- **`EnvironmentId`** :span[string]{.type-label} +- **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. +- **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`Steps`** :span[array of object]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`FailureEncountered`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`ForcePackageRedeployment`** :span[boolean]{.type-label} +- **`FormValues`** :span[object]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ManifestVariableSetId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`Priority`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. +- **`ReleaseId`** :span[string]{.type-label} +- **`SkipActions`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. +- **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`TaskId`** :span[string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. + +:::api-example{label="Response"} +```json +{ + "ChangeRequestSettings": [ + { + "Type": "ServiceNow" + } + ], + "Changes": [ + { + "BuildInformation": [ + {} + ], + "Commits": [ + {} + ], + "ReleaseNotes": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChangesMarkdown": "string", + "ChannelId": "string", + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "DeploymentProcessId": "string", + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + { + "CorrelationId": "string", + "Slug": "string" + } + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "ForcePackageRedeployment": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ReleaseId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true +} +``` +::: + +## Create a new tenanted deployment + +:endpoint{method="POST" path="/api/\{spaceId\}/deployments/create/tenanted/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/deployments/create/tenanted/v1`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`DebugMode`** :span[string]{.type-label} + Contributes the OctopusPrintVariables and OctopusPrintEvaluatedVariables variables to the execution. One of "None", "Log" or "Debug"; leave unset for the default of "None". +- **`DeploymentFreezeNames`** :span[array of string]{.type-label} + Active deployment freezes to override so this execution can proceed despite them. Overriding a freeze bypasses a deliberate block on deploying, so only set this when explicitly asked to. Requires DeploymentFreezeOverrideReason. +- **`DeploymentFreezeOverrideReason`** :span[string]{.type-label} + Required, and must not be blank, whenever DeploymentFreezeNames is non-empty. Recorded against the override. +- **`EnvironmentName`** :span[string]{.type-label} *(required)* + A single environment. To deploy to several, call the command once per environment. +- **`ExcludedMachineNames`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. +- **`ExcludedTargetTagNames`** :span[array of string]{.type-label} + A collection of deployment target tags (canonical names in format TagSetName/TagName) that should be excluded from the deployment. +- **`ForcePackageDownload`** :span[boolean]{.type-label} + Whether to force downloading of already installed packages (flag, default false). +- **`ForcePackageRedeployment`** :span[boolean]{.type-label} + If a project is configured to skip packages with already-installed versions, override this setting to force re-deployment (flag, default false). +- **`NoRunAfter`** :span[string]{.type-label} + Time at which a scheduled execution should expire if it has not started, specified as any valid DateTimeOffset format, and assuming the time zone is the current local time zone. Only meaningful alongside RunAt. Format `date-time`. +- **`Priority`** :span[string]{.type-label} + Whether this execution jumps the task queue ahead of other queued tasks. One of "LifecycleDefault" (use the lifecycle's configured setting), "On" or "Off". +- **`ProjectName`** :span[string]{.type-label} *(required)* +- **`ReleaseVersion`** :span[string]{.type-label} *(required)* + The version of an existing release, for example "1.2.3" — not a release ID. Minimum length 1. +- **`RunAt`** :span[string]{.type-label} + Time at which the execution should start (scheduling it for later), specified as any valid DateTimeOffset format, and assuming the time zone is the current local time zone. Format `date-time`. +- **`SkipStepNames`** :span[array of string]{.type-label} + Steps that are to be skipped for this execution. A name that matches no step is logged as a warning rather than failing the command, so check the step name carefully. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`SpaceIdOrName`** :span[string]{.type-label} *(required)* + Both this and SpaceId are required, and normally hold the same space ID; set both. +- **`SpecificMachineNames`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. A name that matches no machine fails the command. +- **`SpecificTargetTagNames`** :span[array of string]{.type-label} + A collection of deployment target tags (canonical names in format TagSetName/TagName) that should be included in the deployment. +- **`TenantTags`** :span[array of string]{.type-label} + Tenant tags, in canonical "TagSetName/TagName" form, selecting the tenants to deploy for. Set this or Tenants — with both empty nothing is deployed and no error is raised. +- **`Tenants`** :span[array of string]{.type-label} + The tenants to deploy for; one deployment is created per tenant. Set this or TenantTags — with both empty nothing is deployed and no error is raised. The single entry "*" means every tenant that can be deployed to this environment, which may be a very large number — only use it when explicitly asked to deploy to all tenants. +- **`UpdateVariableSnapshot`** :span[boolean]{.type-label} + If set to true, the release's variable set snapshot is updated from the project's current variables before the deployment. This mutates the release itself, so it affects later deployments of it too — leave it unset unless refreshed variables were asked for. +- **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. +- **`Variables`** :span[object]{.type-label} + Name/value pairs for prompted variables. A prompted variable that is required and has no value supplied here fails the command, naming the variable. + +:::api-example{label="Request"} +```json +{ + "DebugMode": "string", + "DeploymentFreezeNames": [ + "string" + ], + "DeploymentFreezeOverrideReason": "string", + "EnvironmentName": "string", + "ExcludedMachineNames": [ + "string" + ], + "ExcludedTargetTagNames": [ + "string" + ], + "ForcePackageDownload": true, + "ForcePackageRedeployment": true, + "NoRunAfter": "2020-01-01T00:00:00.000Z", + "Priority": "string", + "ProjectName": "string", + "ReleaseVersion": "string", + "RunAt": "2020-01-01T00:00:00.000Z", + "SkipStepNames": [ + "string" + ], + "SpaceId": "string", + "SpaceIdOrName": "string", + "SpecificMachineNames": [ + "string" + ], + "SpecificTargetTagNames": [ + "string" + ], + "TenantTags": [ + "string" + ], + "Tenants": [ + "string" + ], + "UpdateVariableSnapshot": true, + "UseGuidedFailure": true, + "Variables": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +**Response** + +`200` — Server tasks associated with the newly-created Deployment + +- **`DeploymentServerTasks`** :span[array of object]{.type-label} + - **`DeploymentId`** :span[string]{.type-label} + - **`ServerTaskId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DeploymentServerTasks": [ + { + "DeploymentId": "string", + "ServerTaskId": "string" + } + ] +} +``` +::: + +## Create a new untenanted deployment + +:endpoint{method="POST" path="/api/\{spaceId\}/deployments/create/untenanted/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/deployments/create/untenanted/v1`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`DebugMode`** :span[string]{.type-label} + Contributes the OctopusPrintVariables and OctopusPrintEvaluatedVariables variables to the execution. One of "None", "Log" or "Debug"; leave unset for the default of "None". +- **`DeploymentFreezeNames`** :span[array of string]{.type-label} + Active deployment freezes to override so this execution can proceed despite them. Overriding a freeze bypasses a deliberate block on deploying, so only set this when explicitly asked to. Requires DeploymentFreezeOverrideReason. +- **`DeploymentFreezeOverrideReason`** :span[string]{.type-label} + Required, and must not be blank, whenever DeploymentFreezeNames is non-empty. Recorded against the override. +- **`EnvironmentNames`** :span[array of string]{.type-label} *(required)* + One deployment is created per environment. Always name at least one: an empty list is not rejected, it simply deploys nothing and returns an empty list of deployments. +- **`ExcludedMachineNames`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. +- **`ExcludedTargetTagNames`** :span[array of string]{.type-label} + A collection of deployment target tags (canonical names in format TagSetName/TagName) that should be excluded from the deployment. +- **`ForcePackageDownload`** :span[boolean]{.type-label} + Whether to force downloading of already installed packages (flag, default false). +- **`ForcePackageRedeployment`** :span[boolean]{.type-label} + If a project is configured to skip packages with already-installed versions, override this setting to force re-deployment (flag, default false). +- **`NoRunAfter`** :span[string]{.type-label} + Time at which a scheduled execution should expire if it has not started, specified as any valid DateTimeOffset format, and assuming the time zone is the current local time zone. Only meaningful alongside RunAt. Format `date-time`. +- **`Priority`** :span[string]{.type-label} + Whether this execution jumps the task queue ahead of other queued tasks. One of "LifecycleDefault" (use the lifecycle's configured setting), "On" or "Off". +- **`ProjectName`** :span[string]{.type-label} *(required)* +- **`ReleaseVersion`** :span[string]{.type-label} *(required)* + The version of an existing release, for example "1.2.3" — not a release ID. Minimum length 1. +- **`RunAt`** :span[string]{.type-label} + Time at which the execution should start (scheduling it for later), specified as any valid DateTimeOffset format, and assuming the time zone is the current local time zone. Format `date-time`. +- **`SkipStepNames`** :span[array of string]{.type-label} + Steps that are to be skipped for this execution. A name that matches no step is logged as a warning rather than failing the command, so check the step name carefully. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`SpaceIdOrName`** :span[string]{.type-label} *(required)* + Both this and SpaceId are required, and normally hold the same space ID; set both. +- **`SpecificMachineNames`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. A name that matches no machine fails the command. +- **`SpecificTargetTagNames`** :span[array of string]{.type-label} + A collection of deployment target tags (canonical names in format TagSetName/TagName) that should be included in the deployment. +- **`UpdateVariableSnapshot`** :span[boolean]{.type-label} + If set to true, the release's variable set snapshot is updated from the project's current variables before the deployment. This mutates the release itself, so it affects later deployments of it too — leave it unset unless refreshed variables were asked for. +- **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. +- **`Variables`** :span[object]{.type-label} + Name/value pairs for prompted variables. A prompted variable that is required and has no value supplied here fails the command, naming the variable. + +:::api-example{label="Request"} +```json +{ + "DebugMode": "string", + "DeploymentFreezeNames": [ + "string" + ], + "DeploymentFreezeOverrideReason": "string", + "EnvironmentNames": [ + "string" + ], + "ExcludedMachineNames": [ + "string" + ], + "ExcludedTargetTagNames": [ + "string" + ], + "ForcePackageDownload": true, + "ForcePackageRedeployment": true, + "NoRunAfter": "2020-01-01T00:00:00.000Z", + "Priority": "string", + "ProjectName": "string", + "ReleaseVersion": "string", + "RunAt": "2020-01-01T00:00:00.000Z", + "SkipStepNames": [ + "string" + ], + "SpaceId": "string", + "SpaceIdOrName": "string", + "SpecificMachineNames": [ + "string" + ], + "SpecificTargetTagNames": [ + "string" + ], + "UpdateVariableSnapshot": true, + "UseGuidedFailure": true, + "Variables": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +**Response** + +`200` — Server tasks associated with the newly-created Deployment + +- **`DeploymentServerTasks`** :span[array of object]{.type-label} + - **`DeploymentId`** :span[string]{.type-label} + - **`ServerTaskId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DeploymentServerTasks": [ + { + "DeploymentId": "string", + "ServerTaskId": "string" + } + ] +} +``` +::: + +## Create a Deployment + +:endpoint{method="POST" path="/api/\{spaceId\}/deployments/v1"} + +Also reachable at `/api/deployments/v1`, `/api/spaces/{spaceIdentifier}/deployments/v1`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `ServiceNow`, `JiraServiceManagement`. +- **`Changes`** :span[array of object]{.type-label} + - **`BuildInformation`** :span[array of object]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + Aggregate of distinct commits from all VersionMetadata. + - **`ReleaseNotes`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} + Aggregate of distinct work items from all VersionMetadata. +- **`ChangesMarkdown`** :span[string]{.type-label} +- **`ChannelId`** :span[string]{.type-label} +- **`Comments`** :span[string]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DebugMode`** :span[string]{.type-label} +- **`DeployedBy`** :span[string]{.type-label} +- **`DeployedById`** :span[string]{.type-label} +- **`DeployedToMachineIds`** :span[array of string]{.type-label} +- **`DeploymentProcessId`** :span[string]{.type-label} +- **`EnvironmentId`** :span[string]{.type-label} *(required)* +- **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. +- **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`Steps`** :span[array of object]{.type-label} *(required)* +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`FailureEncountered`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`ForcePackageRedeployment`** :span[boolean]{.type-label} +- **`FormValues`** :span[object]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ManifestVariableSetId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`Priority`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. +- **`ReleaseId`** :span[string]{.type-label} *(required)* +- **`SkipActions`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. +- **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`TaskId`** :span[string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. + +:::api-example{label="Request"} +```json +{ + "ChangeRequestSettings": [ + { + "Type": "ServiceNow" + } + ], + "Changes": [ + { + "BuildInformation": [ + {} + ], + "Commits": [ + {} + ], + "ReleaseNotes": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChangesMarkdown": "string", + "ChannelId": "string", + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "DeploymentProcessId": "string", + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + { + "CorrelationId": "string", + "Slug": "string" + } + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "ForcePackageRedeployment": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ReleaseId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true +} +``` +::: + +**Response** + +`201` — Created + +- **`Deployment`** :span[object]{.type-label} + - **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Changes`** :span[array of object]{.type-label} + - **`ChangesMarkdown`** :span[string]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`Comments`** :span[string]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`DebugMode`** :span[string]{.type-label} + - **`DeployedBy`** :span[string]{.type-label} + - **`DeployedById`** :span[string]{.type-label} + - **`DeployedToMachineIds`** :span[array of string]{.type-label} + - **`DeploymentProcessId`** :span[string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. + - **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`FailureEncountered`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`ForcePackageRedeployment`** :span[boolean]{.type-label} + - **`FormValues`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ManifestVariableSetId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Priority`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. + - **`ReleaseId`** :span[string]{.type-label} + - **`SkipActions`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. + - **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`TaskId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + - **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. + +:::api-example{label="Response"} +```json +{ + "Deployment": { + "ChangeRequestSettings": [ + { + "Type": "ServiceNow" + } + ], + "Changes": [ + { + "BuildInformation": [ + {} + ], + "Commits": [ + {} + ], + "ReleaseNotes": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChangesMarkdown": "string", + "ChannelId": "string", + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "DeploymentProcessId": "string", + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + {} + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "ForcePackageRedeployment": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ReleaseId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true + } +} +``` +::: + +## Get a Deployment by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/deployments/\{id\}"} + +Also reachable at `/api/deployments/{id}`, `/api/spaces/{spaceIdentifier}/deployments/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Deployment to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested Deployment. + +- **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `ServiceNow`, `JiraServiceManagement`. +- **`Changes`** :span[array of object]{.type-label} + - **`BuildInformation`** :span[array of object]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + Aggregate of distinct commits from all VersionMetadata. + - **`ReleaseNotes`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} + Aggregate of distinct work items from all VersionMetadata. +- **`ChangesMarkdown`** :span[string]{.type-label} +- **`ChannelId`** :span[string]{.type-label} +- **`Comments`** :span[string]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DebugMode`** :span[string]{.type-label} +- **`DeployedBy`** :span[string]{.type-label} +- **`DeployedById`** :span[string]{.type-label} +- **`DeployedToMachineIds`** :span[array of string]{.type-label} +- **`DeploymentProcessId`** :span[string]{.type-label} +- **`EnvironmentId`** :span[string]{.type-label} +- **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. +- **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`Steps`** :span[array of object]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`FailureEncountered`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`ForcePackageRedeployment`** :span[boolean]{.type-label} +- **`FormValues`** :span[object]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ManifestVariableSetId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`Priority`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. +- **`ReleaseId`** :span[string]{.type-label} +- **`SkipActions`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. +- **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`TaskId`** :span[string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. + +:::api-example{label="Response"} +```json +{ + "ChangeRequestSettings": [ + { + "Type": "ServiceNow" + } + ], + "Changes": [ + { + "BuildInformation": [ + {} + ], + "Commits": [ + {} + ], + "ReleaseNotes": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChangesMarkdown": "string", + "ChannelId": "string", + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "DeploymentProcessId": "string", + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + { + "CorrelationId": "string", + "Slug": "string" + } + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "ForcePackageRedeployment": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ReleaseId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true +} +``` +::: + +## Delete an existing Deployment + +:endpoint{method="DELETE" path="/api/\{spaceId\}/deployments/\{id\}"} + +Also reachable at `/api/deployments/{id}`, `/api/spaces/{spaceIdentifier}/deployments/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Deployment to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success diff --git a/src/pages/docs/api/deprecations.md b/src/pages/docs/api/deprecations.md new file mode 100644 index 0000000000..452739e38a --- /dev/null +++ b/src/pages/docs/api/deprecations.md @@ -0,0 +1,64 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Deprecations +--- + +## Toggle a deprecation on or off in Octopus Server. Used to test the impact of deprecations + +:endpoint{method="POST" path="/api/deprecations/toggle"} + +**Request Body** + +- **`Deprecation`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Enabled`** :span[boolean]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Deprecation": "string", + "Enabled": true +} +``` +::: + +**Response** + +`200` — Confirmation that the Toggle has been deprecated + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Toggle a deprecation on or off in Octopus Server. Used to test the impact of deprecations + +:endpoint{method="POST" path="/api/deprecations/toggle/v1"} + +**Request Body** + +- **`Deprecation`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Enabled`** :span[boolean]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Deprecation": "string", + "Enabled": true +} +``` +::: + +**Response** + +`200` — Confirmation that the Toggle has been deprecated + +:::api-example{label="Response"} +```json +{} +``` +::: diff --git a/src/pages/docs/api/directory-services.md b/src/pages/docs/api/directory-services.md new file mode 100644 index 0000000000..5963e8d164 --- /dev/null +++ b/src/pages/docs/api/directory-services.md @@ -0,0 +1,30 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Directory Services +--- + +## Search for Active Directory groups + +:endpoint{method="GET" path="/api/externalgroups/directoryServices"} + +Also reachable at `/api/externalgroups/ldap`. + +Search for Active Directory groups + +**Response** + +`200` — OK + +## Search for Active Directory users + +:endpoint{method="GET" path="/api/externalusers/directoryServices"} + +Also reachable at `/api/externalusers/ldap`. + +Search for Active Directory users + +**Response** + +`200` — OK diff --git a/src/pages/docs/api/dynamic-extensions.md b/src/pages/docs/api/dynamic-extensions.md new file mode 100644 index 0000000000..71238c58e4 --- /dev/null +++ b/src/pages/docs/api/dynamic-extensions.md @@ -0,0 +1,102 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Dynamic Extensions +--- + +## Request the current dynamic extensions feature metadata + +:endpoint{method="GET" path="/api/dynamic-extensions/features/metadata"} + +**Response** + +`200` — The current dynamic extensions feature metadata + +- **`Features`** :span[array of object]{.type-label} + - **`Default`** :span[string]{.type-label} + - **`Description`** :span[string]{.type-label} + Markdown formatted. + - **`Key`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Options`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Features": [ + { + "Default": "string", + "Description": "string", + "Key": "string", + "Name": "string", + "Options": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + } + ] +} +``` +::: + +## Request the current dynamic extensions feature values + +:endpoint{method="GET" path="/api/dynamic-extensions/features/values"} + +**Response** + +`200` — The current dynamic extensions feature values + +- **`Values`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Values": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +## Modify the current dynamic extensions feature values + +:endpoint{method="PUT" path="/api/dynamic-extensions/features/values"} + +**Request Body** + +- **`Values`** :span[object]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Values": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +**Response** + +`200` — The new dynamic extensions feature values + +- **`Values`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Values": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: diff --git a/src/pages/docs/api/environments.md b/src/pages/docs/api/environments.md new file mode 100644 index 0000000000..9920739ffb --- /dev/null +++ b/src/pages/docs/api/environments.md @@ -0,0 +1,1432 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Environments +--- + +## Get a list of Environments + +:endpoint{method="GET" path="/api/\{spaceId\}/environments"} + +Also reachable at `/api/environments`, `/api/spaces/{spaceIdentifier}/environments`. + +Lists all of the environments in the supplied Octopus Deploy Space. The results will be sorted by the `SortOrder` field on each environment. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + Environment Ids to filter results to only Environments with the given Ids. +- **`name`** :span[string]{.type-label} + Filters the returned environments by the specified `name` fragment. Left for backwards compatibility; prefer PartialName. +- **`partialName`** :span[string]{.type-label} + Filters the documents using the specified `partialName` fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 10. Minimum `0`. + +**Response** + +`200` — The requested list of Environments + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`AllowDynamicInfrastructure`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + List of tags assigned to this environment. + - **`ExtensionSettings`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this environment. This should be short, preferably 5-20 characters. + - **`Slug`** :span[string]{.type-label} + - **`SortOrder`** :span[integer]{.type-label} + 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`** :span[string]{.type-label} + - **`UseGuidedFailure`** :span[boolean]{.type-label} + 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. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "AllowDynamicInfrastructure": true, + "Description": "string", + "EnvironmentTags": [ + "string" + ], + "ExtensionSettings": [ + {} + ], + "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 + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new environment + +:endpoint{method="POST" path="/api/\{spaceId\}/environments"} + +Also reachable at `/api/environments`, `/api/spaces/{spaceIdentifier}/environments`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`AllowDynamicInfrastructure`** :span[boolean]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EnvironmentTags`** :span[array of string]{.type-label} +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. Maximum length 50. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`UseGuidedFailure`** :span[boolean]{.type-label} + +:::api-example{label="Request"} +```json +{ + "AllowDynamicInfrastructure": true, + "Description": "string", + "EnvironmentTags": [ + "string" + ], + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "Name": "string", + "Slug": "string", + "SortOrder": 0, + "SpaceId": "string", + "UseGuidedFailure": true +} +``` +::: + +**Response** + +`201` — Created + +- **`AllowDynamicInfrastructure`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + List of tags assigned to this environment. +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this environment. This should be short, preferably 5-20 characters. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} + 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`** :span[string]{.type-label} +- **`UseGuidedFailure`** :span[boolean]{.type-label} + 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. + +:::api-example{label="Response"} +```json +{ + "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 a list of Environments + +:endpoint{method="GET" path="/api/\{spaceId\}/environments/all"} + +Also reachable at `/api/environments/all`, `/api/spaces/{spaceIdentifier}/environments/all`. + +Lists the name and ID of all of the environments in the supplied Space. The results will be sorted by the `SortOrder` field on each environment. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`channelId`** :span[string]{.type-label} + A Channel Id used to filter a query. +- **`ids`** :span[array of string]{.type-label} + A comma separated list of Deployment Environment resource ids used to filter a query. +- **`projectId`** :span[string]{.type-label} + A project Id used to filter a query. + +**Response** + +`200` — Requested list of Environments + +- **`AllowDynamicInfrastructure`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + List of tags assigned to this environment. +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this environment. This should be short, preferably 5-20 characters. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} + 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`** :span[string]{.type-label} +- **`UseGuidedFailure`** :span[boolean]{.type-label} + 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. + +:::api-example{label="Response"} +```json +[ + { + "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 a list of Environments + +:endpoint{method="GET" path="/api/\{spaceId\}/environments/all/v1"} + +Also reachable at `/api/environments/all/v1`, `/api/spaces/{spaceIdentifier}/environments/all/v1`. + +Lists the name and ID of all of the environments in the supplied Space. The results will be sorted by the `SortOrder` field on each environment. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`channelId`** :span[string]{.type-label} + A Channel Id used to filter a query. +- **`ids`** :span[array of string]{.type-label} + A comma separated list of Deployment Environment resource ids used to filter a query. +- **`projectId`** :span[string]{.type-label} + A project Id used to filter a query. + +**Response** + +`200` — Requested list of Environments + +- **`Environments`** :span[array of object]{.type-label} + - **`AllowDynamicInfrastructure`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + List of tags assigned to this environment. + - **`ExtensionSettings`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this environment. This should be short, preferably 5-20 characters. + - **`Slug`** :span[string]{.type-label} + - **`SortOrder`** :span[integer]{.type-label} + 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`** :span[string]{.type-label} + - **`UseGuidedFailure`** :span[boolean]{.type-label} + 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. + +:::api-example{label="Response"} +```json +{ + "Environments": [ + { + "AllowDynamicInfrastructure": true, + "Description": "string", + "EnvironmentTags": [ + "string" + ], + "ExtensionSettings": [ + {} + ], + "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 + } + ] +} +``` +::: + +## PUT /api/{spaceId}/environments/sortorder + +:endpoint{method="PUT" path="/api/\{spaceId\}/environments/sortorder"} + +Also reachable at `/api/environments/sortorder`, `/api/spaces/{spaceIdentifier}/environments/sortorder`. + +Takes an array of environment IDs as the request body, uses the order of items in the array to sort the environments on the server. The ID of every environment must be specified. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +A `array of string` payload. + +:::api-example{label="Request"} +```json +[ + "string" +] +``` +::: + +**Response** + +`200` — Success + +## List all environments, including a summary of machine information + +:endpoint{method="GET" path="/api/\{spaceId\}/environments/summary"} + +Also reachable at `/api/environments/summary`, `/api/spaces/{spaceIdentifier}/environments/summary`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`commStyles`** :span[array of string]{.type-label} +- **`deploymentTargetTypes`** :span[array of string]{.type-label} +- **`environmentTags`** :span[array of string]{.type-label} +- **`healthStatuses`** :span[array of string]{.type-label} +- **`hideEmptyEnvironments`** :span[boolean]{.type-label} +- **`ids`** :span[array of string]{.type-label} +- **`isDisabled`** :span[boolean]{.type-label} +- **`machinePartialName`** :span[string]{.type-label} +- **`partialName`** :span[string]{.type-label} +- **`roles`** :span[array of string]{.type-label} +- **`shellNames`** :span[array of string]{.type-label} +- **`targetTags`** :span[array of string]{.type-label} +- **`tenantIds`** :span[array of string]{.type-label} +- **`tenantTags`** :span[array of string]{.type-label} + +**Response** + +`200` — Contains the machines et al associated with a given environment. + +- **`DeploymentTargetSummaries`** :span[object]{.type-label} +- **`EnvironmentSummaries`** :span[array of object]{.type-label} + - **`DeploymentTargetSummaries`** :span[object]{.type-label} + - **`Environment`** :span[object]{.type-label} + - **`MachineEndpointSummaries`** :span[object]{.type-label} + - **`MachineHealthStatusSummaries`** :span[object]{.type-label} + - **`MachineIdsForCalamariUpgrade`** :span[array of string]{.type-label} + - **`MachineIdsForTentacleUpgrade`** :span[array of string]{.type-label} + - **`MachineTenantSummaries`** :span[object]{.type-label} + - **`MachineTenantTagSummaries`** :span[object]{.type-label} + - **`TentacleUpgradesRequired`** :span[boolean]{.type-label} + - **`TotalDisabledMachines`** :span[integer]{.type-label} + - **`TotalMachines`** :span[integer]{.type-label} +- **`MachineEndpointSummaries`** :span[object]{.type-label} +- **`MachineHealthStatusSummaries`** :span[object]{.type-label} +- **`MachineIdsForCalamariUpgrade`** :span[array of string]{.type-label} +- **`MachineIdsForTentacleUpgrade`** :span[array of string]{.type-label} +- **`MachineTenantSummaries`** :span[object]{.type-label} +- **`MachineTenantTagSummaries`** :span[object]{.type-label} +- **`TentacleUpgradesRequired`** :span[boolean]{.type-label} +- **`TotalDisabledMachines`** :span[integer]{.type-label} +- **`TotalMachines`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DeploymentTargetSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "EnvironmentSummaries": [ + { + "DeploymentTargetSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "Environment": { + "AllowDynamicInfrastructure": true, + "Description": "string", + "EnvironmentTags": [ + "string" + ], + "ExtensionSettings": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {}, + "Name": "string", + "Slug": "string", + "SortOrder": 0, + "SpaceId": "string", + "UseGuidedFailure": true + }, + "MachineEndpointSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineHealthStatusSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineIdsForCalamariUpgrade": [ + "string" + ], + "MachineIdsForTentacleUpgrade": [ + "string" + ], + "MachineTenantSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineTenantTagSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "TentacleUpgradesRequired": true, + "TotalDisabledMachines": 0, + "TotalMachines": 0 + } + ], + "MachineEndpointSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineHealthStatusSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineIdsForCalamariUpgrade": [ + "string" + ], + "MachineIdsForTentacleUpgrade": [ + "string" + ], + "MachineTenantSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineTenantTagSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "TentacleUpgradesRequired": true, + "TotalDisabledMachines": 0, + "TotalMachines": 0 +} +``` +::: + +## List all environments, including a summary of machine information + +:endpoint{method="GET" path="/api/\{spaceId\}/environments/summary/v2"} + +Also reachable at `/api/spaces/{spaceIdentifier}/environments/summary/v2`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`commStyles`** :span[array of string]{.type-label} +- **`deploymentTargetTypes`** :span[array of string]{.type-label} +- **`environmentTags`** :span[array of string]{.type-label} +- **`healthStatuses`** :span[array of string]{.type-label} +- **`hideEmptyEnvironments`** :span[boolean]{.type-label} +- **`ids`** :span[array of string]{.type-label} +- **`isDisabled`** :span[boolean]{.type-label} +- **`machinePartialName`** :span[string]{.type-label} +- **`partialName`** :span[string]{.type-label} +- **`roles`** :span[array of string]{.type-label} +- **`shellNames`** :span[array of string]{.type-label} +- **`targetTags`** :span[array of string]{.type-label} +- **`tenantIds`** :span[array of string]{.type-label} +- **`tenantTags`** :span[array of string]{.type-label} +- **`type`** :span[array of string]{.type-label} + Filters the environment summaries using the specified environment EnvironmentType. + +**Response** + +`200` — Contains the machines et al associated with a given environment. + +- **`DeploymentTargetSummaries`** :span[object]{.type-label} +- **`EnvironmentSummaries`** :span[array of object]{.type-label} + - **`DeploymentTargetSummaries`** :span[object]{.type-label} + - **`Environment`** :span[object]{.type-label} + - **`MachineEndpointSummaries`** :span[object]{.type-label} + - **`MachineHealthStatusSummaries`** :span[object]{.type-label} + - **`MachineIdsForCalamariUpgrade`** :span[array of string]{.type-label} + - **`MachineIdsForTentacleUpgrade`** :span[array of string]{.type-label} + - **`MachineTenantSummaries`** :span[object]{.type-label} + - **`MachineTenantTagSummaries`** :span[object]{.type-label} + - **`TentacleUpgradesRequired`** :span[boolean]{.type-label} + - **`TotalDisabledMachines`** :span[integer]{.type-label} + - **`TotalMachines`** :span[integer]{.type-label} +- **`MachineEndpointSummaries`** :span[object]{.type-label} +- **`MachineHealthStatusSummaries`** :span[object]{.type-label} +- **`MachineIdsForCalamariUpgrade`** :span[array of string]{.type-label} +- **`MachineTenantSummaries`** :span[object]{.type-label} +- **`MachineTenantTagSummaries`** :span[object]{.type-label} +- **`TentacleUpgradesRequired`** :span[boolean]{.type-label} +- **`TotalDisabledMachines`** :span[integer]{.type-label} +- **`TotalMachines`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DeploymentTargetSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "EnvironmentSummaries": [ + { + "DeploymentTargetSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "Environment": { + "Description": "string", + "EnvironmentTags": [ + "string" + ], + "Id": "string", + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "Type": "string" + }, + "MachineEndpointSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineHealthStatusSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineIdsForCalamariUpgrade": [ + "string" + ], + "MachineIdsForTentacleUpgrade": [ + "string" + ], + "MachineTenantSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineTenantTagSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "TentacleUpgradesRequired": true, + "TotalDisabledMachines": 0, + "TotalMachines": 0 + } + ], + "MachineEndpointSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineHealthStatusSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineIdsForCalamariUpgrade": [ + "string" + ], + "MachineTenantSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineTenantTagSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "TentacleUpgradesRequired": true, + "TotalDisabledMachines": 0, + "TotalMachines": 0 +} +``` +::: + +## Get a list of Environments + +:endpoint{method="GET" path="/api/\{spaceId\}/environments/v1"} + +Also reachable at `/api/environments/v1`, `/api/spaces/{spaceIdentifier}/environments/v1`. + +Lists all of the environments in the supplied Octopus Deploy Space. The results will be sorted by the `SortOrder` field on each environment. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + Environment Ids to filter results to only Environments with the given Ids. +- **`name`** :span[string]{.type-label} + Filters the returned environments by the specified `name` fragment. Left for backwards compatibility; prefer PartialName. +- **`partialName`** :span[string]{.type-label} + Filters the documents using the specified `partialName` fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 10. Minimum `0`. + +**Response** + +`200` — The requested list of Environments + +- **`Environments`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`ItemType`** :span[string]{.type-label} + - **`Items`** :span[array of object]{.type-label} + - **`ItemsPerPage`** :span[integer]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastPageNumber`** :span[integer]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`NumberOfPages`** :span[integer]{.type-label} + - **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Environments": { + "Id": "string", + "ItemType": "string", + "Items": [ + { + "AllowDynamicInfrastructure": true, + "Description": "string", + "EnvironmentTags": [ + "string" + ], + "ExtensionSettings": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {}, + "Name": "string", + "Slug": "string", + "SortOrder": 0, + "SpaceId": "string", + "UseGuidedFailure": true + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 + } +} +``` +::: + +## List Static, Parent and Ephemeral Environments in the supplied Octopus Deploy Space. The results will be sorted by the `SortOrder` field on each environment (which is set to a MaxValue integer for Ephemeral Environments) + +:endpoint{method="GET" path="/api/\{spaceId\}/environments/v2"} + +Also reachable at `/api/spaces/{spaceIdentifier}/environments/v2`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + Filter environments using ids. +- **`name`** :span[string]{.type-label} + The exact name of an Environment to be matched. +- **`partialName`** :span[string]{.type-label} + Filters the documents using the specified `partialName` fragment. +- **`skip`** :span[integer]{.type-label} *(required)* + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} *(required)* + Number of items to skip. Defaults to zero. Minimum `0`. +- **`type`** :span[array of string]{.type-label} + Filters the documents using the specified environment EnvironmentType. + +**Response** + +`200` — Success + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + List of tags assigned to this environment. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this environment. This should be short, preferably 5-20 characters. Minimum length 1. + - **`Slug`** :span[string]{.type-label} + Minimum length 1. + - **`SpaceId`** :span[string]{.type-label} + - **`Type`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "Description": "string", + "EnvironmentTags": [ + "string" + ], + "Id": "string", + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "Type": "string" + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Modify an existing environment + +:endpoint{method="PUT" path="/api/\{spaceId\}/environments/\{environmentId\}"} + +Also reachable at `/api/environments/{environmentId}`, `/api/spaces/{spaceIdentifier}/environments/{environmentId}`. + +**Path Parameters** + +- **`environmentId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`AllowDynamicInfrastructure`** :span[boolean]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EnvironmentId`** :span[string]{.type-label} *(required)* +- **`EnvironmentTags`** :span[array of string]{.type-label} +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. Maximum length 50. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`UseGuidedFailure`** :span[boolean]{.type-label} + +:::api-example{label="Request"} +```json +{ + "AllowDynamicInfrastructure": true, + "Description": "string", + "EnvironmentId": "string", + "EnvironmentTags": [ + "string" + ], + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "Name": "string", + "Slug": "string", + "SortOrder": 0, + "SpaceId": "string", + "UseGuidedFailure": true +} +``` +::: + +**Response** + +`200` — The environment after modifications have been applied. + +- **`AllowDynamicInfrastructure`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + List of tags assigned to this environment. +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this environment. This should be short, preferably 5-20 characters. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} + 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`** :span[string]{.type-label} +- **`UseGuidedFailure`** :span[boolean]{.type-label} + 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. + +:::api-example{label="Response"} +```json +{ + "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 the environment custom settings metadata from the extensions + +:endpoint{method="GET" path="/api/\{spaceId\}/environments/\{environmentId\}/metadata"} + +Also reachable at `/api/environments/{environmentId}/metadata`, `/api/spaces/{spaceIdentifier}/environments/{environmentId}/metadata`. + +**Path Parameters** + +- **`environmentId`** :span[string]{.type-label} *(required)* + The Id of the environment for which metadata is to be retrieved. +- **`spaceId`** :span[string]{.type-label} *(required)* + The Id of the space containing the environment. + +**Response** + +`200` — The requested Environment Metadata + +- **`ExtensionId`** :span[string]{.type-label} +- **`Metadata`** :span[object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Types`** :span[array of object]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "ExtensionId": "string", + "Metadata": { + "Description": "string", + "Types": [ + {} + ] + } + } +] +``` +::: + +## List all the variable set names (projects and library variable sets) that have variables that are scoped to only the given environment + +:endpoint{method="GET" path="/api/\{spaceId\}/environments/\{environmentId\}/singlyScopedVariableDetails"} + +Also reachable at `/api/environments/{environmentId}/singlyScopedVariableDetails`, `/api/spaces/{spaceIdentifier}/environments/{environmentId}/singlyScopedVariableDetails`. + +**Path Parameters** + +- **`environmentId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The names of LibraryVariableSets and VariableSets which contain one or more variables scoped to the requested environment. Along with boolean indication to show that there are unviewable/editable projects/libraries which also contain scoped variables. + +- **`HasUnauthorizedLibraryVariableSetVariables`** :span[boolean]{.type-label} +- **`HasUnauthorizedProjectVariables`** :span[boolean]{.type-label} +- **`VariableMap`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "HasUnauthorizedLibraryVariableSetVariables": true, + "HasUnauthorizedProjectVariables": true, + "VariableMap": { + "additionalProp1": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "additionalProp2": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "additionalProp3": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + } + } +} +``` +::: + +## Get a specific Deployment Environment + +:endpoint{method="GET" path="/api/\{spaceId\}/environments/\{id\}"} + +Also reachable at `/api/environments/{id}`, `/api/spaces/{spaceIdentifier}/environments/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Environment to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested Deployment Environment + +- **`AllowDynamicInfrastructure`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + List of tags assigned to this environment. +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this environment. This should be short, preferably 5-20 characters. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} + 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`** :span[string]{.type-label} +- **`UseGuidedFailure`** :span[boolean]{.type-label} + 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. + +:::api-example{label="Response"} +```json +{ + "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 +} +``` +::: + +## Delete an existing Environment + +:endpoint{method="DELETE" path="/api/\{spaceId\}/environments/\{id\}"} + +Also reachable at `/api/environments/{id}`, `/api/spaces/{spaceIdentifier}/environments/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Environment to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Return the list of machines in an environment that matches the filters requested by the user + +:endpoint{method="GET" path="/api/\{spaceId\}/environments/\{id\}/machines"} + +Also reachable at `/api/environments/{id}/machines`, `/api/spaces/{spaceIdentifier}/environments/{id}/machines`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Environment. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the space. + +**Query Parameters** + +- **`commStyles`** :span[array of string]{.type-label} +- **`deploymentTargetTypes`** :span[array of string]{.type-label} +- **`healthStatuses`** :span[array of string]{.type-label} +- **`isDisabled`** :span[boolean]{.type-label} +- **`partialName`** :span[string]{.type-label} +- **`roles`** :span[array of string]{.type-label} +- **`shellNames`** :span[array of string]{.type-label} +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items per page. Defaults to 20. Minimum `0`. +- **`targetTags`** :span[array of string]{.type-label} +- **`tenantIds`** :span[array of string]{.type-label} +- **`tenantTags`** :span[array of string]{.type-label} + +**Response** + +`200` — The lists of all machines that belong to the given environment, and matches any specified filters. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Architecture`** :span[string]{.type-label} + - **`Endpoint`** :span[object]{.type-label} + - **`EnvironmentIds`** :span[array of string]{.type-label} + - **`HasLatestCalamari`** :span[boolean]{.type-label} + - **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`IsInProcess`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MachinePolicyId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OperatingSystem`** :span[string]{.type-label} + - **`OperatingSystemVersion`** :span[string]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`ShellName`** :span[string]{.type-label} + - **`ShellVersion`** :span[string]{.type-label} + - **`SkipInitialHealthCheck`** :span[boolean]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`StatusSummary`** :span[string]{.type-label} + - **`TenantIds`** :span[array of string]{.type-label} + - **`TenantTags`** :span[array of string]{.type-label} + - **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + - **`Thumbprint`** :span[string]{.type-label} + - **`Uri`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {} + }, + "EnvironmentIds": [ + "string" + ], + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "Roles": [ + "string" + ], + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Uri": "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 +} +``` +::: + +## Get a specific Static, Parent or Ephemeral Environment by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/environments/\{id\}/v2"} + +Also reachable at `/api/spaces/{spaceIdentifier}/environments/{id}/v2`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Environment to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. + +**Response** + +`200` — The requested Static, Parent or Ephemeral Environment + +- **`Description`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + List of tags assigned to this environment. +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this environment. This should be short, preferably 5-20 characters. Minimum length 1. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. +- **`SpaceId`** :span[string]{.type-label} +- **`Type`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "EnvironmentTags": [ + "string" + ], + "Id": "string", + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "Type": "string" +} +``` +::: + +## List environments available for a project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/environments"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`partialName`** :span[string]{.type-label} + Filters the environments by partial name fragment. +- **`skip`** :span[integer]{.type-label} *(required)* + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} *(required)* + Number of items to take. Defaults to 30. Minimum `0`. +- **`type`** :span[array of string]{.type-label} + Filters the environments by EnvironmentType. + +**Response** + +`200` — Success + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + List of tags assigned to this environment. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this environment. This should be short, preferably 5-20 characters. Minimum length 1. + - **`Slug`** :span[string]{.type-label} + Minimum length 1. + - **`SpaceId`** :span[string]{.type-label} + - **`Type`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "Description": "string", + "EnvironmentTags": [ + "string" + ], + "Id": "string", + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "Type": "string" + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: diff --git a/src/pages/docs/api/ephemeral-environments.md b/src/pages/docs/api/ephemeral-environments.md new file mode 100644 index 0000000000..da488de6e9 --- /dev/null +++ b/src/pages/docs/api/ephemeral-environments.md @@ -0,0 +1,245 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Ephemeral Environments +--- + +## Deprovision an ephemeral environment + +:endpoint{method="POST" path="/api/\{spaceId\}/environments/ephemeral/\{id\}/deprovision"} + +Also reachable at `/api/spaces/{spaceIdentifier}/environments/ephemeral/{id}/deprovision`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the ephemeral environment to deprovision. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Deprovision an ephemeral environment response + +- **`DeprovisioningRuns`** :span[array of object]{.type-label} + - **`RunbookRunId`** :span[string]{.type-label} + - **`TaskId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DeprovisioningRuns": [ + { + "RunbookRunId": "string", + "TaskId": "string" + } + ] +} +``` +::: + +## Allow the creation of an ephemeral environment in a given space + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/environments/ephemeral"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/ephemeral`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`EnvironmentName`** :span[string]{.type-label} *(required)* + The name to give the new ephemeral environment. Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "EnvironmentName": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Id`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string" +} +``` +::: + +## Deprovision an ephemeral environment for a specific project + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/environments/ephemeral/\{environmentId\}/deprovision"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/ephemeral/{environmentId}/deprovision`. + +**Path Parameters** + +- **`environmentId`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Deprovision an ephemeral environment response + +- **`DeprovisioningRun`** :span[object]{.type-label} + - **`RunbookRunId`** :span[string]{.type-label} + - **`TaskId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DeprovisioningRun": { + "RunbookRunId": "string", + "TaskId": "string" + } +} +``` +::: + +## Mark a failed deprovisioning as successful for an ephemeral environment + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/environments/ephemeral/\{environmentId\}/deprovisioning/mark-successful"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/ephemeral/{environmentId}/deprovisioning/mark-successful`. + +**Path Parameters** + +- **`environmentId`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Response to mark deprovisioning as successful for an ephemeral environment + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Retry deprovisioning an ephemeral environment + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/environments/ephemeral/\{environmentId\}/deprovisioning/retry"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/ephemeral/{environmentId}/deprovisioning/retry`. + +**Path Parameters** + +- **`environmentId`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Response to retry deprovisioning an ephemeral environment + +- **`DeprovisioningRun`** :span[object]{.type-label} + - **`RunbookRunId`** :span[string]{.type-label} + - **`TaskId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DeprovisioningRun": { + "RunbookRunId": "string", + "TaskId": "string" + } +} +``` +::: + +## Mark a failed provisioning as successful for an ephemeral environment + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/environments/ephemeral/\{environmentId\}/provisioning/mark-successful"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/ephemeral/{environmentId}/provisioning/mark-successful`. + +**Path Parameters** + +- **`environmentId`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Response to mark provisioning as successful for an ephemeral environment + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Retry provisioning an ephemeral environment + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/environments/ephemeral/\{environmentId\}/provisioning/retry"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/ephemeral/{environmentId}/provisioning/retry`. + +**Path Parameters** + +- **`environmentId`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Response to retry provisioning an ephemeral environment + +- **`ProvisioningRun`** :span[object]{.type-label} + - **`RunbookRunId`** :span[string]{.type-label} + - **`TaskId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ProvisioningRun": { + "RunbookRunId": "string", + "TaskId": "string" + } +} +``` +::: + +## Get the status of an ephemeral environment for a given project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/environments/ephemeral/\{id\}/status"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/ephemeral/{id}/status`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the ephemeral environment whose status to report. +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +- **`Status`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Status": "string" +} +``` +::: diff --git a/src/pages/docs/api/event-retention.md b/src/pages/docs/api/event-retention.md new file mode 100644 index 0000000000..0f487e201f --- /dev/null +++ b/src/pages/docs/api/event-retention.md @@ -0,0 +1,207 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Event Retention +--- + +## Get the list of archived event files + +:endpoint{method="GET" path="/api/events/archives"} + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested Archived Event files + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`CreatedDate`** :span[string]{.type-label} + Format `date-time`. + - **`FileBytes`** :span[number]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ModifiedDate`** :span[string]{.type-label} + Format `date-time`. + - **`Name`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "CreatedDate": "2020-01-01T00:00:00.000Z", + "FileBytes": 0, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ModifiedDate": "2020-01-01T00:00:00.000Z", + "Name": "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 +} +``` +::: + +## Get the list of archived event files + +:endpoint{method="GET" path="/api/events/archives/v1"} + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested Archived Event files + +- **`ArchivedFiles`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`ItemType`** :span[string]{.type-label} + - **`Items`** :span[array of object]{.type-label} + - **`ItemsPerPage`** :span[integer]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastPageNumber`** :span[integer]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`NumberOfPages`** :span[integer]{.type-label} + - **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ArchivedFiles": { + "Id": "string", + "ItemType": "string", + "Items": [ + { + "CreatedDate": "2020-01-01T00:00:00.000Z", + "FileBytes": 0, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {}, + "ModifiedDate": "2020-01-01T00:00:00.000Z", + "Name": "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 + } +} +``` +::: + +## Download an archived event file + +:endpoint{method="GET" path="/api/events/archives/\{fileName\}"} + +**Path Parameters** + +- **`fileName`** :span[string]{.type-label} *(required)* + The file name of archived events file to download. + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Delete an archived event file + +:endpoint{method="DELETE" path="/api/events/archives/\{fileName\}"} + +**Path Parameters** + +- **`fileName`** :span[string]{.type-label} *(required)* + The file name of archived events file to delete. + +**Response** + +`200` — Success + +## Delete an archived event file + +:endpoint{method="DELETE" path="/api/events/archives/\{fileName\}/v1"} + +**Path Parameters** + +- **`fileName`** :span[string]{.type-label} *(required)* + The file name of archived events file to delete. + +**Response** + +`200` — Confirmation that the Archived Event File has been deleted, containing the filename + +- **`FileName`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "FileName": "string" +} +``` +::: diff --git a/src/pages/docs/api/events.md b/src/pages/docs/api/events.md new file mode 100644 index 0000000000..d166623a8f --- /dev/null +++ b/src/pages/docs/api/events.md @@ -0,0 +1,325 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Events +--- + +## Get a list of events + +:endpoint{method="GET" path="/api/\{spaceId\}/events"} + +Also reachable at `/api/events`, `/api/spaces/{spaceIdentifier}/events`. + +A list of all audit events collected to date, ordered by the date of the event in descending order. Events can be filtered by various criteria and can be returned as a csv file when the optional parameter 'asCsv' is set to true. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`asCsv`** :span[boolean]{.type-label} + Returns list of events as a csv file when set to true. +- **`documentTypes`** :span[array of string]{.type-label} + The document types to be matched, provided as a comma separated list of strings. +- **`environments`** :span[array of string]{.type-label} + The environment ids to be matched, provided as a comma separated list of strings. +- **`eventAgents`** :span[array of string]{.type-label} + The event agents to be matched, provided as a comma separated list of strings. +- **`eventCategories`** :span[array of string]{.type-label} + The event categories to be matched, provided as a comma separated list of strings. +- **`eventGroups`** :span[array of string]{.type-label} + The event groups to be matched, provided as a comma separated list of strings. +- **`excludeDifference`** :span[boolean]{.type-label} + Omits the change details of all events when set to true. +- **`from`** :span[string]{.type-label} + Filter events that occurred after this datetime. Format `date-time`. +- **`fromAutoId`** :span[integer]{.type-label} + Filter events after specified autoId. +- **`ids`** :span[string]{.type-label} + The event ids to be matched, provided as a comma separated list of strings. +- **`includeInternalEvents`** :span[boolean]{.type-label} + Exclude the machine-related CRUD events that were added for auto-deploy events. +- **`projectGroups`** :span[array of string]{.type-label} + The project group ids to be matched, provided as a comma separated list of strings. +- **`projects`** :span[array of string]{.type-label} + The project ids to be matched, provided as a comma separated list of strings. +- **`regarding`** :span[array of string]{.type-label} + The related document ids to be matched, provided as a comma separated list of strings. +- **`regardingAny`** :span[array of string]{.type-label} + The related document ids to be matched, provided as a comma separated list of strings. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`tags`** :span[array of string]{.type-label} + The canonical tag ids to be matched, provided as a comma separated list of strings. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`tenants`** :span[array of string]{.type-label} + The tenant ids to be matched, provided as a comma separated list of strings. +- **`to`** :span[string]{.type-label} + Filter events that occurred before this datetime. Format `date-time`. +- **`toAutoId`** :span[integer]{.type-label} + Filter events before specified autoId. +- **`user`** :span[string]{.type-label} +- **`users`** :span[array of string]{.type-label} + The user ids to be matched, provided as a comma separated list of strings. + +**Response** + +`200` — OK + +## Return the list of event agents + +:endpoint{method="GET" path="/api/\{spaceId\}/events/agents"} + +Also reachable at `/api/events/agents`, `/api/spaces/{spaceIdentifier}/events/agents`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested event agents + +- **`Id`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} +- **`Name`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Id": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } +] +``` +::: + +## List event categories + +:endpoint{method="GET" path="/api/\{spaceId\}/events/categories"} + +Also reachable at `/api/events/categories`, `/api/spaces/{spaceIdentifier}/events/categories`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`appliesTo`** :span[string]{.type-label} + +**Response** + +`200` — The requested Event Categories + +- **`Id`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} +- **`Name`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Id": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } +] +``` +::: + +## List subscription event document types + +:endpoint{method="GET" path="/api/\{spaceId\}/events/documenttypes"} + +Also reachable at `/api/events/documenttypes`, `/api/spaces/{spaceIdentifier}/events/documenttypes`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — A list of subscription event document types. + +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Id": "string", + "Name": "string" + } +] +``` +::: + +## List subscription event groups + +:endpoint{method="GET" path="/api/\{spaceId\}/events/groups"} + +Also reachable at `/api/events/groups`, `/api/spaces/{spaceIdentifier}/events/groups`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`appliesTo`** :span[string]{.type-label} + Filter results to only include Event Groups which are related to the provided string. eg. 'Machine'. + +**Response** + +`200` — A list of subscription event groups. + +- **`EventCategories`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} +- **`Name`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "EventCategories": [ + "string" + ], + "Id": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } +] +``` +::: + +## Get a single event by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/events/\{id\}"} + +Also reachable at `/api/events/{id}`, `/api/spaces/{spaceIdentifier}/events/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the event. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested event + +- **`ApiKeyHint`** :span[string]{.type-label} + Gets or sets the obfuscated hint of the API key used to authenticate the request, if applicable. +- **`ApiKeyId`** :span[string]{.type-label} + Gets or sets the ID of the API key used to authenticate the request, if applicable. +- **`Category`** :span[string]{.type-label} + Gets or sets the event category. +- **`ChangeDetails`** :span[object]{.type-label} + - **`Differences`** :span[string]{.type-label} + - **`DocumentContext`** :span[string]{.type-label} +- **`Comments`** :span[string]{.type-label} + Gets or sets any user-provided comments that were recorded with the event. +- **`Details`** :span[string]{.type-label} + Gets or sets the details of the event. For events representing a modification to a document use the ChangeDetails property. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IdentityEstablishedWith`** :span[string]{.type-label} + Gets or sets a description of how the user performing the event identified themselves to Octopus. +- **`IpAddress`** :span[string]{.type-label} + The IP address of the user that created the event. +- **`IsService`** :span[boolean]{.type-label} + Gets or sets whether the user who created the event is a service user or an interactive user. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Message`** :span[string]{.type-label} + Gets or sets the message text that summarizes the event. +- **`MessageHtml`** :span[string]{.type-label} + Gets or sets the message text that summarizes the event, HTML formatted with links to the related documents. +- **`MessageReferences`** :span[array of object]{.type-label} + Gets or sets an array of document ID's and indexes where they are mentioned in the message text. + - **`Length`** :span[integer]{.type-label} + - **`ReferencedDocumentId`** :span[string]{.type-label} + - **`StartIndex`** :span[integer]{.type-label} +- **`Occurred`** :span[string]{.type-label} + Gets or sets the date/time that the event took place. Format `date-time`. +- **`RelatedDocumentIds`** :span[array of string]{.type-label} + Gets or sets a collection of document ID's that this event relates to. Note that the document ID's may no longer exist. +- **`SpaceId`** :span[string]{.type-label} + Gets or sets the SpaceId of the event. This represents the space in which the event was raised. +- **`UserAgent`** :span[string]{.type-label} + Gets or sets the user agent header value from the request that triggered the event. +- **`UserId`** :span[string]{.type-label} + Gets or sets the ID of the user who created the event. +- **`Username`** :span[string]{.type-label} + Gets or sets the name of the user who created the event. + +:::api-example{label="Response"} +```json +{ + "ApiKeyHint": "string", + "ApiKeyId": "string", + "Category": "string", + "ChangeDetails": { + "Differences": "string", + "DocumentContext": "string" + }, + "Comments": "string", + "Details": "string", + "Id": "string", + "IdentityEstablishedWith": "string", + "IpAddress": "string", + "IsService": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Message": "string", + "MessageHtml": "string", + "MessageReferences": [ + { + "Length": 0, + "ReferencedDocumentId": "string", + "StartIndex": 0 + } + ], + "Occurred": "2020-01-01T00:00:00.000Z", + "RelatedDocumentIds": [ + "string" + ], + "SpaceId": "string", + "UserAgent": "string", + "UserId": "string", + "Username": "string" +} +``` +::: diff --git a/src/pages/docs/api/external-security-group-providers.md b/src/pages/docs/api/external-security-group-providers.md new file mode 100644 index 0000000000..3597ee3904 --- /dev/null +++ b/src/pages/docs/api/external-security-group-providers.md @@ -0,0 +1,36 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: External Security Group Providers +--- + +## GET /api/externalsecuritygroupproviders + +:endpoint{method="GET" path="/api/externalsecuritygroupproviders"} + +Lists the authentication providers that support external group lookups and are currently enabled + +**Response** + +`200` — The requested External Security Group Providers + +- **`Id`** :span[string]{.type-label} +- **`IsRoleBased`** :span[boolean]{.type-label} +- **`LookupUri`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`SupportsGroupLookup`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Id": "string", + "IsRoleBased": true, + "LookupUri": "string", + "Name": "string", + "SupportsGroupLookup": true + } +] +``` +::: diff --git a/src/pages/docs/api/features-configuration.md b/src/pages/docs/api/features-configuration.md new file mode 100644 index 0000000000..fb527da9d2 --- /dev/null +++ b/src/pages/docs/api/features-configuration.md @@ -0,0 +1,195 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Features Configuration +--- + +## Get features configuration + +:endpoint{method="GET" path="/api/featuresconfiguration"} + +Gets the features configuration of the current instance + +**Response** + +`200` — The requested features configuration + +- **`DefaultPowerShellEdition`** :span[string]{.type-label} +- **`HelpSidebarSupportLink`** :span[string]{.type-label} +- **`HelpSidebarSupportLinkLabel`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsAutomaticStepUpdatesEnabled`** :span[boolean]{.type-label} +- **`IsBuiltInWorkerEnabled`** :span[boolean]{.type-label} +- **`IsCommunityActionTemplatesEnabled`** :span[boolean]{.type-label} +- **`IsCompositeDockerHubRegistryFeedEnabled`** :span[boolean]{.type-label} +- **`IsConfigureFeedsWithLocalOrSmbPathsEnabled`** :span[boolean]{.type-label} +- **`IsExperimentalUIFeatureEnabled`** :span[boolean]{.type-label} +- **`IsGitHubAppEnabled`** :span[boolean]{.type-label} +- **`IsHelpSidebarEnabled`** :span[boolean]{.type-label} +- **`IsKubernetesCloudTargetDiscoveryEnabled`** :span[boolean]{.type-label} +- **`IsProjectsPageOnboardingEnabled`** :span[boolean]{.type-label} +- **`IsProjectsPageOptimizationEnabled`** :span[boolean]{.type-label} +- **`IsWebhookTriggerEnabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + +:::api-example{label="Response"} +```json +{ + "DefaultPowerShellEdition": "string", + "HelpSidebarSupportLink": "string", + "HelpSidebarSupportLinkLabel": "string", + "Id": "string", + "IsAutomaticStepUpdatesEnabled": true, + "IsBuiltInWorkerEnabled": true, + "IsCommunityActionTemplatesEnabled": true, + "IsCompositeDockerHubRegistryFeedEnabled": true, + "IsConfigureFeedsWithLocalOrSmbPathsEnabled": true, + "IsExperimentalUIFeatureEnabled": true, + "IsGitHubAppEnabled": true, + "IsHelpSidebarEnabled": true, + "IsKubernetesCloudTargetDiscoveryEnabled": true, + "IsProjectsPageOnboardingEnabled": true, + "IsProjectsPageOptimizationEnabled": true, + "IsWebhookTriggerEnabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +## Update features configuration + +:endpoint{method="PUT" path="/api/featuresconfiguration"} + +Updates the features configuration of the current instance + +**Request Body** + +- **`DefaultPowerShellEdition`** :span[string]{.type-label} + Default PowerShell edition for deployments and runbooks. +- **`HelpSidebarSupportLink`** :span[string]{.type-label} + Enable help sidebar support link feature. +- **`HelpSidebarSupportLinkLabel`** :span[string]{.type-label} + Custom label for the help sidebar support link. +- **`Id`** :span[string]{.type-label} + The id of features configuration resource. +- **`IsAutomaticStepUpdatesEnabled`** :span[boolean]{.type-label} + Enable automatic step updates feature. +- **`IsBuiltInWorkerEnabled`** :span[boolean]{.type-label} + Enable built-in worker feature. +- **`IsCommunityActionTemplatesEnabled`** :span[boolean]{.type-label} + Enable community action templates feature. +- **`IsCompositeDockerHubRegistryFeedEnabled`** :span[boolean]{.type-label} + Enable composite DockerHub registry feed feature. +- **`IsConfigureFeedsWithLocalOrSmbPathsEnabled`** :span[boolean]{.type-label} + Enable local or SMB paths for feeds feature. +- **`IsExperimentalUIFeatureEnabled`** :span[boolean]{.type-label} + Enable experimental UI feature. +- **`IsGitHubAppEnabled`** :span[boolean]{.type-label} + Enable the Octopus Deploy GitHub App. +- **`IsHelpSidebarEnabled`** :span[boolean]{.type-label} + Enable help sidebar feature. +- **`IsKubernetesCloudTargetDiscoveryEnabled`** :span[boolean]{.type-label} + Enable Kubernetes cloud target discovery feature. +- **`IsNavigationVisualUpliftEnabled`** :span[boolean]{.type-label} + Enable navigation visual uplift feature. +- **`IsProjectsPageOnboardingEnabled`** :span[boolean]{.type-label} + Enable projects page onboarding experience. +- **`IsProjectsPageOptimizationEnabled`** :span[boolean]{.type-label} + Enable new project page bff datasource. +- **`IsWebhookTriggerEnabled`** :span[boolean]{.type-label} + Enable the webhook triggers feature. + +:::api-example{label="Request"} +```json +{ + "DefaultPowerShellEdition": "string", + "HelpSidebarSupportLink": "string", + "HelpSidebarSupportLinkLabel": "string", + "Id": "string", + "IsAutomaticStepUpdatesEnabled": true, + "IsBuiltInWorkerEnabled": true, + "IsCommunityActionTemplatesEnabled": true, + "IsCompositeDockerHubRegistryFeedEnabled": true, + "IsConfigureFeedsWithLocalOrSmbPathsEnabled": true, + "IsExperimentalUIFeatureEnabled": true, + "IsGitHubAppEnabled": true, + "IsHelpSidebarEnabled": true, + "IsKubernetesCloudTargetDiscoveryEnabled": true, + "IsNavigationVisualUpliftEnabled": true, + "IsProjectsPageOnboardingEnabled": true, + "IsProjectsPageOptimizationEnabled": true, + "IsWebhookTriggerEnabled": true +} +``` +::: + +**Response** + +`200` — Confirmation that features configuration has been updated, containing the new configuration + +- **`DefaultPowerShellEdition`** :span[string]{.type-label} +- **`HelpSidebarSupportLink`** :span[string]{.type-label} +- **`HelpSidebarSupportLinkLabel`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsAutomaticStepUpdatesEnabled`** :span[boolean]{.type-label} +- **`IsBuiltInWorkerEnabled`** :span[boolean]{.type-label} +- **`IsCommunityActionTemplatesEnabled`** :span[boolean]{.type-label} +- **`IsCompositeDockerHubRegistryFeedEnabled`** :span[boolean]{.type-label} +- **`IsConfigureFeedsWithLocalOrSmbPathsEnabled`** :span[boolean]{.type-label} +- **`IsExperimentalUIFeatureEnabled`** :span[boolean]{.type-label} +- **`IsGitHubAppEnabled`** :span[boolean]{.type-label} +- **`IsHelpSidebarEnabled`** :span[boolean]{.type-label} +- **`IsKubernetesCloudTargetDiscoveryEnabled`** :span[boolean]{.type-label} +- **`IsProjectsPageOnboardingEnabled`** :span[boolean]{.type-label} +- **`IsProjectsPageOptimizationEnabled`** :span[boolean]{.type-label} +- **`IsWebhookTriggerEnabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + +:::api-example{label="Response"} +```json +{ + "DefaultPowerShellEdition": "string", + "HelpSidebarSupportLink": "string", + "HelpSidebarSupportLinkLabel": "string", + "Id": "string", + "IsAutomaticStepUpdatesEnabled": true, + "IsBuiltInWorkerEnabled": true, + "IsCommunityActionTemplatesEnabled": true, + "IsCompositeDockerHubRegistryFeedEnabled": true, + "IsConfigureFeedsWithLocalOrSmbPathsEnabled": true, + "IsExperimentalUIFeatureEnabled": true, + "IsGitHubAppEnabled": true, + "IsHelpSidebarEnabled": true, + "IsKubernetesCloudTargetDiscoveryEnabled": true, + "IsProjectsPageOnboardingEnabled": true, + "IsProjectsPageOptimizationEnabled": true, + "IsWebhookTriggerEnabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: diff --git a/src/pages/docs/api/feeds.md b/src/pages/docs/api/feeds.md new file mode 100644 index 0000000000..fdde802a8e --- /dev/null +++ b/src/pages/docs/api/feeds.md @@ -0,0 +1,696 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Feeds +--- + +## Get a list of feeds + +:endpoint{method="GET" path="/api/\{spaceId\}/feeds"} + +Also reachable at `/api/feeds`, `/api/spaces/{spaceIdentifier}/feeds`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the space for the Feed. + +**Query Parameters** + +- **`feedType`** :span[array of string]{.type-label} + The feed types to be matched, provided as a comma separated list of strings. +- **`ids`** :span[array of string]{.type-label} + The feed ids to be matched, provided as a comma separated list of strings. +- **`name`** :span[string]{.type-label} + The exact name of a feed to be matched. +- **`partialName`** :span[string]{.type-label} + The partial name of feeds to be matched. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested list of Feeds + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`FeedType`** :span[enum]{.type-label} + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`PackageAcquisitionLocationOptions`** :span[array of enum]{.type-label} + Allowed values: `Server`, `ExecutionTarget`, `NotAcquired`. + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "FeedType": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PackageAcquisitionLocationOptions": [ + "Server" + ], + "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 +} +``` +::: + +## Create a feed + +:endpoint{method="POST" path="/api/\{spaceId\}/feeds"} + +Also reachable at `/api/feeds`, `/api/spaces/{spaceIdentifier}/feeds`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the space that contains the feed. + +**Request Body** + +- **`ClientVersion`** :span[object]{.type-label} + - **`Format`** :span[enum]{.type-label} + Allowed values: `Semver`, `Maven`, `Docker`, `Octopus`, `Lexicographic`. + - **`HasMetadata`** :span[boolean]{.type-label} + - **`IsLegacyVersion`** :span[boolean]{.type-label} + - **`IsPrerelease`** :span[boolean]{.type-label} + - **`IsSemVer2`** :span[boolean]{.type-label} + - **`Major`** :span[integer]{.type-label} + - **`Metadata`** :span[string]{.type-label} + - **`Minor`** :span[integer]{.type-label} + - **`OriginalString`** :span[string]{.type-label} + - **`Patch`** :span[integer]{.type-label} + - **`Release`** :span[string]{.type-label} + - **`ReleaseLabels`** :span[array of string]{.type-label} + - **`Revision`** :span[integer]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`FeedType`** :span[enum]{.type-label} *(required)* + The type of the feed. + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the feed. Maximum length 44. +- **`PackageAcquisitionLocationOptions`** :span[array of enum]{.type-label} + The feed's package acquisition location options. + Allowed values: `Server`, `ExecutionTarget`, `NotAcquired`. +- **`Slug`** :span[string]{.type-label} + The slug of the feed. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The id of the space that contains the feed. + +:::api-example{label="Request"} +```json +{ + "ClientVersion": { + "Format": "Semver", + "HasMetadata": true, + "IsLegacyVersion": true, + "IsPrerelease": true, + "IsSemVer2": true, + "Major": 0, + "Metadata": "string", + "Minor": 0, + "OriginalString": "string", + "Patch": 0, + "Release": "string", + "ReleaseLabels": [ + "string" + ], + "Revision": 0, + "Version": "string" + }, + "FeedType": "None", + "Name": "string", + "PackageAcquisitionLocationOptions": [ + "Server" + ], + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`FeedType`** :span[enum]{.type-label} + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`PackageAcquisitionLocationOptions`** :span[array of enum]{.type-label} + Allowed values: `Server`, `ExecutionTarget`, `NotAcquired`. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "FeedType": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PackageAcquisitionLocationOptions": [ + "Server" + ], + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +## Get all Feeds + +:endpoint{method="GET" path="/api/\{spaceId\}/feeds/all"} + +Also reachable at `/api/feeds/all`, `/api/spaces/{spaceIdentifier}/feeds/all`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the space for the Feed. + +**Response** + +`200` — The requested list of Feeds + +- **`FeedType`** :span[enum]{.type-label} + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`PackageAcquisitionLocationOptions`** :span[array of enum]{.type-label} + Allowed values: `Server`, `ExecutionTarget`, `NotAcquired`. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "FeedType": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PackageAcquisitionLocationOptions": [ + "Server" + ], + "Slug": "string", + "SpaceId": "string" + } +] +``` +::: + +## Get all feed statistics + +:endpoint{method="GET" path="/api/\{spaceId\}/feeds/stats"} + +Also reachable at `/api/feeds/stats`, `/api/spaces/{spaceIdentifier}/feeds/stats`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the space for the Feed. + +**Response** + +`200` — The requested Feed Statistics + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`TotalPackages`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "TotalPackages": 0 +} +``` +::: + +## Get a feed resource by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/feeds/\{id\}"} + +Also reachable at `/api/feeds/{id}`, `/api/spaces/{spaceIdentifier}/feeds/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the feed resource. +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the space that contains the feed. + +**Response** + +`200` — The requested Feed + +- **`FeedType`** :span[enum]{.type-label} + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`PackageAcquisitionLocationOptions`** :span[array of enum]{.type-label} + Allowed values: `Server`, `ExecutionTarget`, `NotAcquired`. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "FeedType": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PackageAcquisitionLocationOptions": [ + "Server" + ], + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +## Modify a feed by ID + +:endpoint{method="PUT" path="/api/\{spaceId\}/feeds/\{id\}"} + +Also reachable at `/api/feeds/{id}`, `/api/spaces/{spaceIdentifier}/feeds/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the feed. +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the space that contains the feed. + +**Request Body** + +- **`ClientVersion`** :span[object]{.type-label} + - **`Format`** :span[enum]{.type-label} + Allowed values: `Semver`, `Maven`, `Docker`, `Octopus`, `Lexicographic`. + - **`HasMetadata`** :span[boolean]{.type-label} + - **`IsLegacyVersion`** :span[boolean]{.type-label} + - **`IsPrerelease`** :span[boolean]{.type-label} + - **`IsSemVer2`** :span[boolean]{.type-label} + - **`Major`** :span[integer]{.type-label} + - **`Metadata`** :span[string]{.type-label} + - **`Minor`** :span[integer]{.type-label} + - **`OriginalString`** :span[string]{.type-label} + - **`Patch`** :span[integer]{.type-label} + - **`Release`** :span[string]{.type-label} + - **`ReleaseLabels`** :span[array of string]{.type-label} + - **`Revision`** :span[integer]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`FeedType`** :span[enum]{.type-label} *(required)* + The type of the feed. + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`Id`** :span[string]{.type-label} *(required)* + The id of the feed. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the feed. Maximum length 44. +- **`PackageAcquisitionLocationOptions`** :span[array of enum]{.type-label} + The feed's package acquisition location options. + Allowed values: `Server`, `ExecutionTarget`, `NotAcquired`. +- **`Slug`** :span[string]{.type-label} + The slug of the feed. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The id of the space that contains the feed. + +:::api-example{label="Request"} +```json +{ + "ClientVersion": { + "Format": "Semver", + "HasMetadata": true, + "IsLegacyVersion": true, + "IsPrerelease": true, + "IsSemVer2": true, + "Major": 0, + "Metadata": "string", + "Minor": 0, + "OriginalString": "string", + "Patch": 0, + "Release": "string", + "ReleaseLabels": [ + "string" + ], + "Revision": 0, + "Version": "string" + }, + "FeedType": "None", + "Id": "string", + "Name": "string", + "PackageAcquisitionLocationOptions": [ + "Server" + ], + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — The response returned from the request to modify a feed. + +- **`FeedType`** :span[enum]{.type-label} + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`PackageAcquisitionLocationOptions`** :span[array of enum]{.type-label} + Allowed values: `Server`, `ExecutionTarget`, `NotAcquired`. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "FeedType": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PackageAcquisitionLocationOptions": [ + "Server" + ], + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +## Delete an existing Feed + +:endpoint{method="DELETE" path="/api/\{spaceId\}/feeds/\{id\}"} + +Also reachable at `/api/feeds/{id}`, `/api/spaces/{spaceIdentifier}/feeds/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the Feed. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the Space that contains the Feed. + +**Response** + +`200` — Success + +## Search the specified feed for packages based on the provided search term + +:endpoint{method="GET" path="/api/\{spaceId\}/feeds/\{id\}/packages/search"} + +Also reachable at `/api/feeds/{id}/packages/search`, `/api/spaces/{spaceIdentifier}/feeds/{id}/packages/search`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the feed resource. +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the space for the Feed. + +**Query Parameters** + +- **`packageType`** :span[string]{.type-label} + The package type to filter results by. Used by feeds that can contain multiple package types. Valid values are ContainerImage and HelmChart. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 20. Minimum `0`. +- **`term`** :span[string]{.type-label} + The term to search for. + +**Response** + +`200` — Holds a paginated collection of searched package descriptions + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`LatestVersion`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Description": "string", + "Id": "string", + "LatestVersion": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "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 +} +``` +::: + +## List available package versions for the specified feed and package + +:endpoint{method="GET" path="/api/\{spaceId\}/feeds/\{id\}/packages/versions"} + +Also reachable at `/api/feeds/{id}/packages/versions`, `/api/spaces/{spaceIdentifier}/feeds/{id}/packages/versions`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the feed resource. +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the space for the Feed. + +**Query Parameters** + +- **`filter`** :span[string]{.type-label} + Version number text to filter by. +- **`includePreRelease`** :span[boolean]{.type-label} + Flag to include pre-release versions, defaults to true. +- **`includeReleaseNotes`** :span[boolean]{.type-label} + Flag to include release notes, defaults to false. +- **`packageId`** :span[string]{.type-label} *(required)* + The id of the package. +- **`preReleaseTag`** :span[string]{.type-label} + The semver tag regex pattern to filter by. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`versionRange`** :span[string]{.type-label} + The range of versions to filter by. +- **`versionTagRegex`** :span[string]{.type-label} + The version-tag regex, applied to the full version string when set. +- **`versioningStrategy`** :span[string]{.type-label} + The versioning strategy: SemVer or MostRecentlyPublished. + +**Response** + +`200` — Contains a paginated collection of package versions returned from a search + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`FeedId`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`Published`** :span[string]{.type-label} + Date the package was published. Optional Property. Format `date-time`. + - **`ReleaseNotes`** :span[string]{.type-label} + Release notes for the package. + - **`SizeBytes`** :span[integer]{.type-label} + Size of package in bytes. Optional Property. + - **`Title`** :span[string]{.type-label} + Title of the package. This may be just the package name if the feed does not expose any version specific name. + - **`Version`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "FeedId": "string", + "Id": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PackageId": "string", + "Published": "2020-01-01T00:00:00.000Z", + "ReleaseNotes": "string", + "SizeBytes": 0, + "Title": "string", + "Version": "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 +} +``` +::: diff --git a/src/pages/docs/api/git-hub.md b/src/pages/docs/api/git-hub.md new file mode 100644 index 0000000000..947e6fc967 --- /dev/null +++ b/src/pages/docs/api/git-hub.md @@ -0,0 +1,819 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Git Hub +--- + +## Get the installation URL for the GitHub App + +:endpoint{method="GET" path="/api/github/accounts/install-url"} + +**Query Parameters** + +- **`redirectUri`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — OK + +## Get the settings for the GitHub App + +:endpoint{method="GET" path="/api/github/app/settings"} + +**Response** + +`200` — Success + +- **`CanUseGitHubApp`** :span[boolean]{.type-label} +- **`CanUseTrustedFlow`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CanUseGitHubApp": true, + "CanUseTrustedFlow": true +} +``` +::: + +## Get the status of the registration between Octopus Server and the GitHub App + +:endpoint{method="GET" path="/api/github/app/status"} + +**Response** + +`200` — Response containing the status of the registration between Octopus Server and the GitHub App + +- **`Status`** :span[string]{.type-label} + The status of the GitHub App registration. Valid values are: Connected, RegistrationInvalid, Error. Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Status": "string" +} +``` +::: + +## Get GitHub App connections for the space + +:endpoint{method="GET" path="/api/\{spaceId\}/github/connections"} + +Also reachable at `/api/spaces/{spaceIdentifier}/github/connections`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} *(required)* + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} *(required)* + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — All GitHub App connections for the space + +- **`Connections`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Installation`** :span[object]{.type-label} + - **`Status`** :span[enum]{.type-label} + Allowed values: `ConnectionNotFound`, `InstallationNotFound`, `InstallationSuspended`, `Connected`, `Error`. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Connections": [ + { + "Id": "string", + "Installation": { + "AccountAvatarUrl": "string", + "AccountId": "string", + "AccountLogin": "string", + "AccountType": "string", + "AllRepositories": true, + "InstallationId": "string" + }, + "Status": "ConnectionNotFound" + } + ], + "ItemsPerPage": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new GitHub App connection for an installation + +:endpoint{method="POST" path="/api/\{spaceId\}/github/connections"} + +Also reachable at `/api/spaces/{spaceIdentifier}/github/connections`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`InstallationId`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`RepositoryIds`** :span[array of string]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "InstallationId": "string", + "RepositoryIds": [ + "string" + ], + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Get the GitHub repositories for the current connection + +:endpoint{method="GET" path="/api/\{spaceId\}/github/connections/\{connectionId\}/repositories"} + +Also reachable at `/api/spaces/{spaceIdentifier}/github/connections/{connectionId}/repositories`. + +**Path Parameters** + +- **`connectionId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — GitHub repositories available for the current connection + +- **`Repositories`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} + - **`GitUrl`** :span[string]{.type-label} + - **`IsAdmin`** :span[boolean]{.type-label} + - **`IsPrivate`** :span[boolean]{.type-label} + - **`Language`** :span[string]{.type-label} + - **`RepositoryId`** :span[string]{.type-label} + - **`RepositoryName`** :span[string]{.type-label} + - **`Visibility`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Repositories": [ + { + "DefaultBranch": "string", + "GitUrl": "string", + "IsAdmin": true, + "IsPrivate": true, + "Language": "string", + "RepositoryId": "string", + "RepositoryName": "string", + "Visibility": "string" + } + ] +} +``` +::: + +## Get a single GitHub app connection by id + +:endpoint{method="GET" path="/api/\{spaceId\}/github/connections/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/github/connections/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — A GitHub app connection + +- **`Id`** :span[string]{.type-label} +- **`Installation`** :span[object]{.type-label} + - **`AccountAvatarUrl`** :span[string]{.type-label} + - **`AccountId`** :span[string]{.type-label} + - **`AccountLogin`** :span[string]{.type-label} + - **`AccountType`** :span[string]{.type-label} + - **`AllRepositories`** :span[boolean]{.type-label} + true if the installation has access to all repositories in the account, false if it has access to only selected repositories. + - **`InstallationId`** :span[string]{.type-label} +- **`Repositories`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} + - **`GitUrl`** :span[string]{.type-label} + - **`IsAdmin`** :span[boolean]{.type-label} + - **`IsPrivate`** :span[boolean]{.type-label} + - **`Language`** :span[string]{.type-label} + - **`RepositoryId`** :span[string]{.type-label} + - **`RepositoryName`** :span[string]{.type-label} + - **`Visibility`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Status`** :span[string]{.type-label} + Minimum length 1. +- **`StatusUserMessage`** :span[string]{.type-label} +- **`UnknownRepositories`** :span[array of object]{.type-label} + Repositories IDs that are configured on the connection but do not have a matching repository returned from GitHub. + - **`RepositoryId`** :span[string]{.type-label} + - **`RepositoryName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "Installation": { + "AccountAvatarUrl": "string", + "AccountId": "string", + "AccountLogin": "string", + "AccountType": "string", + "AllRepositories": true, + "InstallationId": "string" + }, + "Repositories": [ + { + "DefaultBranch": "string", + "GitUrl": "string", + "IsAdmin": true, + "IsPrivate": true, + "Language": "string", + "RepositoryId": "string", + "RepositoryName": "string", + "Visibility": "string" + } + ], + "SpaceId": "string", + "Status": "string", + "StatusUserMessage": "string", + "UnknownRepositories": [ + { + "RepositoryId": "string", + "RepositoryName": "string" + } + ] +} +``` +::: + +## Update a GitHub App connection with a new set of repositories + +:endpoint{method="PUT" path="/api/\{spaceId\}/github/connections/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/github/connections/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Id`** :span[string]{.type-label} *(required)* +- **`RepositoryIds`** :span[array of string]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "RepositoryIds": [ + "string" + ], + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — GitHub app connection modified result + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Delete a GitHub App Connection + +:endpoint{method="DELETE" path="/api/\{spaceId\}/github/connections/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/github/connections/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the GitHub connection to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Used to indicate that a GitHub App Connection has been deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Recover GitHub App connection after the registration has changed + +:endpoint{method="POST" path="/api/\{spaceId\}/github/connections/\{id\}/recover"} + +Also reachable at `/api/spaces/{spaceIdentifier}/github/connections/{id}/recover`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Id`** :span[string]{.type-label} *(required)* +- **`RepositoryIds`** :span[array of string]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "RepositoryIds": [ + "string" + ], + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — GitHub app connection recovery result + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Recover GitHub App connection after the installation was not found + +:endpoint{method="POST" path="/api/\{spaceId\}/github/connections/\{id\}/recover-not-found"} + +Also reachable at `/api/spaces/{spaceIdentifier}/github/connections/{id}/recover-not-found`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Id`** :span[string]{.type-label} *(required)* +- **`InstallationId`** :span[string]{.type-label} *(required)* +- **`RepositoryIds`** :span[array of string]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "InstallationId": "string", + "RepositoryIds": [ + "string" + ], + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — GitHub app connection not-found recovery result + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Refresh the GitHub App connection token + +:endpoint{method="POST" path="/api/\{spaceId\}/github/connections/\{id\}/refresh"} + +Also reachable at `/api/spaces/{spaceIdentifier}/github/connections/{id}/refresh`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — GitHub app connection has been refreshed + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get a list of GitHub organisations accessible to the current GitHub OAuth user. Request will fail if the user does not have a valid GitHub OAuth token + +:endpoint{method="GET" path="/api/\{spaceId\}/github/installations"} + +Also reachable at `/api/spaces/{spaceIdentifier}/github/installations`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`excludeConnected`** :span[boolean]{.type-label} + +**Response** + +`200` — List of GitHub organisations accessible to the current GitHub OAuth user + +- **`Installations`** :span[array of object]{.type-label} + - **`AccountAvatarUrl`** :span[string]{.type-label} + - **`AccountId`** :span[string]{.type-label} + - **`AccountLogin`** :span[string]{.type-label} + - **`AccountType`** :span[string]{.type-label} + - **`AllRepositories`** :span[boolean]{.type-label} + true if the installation has access to all repositories in the account, false if it has access to only selected repositories. + - **`InstallationId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Installations": [ + { + "AccountAvatarUrl": "string", + "AccountId": "string", + "AccountLogin": "string", + "AccountType": "string", + "AllRepositories": true, + "InstallationId": "string" + } + ] +} +``` +::: + +## Handle the response from GitHub after an application has been installed or updated + +:endpoint{method="GET" path="/api/github/installations/updated"} + +**Query Parameters** + +- **`installation_id`** :span[string]{.type-label} +- **`redirectUri`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — OK + +## Get the GitHub repositories for an installation visible to the current user https://docs.github.com/en/rest/apps/installations?apiVersion=2022-11-28#list-repositories-accessible-to-the-user-access-token + +:endpoint{method="GET" path="/api/github/installations/\{installationId\}/repositories"} + +**Path Parameters** + +- **`installationId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} *(required)* + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} *(required)* + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Success + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} + - **`GitUrl`** :span[string]{.type-label} + - **`IsAdmin`** :span[boolean]{.type-label} + - **`IsPrivate`** :span[boolean]{.type-label} + - **`Language`** :span[string]{.type-label} + - **`RepositoryId`** :span[string]{.type-label} + - **`RepositoryName`** :span[string]{.type-label} + - **`Visibility`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "DefaultBranch": "string", + "GitUrl": "string", + "IsAdmin": true, + "IsPrivate": true, + "Language": "string", + "RepositoryId": "string", + "RepositoryName": "string", + "Visibility": "string" + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Reset the GitHub app registration for this Octopus instance. This is a destructive command and will break all existing GitHub app connections across the instance. This should only be used as a last resort to recover connectivity with GitHub + +:endpoint{method="POST" path="/api/github/reset-registration"} + +**Response** + +`200` — GitHub app registration was successfully deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Search for GitHub repositories for an account visible to the current user https://docs.github.com/en/rest/search/search?apiVersion=2022-11-28#search-repositories + +:endpoint{method="GET" path="/api/github/search/\{accountName\}/repositories"} + +**Path Parameters** + +- **`accountName`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`keyword`** :span[string]{.type-label} +- **`skip`** :span[integer]{.type-label} *(required)* + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} *(required)* + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Success + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} + - **`GitUrl`** :span[string]{.type-label} + - **`IsAdmin`** :span[boolean]{.type-label} + - **`IsPrivate`** :span[boolean]{.type-label} + - **`Language`** :span[string]{.type-label} + - **`RepositoryId`** :span[string]{.type-label} + - **`RepositoryName`** :span[string]{.type-label} + - **`Visibility`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "DefaultBranch": "string", + "GitUrl": "string", + "IsAdmin": true, + "IsPrivate": true, + "Language": "string", + "RepositoryId": "string", + "RepositoryName": "string", + "Visibility": "string" + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get status of the users current authorization + +:endpoint{method="GET" path="/api/github/user/app/authorization_status"} + +**Query Parameters** + +- **`includeUserDetails`** :span[boolean]{.type-label} + +**Response** + +`200` — Get the status of the user's current authorization. + +- **`CanAuthorize`** :span[boolean]{.type-label} +- **`IsAuthorized`** :span[boolean]{.type-label} +- **`UserDetails`** :span[object]{.type-label} + - **`AvatarUrl`** :span[string]{.type-label} + - **`Login`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`PrimaryEmail`** :span[string]{.type-label} + - **`RefreshTokenValidTo`** :span[string]{.type-label} + Format `date-time`. + - **`TokenValidTo`** :span[string]{.type-label} + Format `date-time`. + +:::api-example{label="Response"} +```json +{ + "CanAuthorize": true, + "IsAuthorized": true, + "UserDetails": { + "AvatarUrl": "string", + "Login": "string", + "Name": "string", + "PrimaryEmail": "string", + "RefreshTokenValidTo": "2020-01-01T00:00:00.000Z", + "TokenValidTo": "2020-01-01T00:00:00.000Z" + } +} +``` +::: + +## Authorize the current user with the Octopus GitHub app + +:endpoint{method="POST" path="/api/github/user/app/authorize"} + +**Request Body** + +- **`RedirectUri`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "RedirectUri": "string" +} +``` +::: + +**Response** + +`200` — GitHub URL to authorize the GitHub app + +- **`AuthorizeUri`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "AuthorizeUri": "string" +} +``` +::: + +## Exchange a GitHub App authorization code for an access token and store in the instance + +:endpoint{method="POST" path="/api/github/user/app/exchange-access-code"} + +**Request Body** + +- **`Code`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "Code": "string" +} +``` +::: + +**Response** + +`200` — Reports the success of exchanging a GitHub App authorization code for an access token + +- **`ErrorMessage`** :span[string]{.type-label} +- **`Status`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "ErrorMessage": "string", + "Status": "string" +} +``` +::: + +## Exchange a GitHub App authorization code for an access token and store in the instance + +:endpoint{method="GET" path="/api/github/user/app/token"} + +**Query Parameters** + +- **`code`** :span[string]{.type-label} *(required)* +- **`redirectUri`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — OK + +## Deauthorize the GitHub app for the current user, removing this users GitHub tokens from Octopus + +:endpoint{method="DELETE" path="/api/github/user/app/token"} + +**Response** + +`200` — Deauthorized GitHub app user + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Refresh the GitHub current app user. Refreshing the users token and cached GitHub account details + +:endpoint{method="POST" path="/api/github/user/app/token/refresh"} + +**Response** + +`200` — GitHub App user has been successfully refreshed + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Test connectivity to GitHub using the provided credentials + +:endpoint{method="POST" path="/api/githubissuetracker/connectivitycheck"} + +**Request Body** + +- **`BaseUrl`** :span[string]{.type-label} *(required)* + The GitHub base URL to test connectivity to. Minimum length 1. +- **`Password`** :span[string]{.type-label} + The GitHub personal access token or password for authentication. If not provided, will be retrieved from configuration. +- **`UserName`** :span[string]{.type-label} + The GitHub username for authentication. + +:::api-example{label="Request"} +```json +{ + "BaseUrl": "string", + "Password": "string", + "UserName": "string" +} +``` +::: + +**Response** + +`200` — Result of testing connectivity to GitHub + +- **`Messages`** :span[array of object]{.type-label} + Messages from the connectivity check. + - **`Category`** :span[enum]{.type-label} + Allowed values: `Info`, `Warning`, `Error`. + - **`Message`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Messages": [ + { + "Category": "Info", + "Message": "string" + } + ] +} +``` +::: diff --git a/src/pages/docs/api/home.md b/src/pages/docs/api/home.md new file mode 100644 index 0000000000..883b02a872 --- /dev/null +++ b/src/pages/docs/api/home.md @@ -0,0 +1,94 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Home +--- + +## GET /api/{spaceId} + +:endpoint{method="GET" path="/api/\{spaceId\}"} + +Returns a document describing the specified Space and links to other parts of the API that apply to the Space. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + Must match `Spaces-\d+`. + +**Response** + +`200` — Success + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +## GET /api/ + +:endpoint{method="GET" path="/api/"} + +Returns a document describing the current Octopus Server and links to other parts of the API. + +**Response** + +`200` — Success + +- **`ApiVersion`** :span[string]{.type-label} +- **`Application`** :span[string]{.type-label} +- **`HasLongTermSupport`** :span[boolean]{.type-label} + Every release from 2020.1 onwards of Octopus Server comes with long-term support. I wanted to remove this from the API, but that would be a breaking change. @michaelnoonan 2020-04-20. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`InstallationId`** :span[string]{.type-label} + Format `uuid`. +- **`IsEarlyAccessProgram`** :span[boolean]{.type-label} + Defaults to `false`. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Version`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ApiVersion": "string", + "Application": "string", + "HasLongTermSupport": true, + "Id": "string", + "InstallationId": "00000000-0000-0000-0000-000000000000", + "IsEarlyAccessProgram": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Version": "string" +} +``` +::: diff --git a/src/pages/docs/api/icons.md b/src/pages/docs/api/icons.md new file mode 100644 index 0000000000..4201fbac11 --- /dev/null +++ b/src/pages/docs/api/icons.md @@ -0,0 +1,197 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Icons +--- + +## Get details of all icons + +:endpoint{method="GET" path="/api/icons/all"} + +**Response** + +`200` — The requested list of Icons + +- **`icons`** :span[array of object]{.type-label} + - **`iconHeight`** :span[integer]{.type-label} + - **`iconPath`** :span[string]{.type-label} + - **`iconWidth`** :span[integer]{.type-label} + - **`id`** :span[string]{.type-label} + - **`label`** :span[string]{.type-label} + - **`searchTerms`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "icons": [ + { + "iconHeight": 0, + "iconPath": "string", + "iconWidth": 0, + "id": "string", + "label": "string", + "searchTerms": [ + "string" + ] + } + ] +} +``` +::: + +## Get all icon categories and icon IDs contained in each category + +:endpoint{method="GET" path="/api/icons/categories"} + +**Response** + +`200` — The requested Icon Categories + +- **`categories`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "categories": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + } +} +``` +::: + +## Modify the logo of a Space to be a specified icon + +:endpoint{method="POST" path="/api/spaces/\{spaceId\}/logo/icon"} + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the Space to change logo for. Example: 'Space-1'. + +**Request Body** + +- **`IconColor`** :span[string]{.type-label} *(required)* + Color of the icon in hex format. Example: '#0D80D8'. Minimum length 1. Must match `^#[0-9a-fA-F]{6}$`. +- **`IconId`** :span[string]{.type-label} *(required)* + ID of the icon. Example: 'octopus-deploy'. Minimum length 1. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the Space to change logo for. Example: 'Space-1'. + +:::api-example{label="Request"} +```json +{ + "IconColor": "string", + "IconId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Space Icon has been modified + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Modify the logo of a project to be a specified icon + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/logo/icon"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/logo/icon`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project to change logo for. Example: 'Projects-1'. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`IconColor`** :span[string]{.type-label} *(required)* + Color of the icon in hex format. Example: '#0D80D8'. Minimum length 1. Must match `^#[0-9a-fA-F]{6}$`. +- **`IconId`** :span[string]{.type-label} *(required)* + ID of the icon. Example: 'octopus-deploy'. Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} *(required)* + The ID of the project to change logo for. Example: 'Projects-1'. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "IconColor": "string", + "IconId": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Project Icon has been modified + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Modify the logo of a tenant to be a specified icon + +:endpoint{method="POST" path="/api/\{spaceId\}/tenants/\{tenantId\}/logo/icon"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/{tenantId}/logo/icon`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`tenantId`** :span[string]{.type-label} *(required)* + The ID of the tenant to change logo for. Example: 'Tenants-1'. + +**Request Body** + +- **`IconColor`** :span[string]{.type-label} *(required)* + Color of the icon in hex format. Example: '#0D80D8'. Minimum length 1. Must match `^#[0-9a-fA-F]{6}$`. +- **`IconId`** :span[string]{.type-label} *(required)* + ID of the icon. Example: 'octopus-deploy'. Minimum length 1. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`TenantId`** :span[string]{.type-label} *(required)* + The ID of the tenant to change logo for. Example: 'Tenants-1'. + +:::api-example{label="Request"} +```json +{ + "IconColor": "string", + "IconId": "string", + "SpaceId": "string", + "TenantId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Tenant Icon has been modified + +:::api-example{label="Response"} +```json +{} +``` +::: diff --git a/src/pages/docs/api/insights.md b/src/pages/docs/api/insights.md new file mode 100644 index 0000000000..34db70e255 --- /dev/null +++ b/src/pages/docs/api/insights.md @@ -0,0 +1,1459 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Insights +--- + +## Get a list of Insights Reports + +:endpoint{method="GET" path="/api/\{spaceId\}/insights/reports"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports`. + +Returns a paginated list of the Insights Reports in the supplied Octopus Deploy Space. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Success + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`AllTenants`** :span[boolean]{.type-label} + - **`ChannelIds`** :span[array of string]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`EnvironmentGroups`** :span[array of object]{.type-label} + - **`IconColor`** :span[string]{.type-label} + - **`IconId`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`ProjectGroupIds`** :span[array of string]{.type-label} + - **`ProjectIds`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`TenantIds`** :span[array of string]{.type-label} + - **`TenantMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedAndUntenanted`, `Tenanted`. + - **`TenantTags`** :span[array of string]{.type-label} + - **`TimeZone`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "AllTenants": true, + "ChannelIds": [ + "string" + ], + "Description": "string", + "EnvironmentGroups": [ + {} + ], + "IconColor": "string", + "IconId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantMode": "Untenanted", + "TenantTags": [ + "string" + ], + "TimeZone": "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 +} +``` +::: + +## Create an Insights Report + +:endpoint{method="POST" path="/api/\{spaceId\}/insights/reports"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports`. + +Creates a new Insights Report. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`AllTenants`** :span[boolean]{.type-label} + If true, all tenants in the space will be included in the report. +- **`ChannelIds`** :span[array of string]{.type-label} *(required)* + The channels for the report. +- **`Description`** :span[string]{.type-label} + The description for the report. +- **`EnvironmentGroups`** :span[array of object]{.type-label} *(required)* + The environment groups for the report. + - **`Environments`** :span[array of string]{.type-label} *(required)* + - **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the report. Minimum length 1. Maximum length 200. +- **`ProjectGroupIds`** :span[array of string]{.type-label} *(required)* + The project groups for the report. +- **`ProjectIds`** :span[array of string]{.type-label} *(required)* + The projects for the report. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantIds`** :span[array of string]{.type-label} *(required)* + The tenants for the report. +- **`TenantMode`** :span[enum]{.type-label} + The kind of deployments that will be included in this report. + Allowed values: `Untenanted`, `TenantedAndUntenanted`, `Tenanted`. +- **`TenantTags`** :span[array of string]{.type-label} *(required)* + The tenant tags the report. +- **`TimeZone`** :span[string]{.type-label} *(required)* + The timezone of the report. + +:::api-example{label="Request"} +```json +{ + "AllTenants": true, + "ChannelIds": [ + "string" + ], + "Description": "string", + "EnvironmentGroups": [ + { + "Environments": [ + "string" + ], + "Name": "string" + } + ], + "Name": "string", + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantMode": "Untenanted", + "TenantTags": [ + "string" + ], + "TimeZone": "string" +} +``` +::: + +**Response** + +`200` — Success + +- **`AllTenants`** :span[boolean]{.type-label} +- **`ChannelIds`** :span[array of string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EnvironmentGroups`** :span[array of object]{.type-label} + - **`Environments`** :span[array of string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`IconColor`** :span[string]{.type-label} +- **`IconId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ProjectGroupIds`** :span[array of string]{.type-label} +- **`ProjectIds`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedAndUntenanted`, `Tenanted`. +- **`TenantTags`** :span[array of string]{.type-label} +- **`TimeZone`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AllTenants": true, + "ChannelIds": [ + "string" + ], + "Description": "string", + "EnvironmentGroups": [ + { + "Environments": [ + "string" + ], + "Name": "string" + } + ], + "IconColor": "string", + "IconId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantMode": "Untenanted", + "TenantTags": [ + "string" + ], + "TimeZone": "string" +} +``` +::: + +## Create an Insights Report + +:endpoint{method="POST" path="/api/\{spaceId\}/insights/reports/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports/v1`. + +Creates a new Insights Report. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`AllTenants`** :span[boolean]{.type-label} + If true, all tenants in the space will be included in the report. +- **`ChannelIds`** :span[array of string]{.type-label} *(required)* + The channels for the report. +- **`Description`** :span[string]{.type-label} + The description for the report. +- **`EnvironmentGroups`** :span[array of object]{.type-label} *(required)* + The environment groups for the report. + - **`Environments`** :span[array of string]{.type-label} *(required)* + - **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the report. Minimum length 1. Maximum length 200. +- **`ProjectGroupIds`** :span[array of string]{.type-label} *(required)* + The project groups for the report. +- **`ProjectIds`** :span[array of string]{.type-label} *(required)* + The projects for the report. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantIds`** :span[array of string]{.type-label} *(required)* + The tenants for the report. +- **`TenantMode`** :span[enum]{.type-label} + The kind of deployments that will be included in this report. + Allowed values: `Untenanted`, `TenantedAndUntenanted`, `Tenanted`. +- **`TenantTags`** :span[array of string]{.type-label} *(required)* + The tenant tags the report. +- **`TimeZone`** :span[string]{.type-label} *(required)* + The timezone of the report. + +:::api-example{label="Request"} +```json +{ + "AllTenants": true, + "ChannelIds": [ + "string" + ], + "Description": "string", + "EnvironmentGroups": [ + { + "Environments": [ + "string" + ], + "Name": "string" + } + ], + "Name": "string", + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantMode": "Untenanted", + "TenantTags": [ + "string" + ], + "TimeZone": "string" +} +``` +::: + +**Response** + +`200` — Success + +- **`Report`** :span[object]{.type-label} + - **`AllTenants`** :span[boolean]{.type-label} + - **`ChannelIds`** :span[array of string]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`EnvironmentGroups`** :span[array of object]{.type-label} + - **`IconColor`** :span[string]{.type-label} + - **`IconId`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`ProjectGroupIds`** :span[array of string]{.type-label} + - **`ProjectIds`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`TenantIds`** :span[array of string]{.type-label} + - **`TenantMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedAndUntenanted`, `Tenanted`. + - **`TenantTags`** :span[array of string]{.type-label} + - **`TimeZone`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Report": { + "AllTenants": true, + "ChannelIds": [ + "string" + ], + "Description": "string", + "EnvironmentGroups": [ + { + "Environments": [ + "string" + ], + "Name": "string" + } + ], + "IconColor": "string", + "IconId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantMode": "Untenanted", + "TenantTags": [ + "string" + ], + "TimeZone": "string" + } +} +``` +::: + +## GET /api/{spaceId}/insights/reports/{id} + +:endpoint{method="GET" path="/api/\{spaceId\}/insights/reports/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +- **`AllTenants`** :span[boolean]{.type-label} +- **`ChannelIds`** :span[array of string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EnvironmentGroups`** :span[array of object]{.type-label} + - **`Environments`** :span[array of string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`IconColor`** :span[string]{.type-label} +- **`IconId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ProjectGroupIds`** :span[array of string]{.type-label} +- **`ProjectIds`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedAndUntenanted`, `Tenanted`. +- **`TenantTags`** :span[array of string]{.type-label} +- **`TimeZone`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AllTenants": true, + "ChannelIds": [ + "string" + ], + "Description": "string", + "EnvironmentGroups": [ + { + "Environments": [ + "string" + ], + "Name": "string" + } + ], + "IconColor": "string", + "IconId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantMode": "Untenanted", + "TenantTags": [ + "string" + ], + "TimeZone": "string" +} +``` +::: + +## Update an existing Insights Report + +:endpoint{method="PUT" path="/api/\{spaceId\}/insights/reports/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports/{id}`. + +Updates an existing Insights Report + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The Id of the Insights Report. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`AllTenants`** :span[boolean]{.type-label} *(required)* + If true, all tenants in the space will be included in the report. +- **`ChannelIds`** :span[array of string]{.type-label} *(required)* + The channels for the report. +- **`Description`** :span[string]{.type-label} + The description for the report. +- **`EnvironmentGroups`** :span[array of object]{.type-label} *(required)* + The environment groups for the report. + - **`Environments`** :span[array of string]{.type-label} *(required)* + - **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Id`** :span[string]{.type-label} *(required)* + The Id of the Insights Report. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the report. Minimum length 1. Maximum length 200. +- **`ProjectGroupIds`** :span[array of string]{.type-label} *(required)* + The project groups for the report. +- **`ProjectIds`** :span[array of string]{.type-label} *(required)* + The projects for the report. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`TenantIds`** :span[array of string]{.type-label} *(required)* + The tenants for the report. +- **`TenantMode`** :span[enum]{.type-label} *(required)* + The kind of deployments that will be included in this report. + Allowed values: `Untenanted`, `TenantedAndUntenanted`, `Tenanted`. +- **`TenantTags`** :span[array of string]{.type-label} *(required)* + The tenant tags for the report. +- **`TimeZone`** :span[string]{.type-label} *(required)* + The timezone of the report. + +:::api-example{label="Request"} +```json +{ + "AllTenants": true, + "ChannelIds": [ + "string" + ], + "Description": "string", + "EnvironmentGroups": [ + { + "Environments": [ + "string" + ], + "Name": "string" + } + ], + "Id": "string", + "Name": "string", + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantMode": "Untenanted", + "TenantTags": [ + "string" + ], + "TimeZone": "string" +} +``` +::: + +**Response** + +`200` — Success + +- **`AllTenants`** :span[boolean]{.type-label} +- **`ChannelIds`** :span[array of string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EnvironmentGroups`** :span[array of object]{.type-label} + - **`Environments`** :span[array of string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`IconColor`** :span[string]{.type-label} +- **`IconId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ProjectGroupIds`** :span[array of string]{.type-label} +- **`ProjectIds`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantIds`** :span[array of string]{.type-label} +- **`TenantMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedAndUntenanted`, `Tenanted`. +- **`TenantTags`** :span[array of string]{.type-label} +- **`TimeZone`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AllTenants": true, + "ChannelIds": [ + "string" + ], + "Description": "string", + "EnvironmentGroups": [ + { + "Environments": [ + "string" + ], + "Name": "string" + } + ], + "IconColor": "string", + "IconId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantMode": "Untenanted", + "TenantTags": [ + "string" + ], + "TimeZone": "string" +} +``` +::: + +## Delete an Insights Report by ID + +:endpoint{method="DELETE" path="/api/\{spaceId\}/insights/reports/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports/{id}`. + +Deletes an existing Insights Report. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Insights Report to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## GET /api/{spaceId}/insights/reports/{id}/v1 + +:endpoint{method="GET" path="/api/\{spaceId\}/insights/reports/\{id\}/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports/{id}/v1`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +- **`Report`** :span[object]{.type-label} + - **`AllTenants`** :span[boolean]{.type-label} + - **`ChannelIds`** :span[array of string]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`EnvironmentGroups`** :span[array of object]{.type-label} + - **`IconColor`** :span[string]{.type-label} + - **`IconId`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`ProjectGroupIds`** :span[array of string]{.type-label} + - **`ProjectIds`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`TenantIds`** :span[array of string]{.type-label} + - **`TenantMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedAndUntenanted`, `Tenanted`. + - **`TenantTags`** :span[array of string]{.type-label} + - **`TimeZone`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Report": { + "AllTenants": true, + "ChannelIds": [ + "string" + ], + "Description": "string", + "EnvironmentGroups": [ + { + "Environments": [ + "string" + ], + "Name": "string" + } + ], + "IconColor": "string", + "IconId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantMode": "Untenanted", + "TenantTags": [ + "string" + ], + "TimeZone": "string" + } +} +``` +::: + +## Update an existing Insights Report + +:endpoint{method="PUT" path="/api/\{spaceId\}/insights/reports/\{id\}/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports/{id}/v1`. + +Updates an existing Insights Report + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The Id of the Insights Report. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`AllTenants`** :span[boolean]{.type-label} *(required)* + If true, all tenants in the space will be included in the report. +- **`ChannelIds`** :span[array of string]{.type-label} *(required)* + The channels for the report. +- **`Description`** :span[string]{.type-label} + The description for the report. +- **`EnvironmentGroups`** :span[array of object]{.type-label} *(required)* + The environment groups for the report. + - **`Environments`** :span[array of string]{.type-label} *(required)* + - **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Id`** :span[string]{.type-label} *(required)* + The Id of the Insights Report. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the report. Minimum length 1. Maximum length 200. +- **`ProjectGroupIds`** :span[array of string]{.type-label} *(required)* + The project groups for the report. +- **`ProjectIds`** :span[array of string]{.type-label} *(required)* + The projects for the report. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`TenantIds`** :span[array of string]{.type-label} *(required)* + The tenants for the report. +- **`TenantMode`** :span[enum]{.type-label} *(required)* + The kind of deployments that will be included in this report. + Allowed values: `Untenanted`, `TenantedAndUntenanted`, `Tenanted`. +- **`TenantTags`** :span[array of string]{.type-label} *(required)* + The tenant tags for the report. +- **`TimeZone`** :span[string]{.type-label} *(required)* + The timezone of the report. + +:::api-example{label="Request"} +```json +{ + "AllTenants": true, + "ChannelIds": [ + "string" + ], + "Description": "string", + "EnvironmentGroups": [ + { + "Environments": [ + "string" + ], + "Name": "string" + } + ], + "Id": "string", + "Name": "string", + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantMode": "Untenanted", + "TenantTags": [ + "string" + ], + "TimeZone": "string" +} +``` +::: + +**Response** + +`200` — Success + +- **`Report`** :span[object]{.type-label} + - **`AllTenants`** :span[boolean]{.type-label} + - **`ChannelIds`** :span[array of string]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`EnvironmentGroups`** :span[array of object]{.type-label} + - **`IconColor`** :span[string]{.type-label} + - **`IconId`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`ProjectGroupIds`** :span[array of string]{.type-label} + - **`ProjectIds`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`TenantIds`** :span[array of string]{.type-label} + - **`TenantMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedAndUntenanted`, `Tenanted`. + - **`TenantTags`** :span[array of string]{.type-label} + - **`TimeZone`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Report": { + "AllTenants": true, + "ChannelIds": [ + "string" + ], + "Description": "string", + "EnvironmentGroups": [ + { + "Environments": [ + "string" + ], + "Name": "string" + } + ], + "IconColor": "string", + "IconId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TenantIds": [ + "string" + ], + "TenantMode": "Untenanted", + "TenantTags": [ + "string" + ], + "TimeZone": "string" + } +} +``` +::: + +## Delete an Insights Report by ID + +:endpoint{method="DELETE" path="/api/\{spaceId\}/insights/reports/\{id\}/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports/{id}/v1`. + +Deletes an existing Insights Report. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Insights Report to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Request Insights Deployments for a Report + +:endpoint{method="GET" path="/api/\{spaceId\}/insights/reports/\{reportId\}/deployments"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports/{reportId}/deployments`, `/api/spaces/{spaceIdentifier}/insights/reports/{reportId}/deployments/csv`, `/api/{spaceId}/insights/reports/{reportId}/deployments/csv`. + +**Path Parameters** + +- **`reportId`** :span[string]{.type-label} *(required)* + ID of the Insights Report. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Insights Deployments + +- **`ReportName`** :span[string]{.type-label} + Minimum length 1. +- **`Streams`** :span[array of object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`ChannelName`** :span[string]{.type-label} + - **`Deployments`** :span[array of object]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`EnvironmentName`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + - **`TenantName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ReportName": "string", + "Streams": [ + { + "ChannelId": "string", + "ChannelName": "string", + "Deployments": [ + {} + ], + "EnvironmentId": "string", + "EnvironmentName": "string", + "ProjectId": "string", + "ProjectName": "string", + "TenantId": "string", + "TenantName": "string" + } + ] +} +``` +::: + +## GET /api/{spaceId}/insights/reports/{reportId}/logo + +:endpoint{method="GET" path="/api/\{spaceId\}/insights/reports/\{reportId\}/logo"} + +Also reachable at `/api/insights/reports/{reportId}/logo`, `/api/spaces/{spaceIdentifier}/insights/reports/{reportId}/logo`. + +**Path Parameters** + +- **`reportId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Update the logo associated with the report + +:endpoint{method="POST" path="/api/\{spaceId\}/insights/reports/\{reportId\}/logo"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports/{reportId}/logo`. + +**Path Parameters** + +- **`reportId`** :span[string]{.type-label} *(required)* + The ID of the Insights report. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +## Modify the logo of an insights report to be a specified icon + +:endpoint{method="POST" path="/api/\{spaceId\}/insights/reports/\{reportId\}/logo/icon"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports/{reportId}/logo/icon`. + +**Path Parameters** + +- **`reportId`** :span[string]{.type-label} *(required)* + The ID of the insights report to change logo for. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`IconColor`** :span[string]{.type-label} *(required)* + Color of the icon in hex format. Example: '#0D80D8'. Minimum length 1. Must match `^#[0-9a-fA-F]{6}$`. +- **`IconId`** :span[string]{.type-label} *(required)* + ID of the icon. Example: 'octopus-deploy'. Minimum length 1. +- **`ReportId`** :span[string]{.type-label} *(required)* + The ID of the insights report to change logo for. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "IconColor": "string", + "IconId": "string", + "ReportId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Insights Report Icon has been modified + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Modify the logo of an insights report to be a specified icon + +:endpoint{method="POST" path="/api/\{spaceId\}/insights/reports/\{reportId\}/logo/icon/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports/{reportId}/logo/icon/v1`. + +**Path Parameters** + +- **`reportId`** :span[string]{.type-label} *(required)* + The ID of the insights report to change logo for. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`IconColor`** :span[string]{.type-label} *(required)* + Color of the icon in hex format. Example: '#0D80D8'. Minimum length 1. Must match `^#[0-9a-fA-F]{6}$`. +- **`IconId`** :span[string]{.type-label} *(required)* + ID of the icon. Example: 'octopus-deploy'. Minimum length 1. +- **`ReportId`** :span[string]{.type-label} *(required)* + The ID of the insights report to change logo for. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "IconColor": "string", + "IconId": "string", + "ReportId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Insights Report Icon has been modified + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get Insights metrics series for the Insights Report + +:endpoint{method="GET" path="/api/\{spaceId\}/insights/reports/\{reportId\}/metrics"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports/{reportId}/metrics`. + +Returns the aggregated insights metrics for this insights report for the chosen granularity and time period grouped by the chosen split + +**Path Parameters** + +- **`reportId`** :span[string]{.type-label} *(required)* + ID of the Insights Report. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`granularity`** :span[enum]{.type-label} + The data grouping granularity, defaults to weekly if not supplied. + Allowed values: `Monthly`, `Weekly`, `Daily`. +- **`split`** :span[enum]{.type-label} *(required)* + How to split the metrics. + Allowed values: `None`, `Project`, `ProjectGroup`, `Environment`, `EnvironmentGroup`, `Tenant`, `TenantTagSet`. +- **`tenantTagSetId`** :span[string]{.type-label} + If TenantTagSet is chosen for Split, this is required, otherwise it is ignored. It is the tag set to split on. +- **`timeRange`** :span[enum]{.type-label} + The time period to get data for, defaults to last quarter if not supplied. + Allowed values: `LastMonth`, `LastQuarter`, `LastYear`. + +**Response** + +`200` — Success + +- **`Series`** :span[array of object]{.type-label} + - **`Intervals`** :span[array of object]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Series": [ + { + "Intervals": [ + {} + ], + "Name": "string" + } + ] +} +``` +::: + +## Get Insights metrics series for the Insights Report + +:endpoint{method="GET" path="/api/\{spaceId\}/insights/reports/\{reportId\}/metrics/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/insights/reports/{reportId}/metrics/v1`. + +Returns the aggregated insights metrics for this insights report for the chosen granularity and time period grouped by the chosen split + +**Path Parameters** + +- **`reportId`** :span[string]{.type-label} *(required)* + ID of the Insights Report. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`granularity`** :span[enum]{.type-label} + The data grouping granularity, defaults to weekly if not supplied. + Allowed values: `Monthly`, `Weekly`, `Daily`. +- **`split`** :span[enum]{.type-label} *(required)* + How to split the metrics. + Allowed values: `None`, `Project`, `ProjectGroup`, `Environment`, `EnvironmentGroup`, `Tenant`, `TenantTagSet`. +- **`tenantTagSetId`** :span[string]{.type-label} + If TenantTagSet is chosen for Split, this is required, otherwise it is ignored. It is the tag set to split on. +- **`timeRange`** :span[enum]{.type-label} + The time period to get data for, defaults to last quarter if not supplied. + Allowed values: `LastMonth`, `LastQuarter`, `LastYear`. + +**Response** + +`200` — Success + +- **`Series`** :span[array of object]{.type-label} + - **`Intervals`** :span[array of object]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Series": [ + { + "Intervals": [ + {} + ], + "Name": "string" + } + ] +} +``` +::: + +## Get Insights Deployments for a Project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/insights/deployments"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/insights/deployments`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/insights/deployments/csv`, `/api/{spaceId}/projects/{projectId}/insights/deployments/csv`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`channelId`** :span[string]{.type-label} *(required)* + ID of the Channel. +- **`environmentId`** :span[string]{.type-label} *(required)* + ID of the Environment. +- **`tenantFilter`** :span[enum]{.type-label} + How to filter for tenants, defaults to untenanted and all tenants if not supplied. + Allowed values: `UntenantedAndAllTenants`, `Untenanted`, `SingleTenant`. +- **`tenantId`** :span[string]{.type-label} + ID of the Tenant. + +**Response** + +`200` — The requested Insights Deployments + +- **`ProjectName`** :span[string]{.type-label} + Minimum length 1. +- **`Streams`** :span[array of object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`ChannelName`** :span[string]{.type-label} + - **`Deployments`** :span[array of object]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`EnvironmentName`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + - **`TenantName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ProjectName": "string", + "Streams": [ + { + "ChannelId": "string", + "ChannelName": "string", + "Deployments": [ + {} + ], + "EnvironmentId": "string", + "EnvironmentName": "string", + "ProjectId": "string", + "ProjectName": "string", + "TenantId": "string", + "TenantName": "string" + } + ] +} +``` +::: + +## Get Insights metrics series for the project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/insights/metrics"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/insights/metrics`. + +Returns the aggregated insights metrics for this project for the chosen granularity and time period + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`channelId`** :span[string]{.type-label} *(required)* + ID of the Channel. +- **`environmentId`** :span[string]{.type-label} *(required)* + ID of the Environment. +- **`granularity`** :span[enum]{.type-label} + The data grouping granularity, defaults to weekly if not supplied. + Allowed values: `Monthly`, `Weekly`, `Daily`. +- **`tenantFilter`** :span[enum]{.type-label} + How to filter for tenants, defaults to untenanted and all tenants (combined) if not supplied. + Allowed values: `UntenantedAndAllTenants`, `Untenanted`, `SingleTenant`. +- **`tenantId`** :span[string]{.type-label} + ID of the Tenant. +- **`timeRange`** :span[enum]{.type-label} + The time period to get data for, defaults to last quarter if not supplied. + Allowed values: `LastMonth`, `LastQuarter`, `LastYear`. +- **`timeZone`** :span[string]{.type-label} + The IANA timezone to use when grouping data, defaults to UTC if not supplied. + +**Response** + +`200` — Success + +- **`Series`** :span[array of object]{.type-label} + - **`Intervals`** :span[array of object]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Series": [ + { + "Intervals": [ + {} + ], + "Name": "string" + } + ] +} +``` +::: + +## Get Insights metrics series for the project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/insights/metrics/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/insights/metrics/v1`. + +Returns the aggregated insights metrics for this project for the chosen granularity and time period + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`channelId`** :span[string]{.type-label} *(required)* + ID of the Channel. +- **`environmentId`** :span[string]{.type-label} *(required)* + ID of the Environment. +- **`granularity`** :span[enum]{.type-label} + The data grouping granularity, defaults to weekly if not supplied. + Allowed values: `Monthly`, `Weekly`, `Daily`. +- **`tenantFilter`** :span[enum]{.type-label} + How to filter for tenants, defaults to untenanted and all tenants (combined) if not supplied. + Allowed values: `UntenantedAndAllTenants`, `Untenanted`, `SingleTenant`. +- **`tenantId`** :span[string]{.type-label} + ID of the Tenant. +- **`timeRange`** :span[enum]{.type-label} + The time period to get data for, defaults to last quarter if not supplied. + Allowed values: `LastMonth`, `LastQuarter`, `LastYear`. +- **`timeZone`** :span[string]{.type-label} + The IANA timezone to use when grouping data, defaults to UTC if not supplied. + +**Response** + +`200` — Success + +- **`Series`** :span[array of object]{.type-label} + - **`Intervals`** :span[array of object]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Series": [ + { + "Intervals": [ + {} + ], + "Name": "string" + } + ] +} +``` +::: diff --git a/src/pages/docs/api/integrated-authentication.md b/src/pages/docs/api/integrated-authentication.md new file mode 100644 index 0000000000..9057bb8b7f --- /dev/null +++ b/src/pages/docs/api/integrated-authentication.md @@ -0,0 +1,14 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Integrated Authentication +--- + +## GET /api/integrated-challenge + +:endpoint{method="GET" path="/api/integrated-challenge"} + +**Response** + +`200` — Success diff --git a/src/pages/docs/api/interruptions.md b/src/pages/docs/api/interruptions.md new file mode 100644 index 0000000000..a09642e56e --- /dev/null +++ b/src/pages/docs/api/interruptions.md @@ -0,0 +1,516 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Interruptions +--- + +## List interruptions for user attention. The results will be sorted by date from most recently to least recently created + +:endpoint{method="GET" path="/api/\{spaceId\}/interruptions"} + +Also reachable at `/api/interruptions`, `/api/spaces/{spaceIdentifier}/interruptions`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + List of specific interruption IDs to load. +- **`pendingOnly`** :span[boolean]{.type-label} + If true, lists only pending interruptions. +- **`regarding`** :span[string]{.type-label} + Lists interruptions related to a specific other document, specified by its ID (e.g. a ServerTasks-*, Projects-* or Environments-* ID). +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Holds a list of interruptions returned in response to ListInterruptionsRequest + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`CanTakeResponsibility`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the current user has permissions to take responsibility for this interruption. + - **`CorrelationId`** :span[string]{.type-label} + Gets or sets the correlation ID of the activity in which the interruption was requested, if any. + - **`Created`** :span[string]{.type-label} + Gets the time at which the interruption was created. Format `date-time`. + - **`Form`** :span[object]{.type-label} + - **`HasResponsibility`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the current user has responsibility for this interruption. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsLinkedToOtherInterruption`** :span[boolean]{.type-label} + If this interruption is linked to another it will be automatically completed when the other one is. Used to handle interruptions in child deployments. + - **`IsPending`** :span[boolean]{.type-label} + True if the interruption is waiting for user action; otherwise, false. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`PullRequests`** :span[array of object]{.type-label} + Gets or sets a list of pull requests associated with this interruption. This will only be populated when Type is PullRequestCompletion. + - **`RelatedDocumentIds`** :span[array of string]{.type-label} + Gets the ids of documents related to this interruption. + - **`ResponsibleTeamIds`** :span[array of string]{.type-label} + Gets the ids of groups that can take responsibility for this interruption. + - **`ResponsibleUserId`** :span[string]{.type-label} + Gets or sets the. + - **`SpaceId`** :span[string]{.type-label} + - **`TaskId`** :span[string]{.type-label} + Gets or sets the id of the Server Task raising the interruption. + - **`Title`** :span[string]{.type-label} + Gets or sets a title for this interruption. + - **`Type`** :span[enum]{.type-label} + Gets or sets the type of interruption. + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "CanTakeResponsibility": true, + "CorrelationId": "string", + "Created": "2020-01-01T00:00:00.000Z", + "Form": { + "Elements": [ + {} + ], + "Values": {} + }, + "HasResponsibility": true, + "Id": "string", + "IsLinkedToOtherInterruption": true, + "IsPending": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PullRequests": [ + {} + ], + "RelatedDocumentIds": [ + "string" + ], + "ResponsibleTeamIds": [ + "string" + ], + "ResponsibleUserId": "string", + "SpaceId": "string", + "TaskId": "string", + "Title": "string", + "Type": "ManualIntervention" + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get an Interruption by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/interruptions/\{id\}"} + +Also reachable at `/api/interruptions/{id}`, `/api/spaces/{spaceIdentifier}/interruptions/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Interruption to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space. + +**Response** + +`200` — The requested Interruption + +- **`CanTakeResponsibility`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the current user has permissions to take responsibility for this interruption. +- **`CorrelationId`** :span[string]{.type-label} + Gets or sets the correlation ID of the activity in which the interruption was requested, if any. +- **`Created`** :span[string]{.type-label} + Gets the time at which the interruption was created. Format `date-time`. +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`HasResponsibility`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the current user has responsibility for this interruption. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsLinkedToOtherInterruption`** :span[boolean]{.type-label} + If this interruption is linked to another it will be automatically completed when the other one is. Used to handle interruptions in child deployments. +- **`IsPending`** :span[boolean]{.type-label} + True if the interruption is waiting for user action; otherwise, false. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`PullRequests`** :span[array of object]{.type-label} + Gets or sets a list of pull requests associated with this interruption. This will only be populated when Type is PullRequestCompletion. + - **`Id`** :span[string]{.type-label} + - **`InterruptionId`** :span[string]{.type-label} + - **`Number`** :span[integer]{.type-label} + - **`RepositoryUrl`** :span[string]{.type-label} + - **`Status`** :span[enum]{.type-label} + Allowed values: `Unknown`, `Open`, `Merged`, `Closed`, `UnknownGitVendor`. + - **`Title`** :span[string]{.type-label} + - **`Url`** :span[string]{.type-label} +- **`RelatedDocumentIds`** :span[array of string]{.type-label} + Gets the ids of documents related to this interruption. +- **`ResponsibleTeamIds`** :span[array of string]{.type-label} + Gets the ids of groups that can take responsibility for this interruption. +- **`ResponsibleUserId`** :span[string]{.type-label} + Gets or sets the. +- **`SpaceId`** :span[string]{.type-label} +- **`TaskId`** :span[string]{.type-label} + Gets or sets the id of the Server Task raising the interruption. +- **`Title`** :span[string]{.type-label} + Gets or sets a title for this interruption. +- **`Type`** :span[enum]{.type-label} + Gets or sets the type of interruption. + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. + +:::api-example{label="Response"} +```json +{ + "CanTakeResponsibility": true, + "CorrelationId": "string", + "Created": "2020-01-01T00:00:00.000Z", + "Form": { + "Elements": [ + { + "Control": {}, + "IsValueRequired": true, + "Name": "string" + } + ], + "Values": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "HasResponsibility": true, + "Id": "string", + "IsLinkedToOtherInterruption": true, + "IsPending": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PullRequests": [ + { + "Id": "string", + "InterruptionId": "string", + "Number": 0, + "RepositoryUrl": "string", + "Status": "Unknown", + "Title": "string", + "Url": "string" + } + ], + "RelatedDocumentIds": [ + "string" + ], + "ResponsibleTeamIds": [ + "string" + ], + "ResponsibleUserId": "string", + "SpaceId": "string", + "TaskId": "string", + "Title": "string", + "Type": "ManualIntervention" +} +``` +::: + +## Get the User that is currently responsible for this Interruption (if any) + +:endpoint{method="GET" path="/api/\{spaceId\}/interruptions/\{id\}/responsible"} + +Also reachable at `/api/interruptions/{id}/responsible`, `/api/spaces/{spaceIdentifier}/interruptions/{id}/responsible`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Interruption. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space. + +**Response** + +`200` — OK + +## Allow the current user to take responsibility for this interruption. Only users in one of the responsible teams on this interruption can take responsibility for it + +:endpoint{method="PUT" path="/api/\{spaceId\}/interruptions/\{id\}/responsible"} + +Also reachable at `/api/interruptions/{id}/responsible`, `/api/spaces/{spaceIdentifier}/interruptions/{id}/responsible`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Interruption. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space. + +**Response** + +`200` — The User responsible for the requested Interruption + +- **`CanPasswordBeEdited`** :span[boolean]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DisplayName`** :span[string]{.type-label} + Maximum length 64. +- **`EmailAddress`** :span[string]{.type-label} + Format `email`. Maximum length 256. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`Identities`** :span[array of object]{.type-label} + - **`Claims`** :span[object]{.type-label} + - **`IdentityProviderName`** :span[string]{.type-label} +- **`IsActive`** :span[boolean]{.type-label} +- **`IsRequestor`** :span[boolean]{.type-label} + Gets or sets a value indicating whether this user resource represents the user who requested it. +- **`IsService`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Password`** :span[string]{.type-label} +- **`ServiceAccountType`** :span[enum]{.type-label} + Allowed values: `Standard`, `Agent`. +- **`Username`** :span[string]{.type-label} + Maximum length 64. + +:::api-example{label="Response"} +```json +{ + "CanPasswordBeEdited": true, + "Created": "2020-01-01T00:00:00.000Z", + "DisplayName": "string", + "EmailAddress": "user@example.com", + "Id": "string", + "Identities": [ + { + "Claims": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "IdentityProviderName": "string" + } + ], + "IsActive": true, + "IsRequestor": true, + "IsService": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Password": "string", + "ServiceAccountType": "Standard", + "Username": "string" +} +``` +::: + +## Submit a dictionary of form values for the interruption. Only the user with responsibility for this interruption can submit this form + +:endpoint{method="POST" path="/api/\{spaceId\}/interruptions/\{id\}/submit"} + +Also reachable at `/api/interruptions/{id}/submit`, `/api/spaces/{spaceIdentifier}/interruptions/{id}/submit`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Interruption. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space. + +**Request Body** + +- **`Guidance`** :span[string]{.type-label} + Used for Guided Failure Interruptions. Should be one of "Fail", "Retry", "Ignore" or "Exclude". +- **`Id`** :span[string]{.type-label} *(required)* + ID of the Interruption. Minimum length 1. +- **`Instructions`** :span[string]{.type-label} + Optional free-text instructions recorded with the submission. +- **`Notes`** :span[string]{.type-label} + Optional notes recorded with the submission and included in the audit log entry. +- **`Result`** :span[string]{.type-label} + Used for Manual Intervention Interruptions. Should be one of "Proceed" or "Abort". +- **`SpaceId`** :span[string]{.type-label} *(required)* + ID of the Space. + +:::api-example{label="Request"} +```json +{ + "Guidance": "string", + "Id": "string", + "Instructions": "string", + "Notes": "string", + "Result": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirms that the Interruption has been submitted successfully, containing the updated Interruption + +- **`CanTakeResponsibility`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the current user has permissions to take responsibility for this interruption. +- **`CorrelationId`** :span[string]{.type-label} + Gets or sets the correlation ID of the activity in which the interruption was requested, if any. +- **`Created`** :span[string]{.type-label} + Gets the time at which the interruption was created. Format `date-time`. +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`HasResponsibility`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the current user has responsibility for this interruption. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsLinkedToOtherInterruption`** :span[boolean]{.type-label} + If this interruption is linked to another it will be automatically completed when the other one is. Used to handle interruptions in child deployments. +- **`IsPending`** :span[boolean]{.type-label} + True if the interruption is waiting for user action; otherwise, false. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`PullRequests`** :span[array of object]{.type-label} + Gets or sets a list of pull requests associated with this interruption. This will only be populated when Type is PullRequestCompletion. + - **`Id`** :span[string]{.type-label} + - **`InterruptionId`** :span[string]{.type-label} + - **`Number`** :span[integer]{.type-label} + - **`RepositoryUrl`** :span[string]{.type-label} + - **`Status`** :span[enum]{.type-label} + Allowed values: `Unknown`, `Open`, `Merged`, `Closed`, `UnknownGitVendor`. + - **`Title`** :span[string]{.type-label} + - **`Url`** :span[string]{.type-label} +- **`RelatedDocumentIds`** :span[array of string]{.type-label} + Gets the ids of documents related to this interruption. +- **`ResponsibleTeamIds`** :span[array of string]{.type-label} + Gets the ids of groups that can take responsibility for this interruption. +- **`ResponsibleUserId`** :span[string]{.type-label} + Gets or sets the. +- **`SpaceId`** :span[string]{.type-label} +- **`TaskId`** :span[string]{.type-label} + Gets or sets the id of the Server Task raising the interruption. +- **`Title`** :span[string]{.type-label} + Gets or sets a title for this interruption. +- **`Type`** :span[enum]{.type-label} + Gets or sets the type of interruption. + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. + +:::api-example{label="Response"} +```json +{ + "CanTakeResponsibility": true, + "CorrelationId": "string", + "Created": "2020-01-01T00:00:00.000Z", + "Form": { + "Elements": [ + { + "Control": {}, + "IsValueRequired": true, + "Name": "string" + } + ], + "Values": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "HasResponsibility": true, + "Id": "string", + "IsLinkedToOtherInterruption": true, + "IsPending": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PullRequests": [ + { + "Id": "string", + "InterruptionId": "string", + "Number": 0, + "RepositoryUrl": "string", + "Status": "Unknown", + "Title": "string", + "Url": "string" + } + ], + "RelatedDocumentIds": [ + "string" + ], + "ResponsibleTeamIds": [ + "string" + ], + "ResponsibleUserId": "string", + "SpaceId": "string", + "TaskId": "string", + "Title": "string", + "Type": "ManualIntervention" +} +``` +::: diff --git a/src/pages/docs/api/invitations.md b/src/pages/docs/api/invitations.md new file mode 100644 index 0000000000..ddce123435 --- /dev/null +++ b/src/pages/docs/api/invitations.md @@ -0,0 +1,128 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Invitations +--- + +## Create an invitation to allow a new person to join this Octopus instance + +:endpoint{method="POST" path="/api/\{spaceId\}/users/invitations"} + +Also reachable at `/api/spaces/{spaceIdentifier}/users/invitations`, `/api/users/invitations`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space to create the invitation in. + +**Request Body** + +- **`AddToTeamIds`** :span[array of string]{.type-label} *(required)* + The teams the user will be invited to join. +- **`SpaceId`** :span[string]{.type-label} + The ID of the space to create the invitation in. + +:::api-example{label="Request"} +```json +{ + "AddToTeamIds": [ + "string" + ], + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`AddToTeamIds`** :span[array of string]{.type-label} +- **`Expires`** :span[string]{.type-label} + Format `date-time`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`InvitationCode`** :span[string]{.type-label} + Minimum length 1. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AddToTeamIds": [ + "string" + ], + "Expires": "2020-01-01T00:00:00.000Z", + "Id": "string", + "InvitationCode": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "SpaceId": "string" +} +``` +::: + +## Get an Invitation by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/users/invitations/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/users/invitations/{id}`, `/api/users/invitations/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Invitation to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resources. + +**Response** + +`200` — An Invitation object + +- **`AddToTeamIds`** :span[array of string]{.type-label} +- **`Expires`** :span[string]{.type-label} + Format `date-time`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`InvitationCode`** :span[string]{.type-label} + Minimum length 1. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AddToTeamIds": [ + "string" + ], + "Expires": "2020-01-01T00:00:00.000Z", + "Id": "string", + "InvitationCode": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "SpaceId": "string" +} +``` +::: diff --git a/src/pages/docs/api/jira-integration.md b/src/pages/docs/api/jira-integration.md new file mode 100644 index 0000000000..dd53bddc75 --- /dev/null +++ b/src/pages/docs/api/jira-integration.md @@ -0,0 +1,22 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Jira Integration +--- + +## POST /api/jiraintegration/connectivitycheck/connectapp + +:endpoint{method="POST" path="/api/jiraintegration/connectivitycheck/connectapp"} + +**Response** + +`200` — OK + +## POST /api/jiraintegration/connectivitycheck/jira + +:endpoint{method="POST" path="/api/jiraintegration/connectivitycheck/jira"} + +**Response** + +`200` — OK diff --git a/src/pages/docs/api/json-web-keys.md b/src/pages/docs/api/json-web-keys.md new file mode 100644 index 0000000000..020b2cdff3 --- /dev/null +++ b/src/pages/docs/api/json-web-keys.md @@ -0,0 +1,42 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Json Web Keys +--- + +## Get signing keys used by Octopus Server in JWK format + +:endpoint{method="GET" path="/api/.well-known/jwks"} + +**Response** + +`200` — Rseponse to getting set of JsonWebKeys + +- **`keys`** :span[array of object]{.type-label} + - **`e`** :span[string]{.type-label} + Minimum length 1. + - **`kid`** :span[string]{.type-label} + Minimum length 1. + - **`kty`** :span[string]{.type-label} + Minimum length 1. + - **`n`** :span[string]{.type-label} + Minimum length 1. + - **`use`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "keys": [ + { + "e": "string", + "kid": "string", + "kty": "string", + "n": "string", + "use": "string" + } + ] +} +``` +::: diff --git a/src/pages/docs/api/lets-encrypt.md b/src/pages/docs/api/lets-encrypt.md new file mode 100644 index 0000000000..e43d5fa98a --- /dev/null +++ b/src/pages/docs/api/lets-encrypt.md @@ -0,0 +1,120 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Lets Encrypt +--- + +## Request the current Let's Encrypt configuration + +:endpoint{method="GET" path="/api/letsencryptconfiguration"} + +**Response** + +`200` — The current Let's Encrypt configuration for this Octopus Server + +- **`AcceptLetsEncryptTermsOfService`** :span[boolean]{.type-label} +- **`CertificateExpiryDate`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateThumbprint`** :span[string]{.type-label} +- **`DnsName`** :span[string]{.type-label} +- **`Enabled`** :span[boolean]{.type-label} +- **`HttpsPort`** :span[integer]{.type-label} +- **`IPAddress`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Path`** :span[string]{.type-label} +- **`RegistrationEmailAddress`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AcceptLetsEncryptTermsOfService": true, + "CertificateExpiryDate": "2020-01-01T00:00:00.000Z", + "CertificateThumbprint": "string", + "DnsName": "string", + "Enabled": true, + "HttpsPort": 0, + "IPAddress": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Path": "string", + "RegistrationEmailAddress": "string" +} +``` +::: + +## Allow you to disable the Let's Encrypt configuration for this Octopus Server + +:endpoint{method="PUT" path="/api/letsencryptconfiguration"} + +**Request Body** + +- **`Enabled`** :span[boolean]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Enabled": true +} +``` +::: + +**Response** + +`200` — The updated configuration + +- **`AcceptLetsEncryptTermsOfService`** :span[boolean]{.type-label} +- **`CertificateExpiryDate`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateThumbprint`** :span[string]{.type-label} +- **`DnsName`** :span[string]{.type-label} +- **`Enabled`** :span[boolean]{.type-label} +- **`HttpsPort`** :span[integer]{.type-label} +- **`IPAddress`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Path`** :span[string]{.type-label} +- **`RegistrationEmailAddress`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AcceptLetsEncryptTermsOfService": true, + "CertificateExpiryDate": "2020-01-01T00:00:00.000Z", + "CertificateThumbprint": "string", + "DnsName": "string", + "Enabled": true, + "HttpsPort": 0, + "IPAddress": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Path": "string", + "RegistrationEmailAddress": "string" +} +``` +::: diff --git a/src/pages/docs/api/library-variable-sets.md b/src/pages/docs/api/library-variable-sets.md new file mode 100644 index 0000000000..8be37e4eb2 --- /dev/null +++ b/src/pages/docs/api/library-variable-sets.md @@ -0,0 +1,836 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Library Variable Sets +--- + +## List all of the library variable sets in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name + +:endpoint{method="GET" path="/api/\{spaceId\}/libraryvariablesets"} + +Also reachable at `/api/libraryvariablesets`, `/api/spaces/{spaceIdentifier}/libraryvariablesets`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`contentType`** :span[string]{.type-label} + Filters by the purpose of the set: 'Variables' for ordinary variable sets or 'ScriptModule' for script modules. Omit to return both. +- **`ids`** :span[array of string]{.type-label} +- **`name`** :span[string]{.type-label} + The exact name of a Library Variable Set to be matched. +- **`partialName`** :span[string]{.type-label} +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — All of the library variable sets in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`ContentType`** :span[enum]{.type-label} + Describes the purpose of the variable set. Clients can use this to offer an editing experience appropriately. + Allowed values: `Variables`, `ScriptModule`. + - **`Description`** :span[string]{.type-label} + Gets or sets a description of this variable set that explains the purpose of the variable set to other users. This field may contain markdown. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this variable set. This should be short, preferably 5-20 characters. + - **`SpaceId`** :span[string]{.type-label} + - **`Templates`** :span[array of object]{.type-label} + Gets the variable templates. + - **`VariableSetId`** :span[string]{.type-label} + Gets or sets the id of the associated variable set. + - **`Version`** :span[integer]{.type-label} + Gets or sets the version number. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "ContentType": "Variables", + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpaceId": "string", + "Templates": [ + {} + ], + "VariableSetId": "string", + "Version": 0 + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new library variable set + +:endpoint{method="POST" path="/api/\{spaceId\}/libraryvariablesets"} + +Also reachable at `/api/libraryvariablesets`, `/api/spaces/{spaceIdentifier}/libraryvariablesets`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ContentType`** :span[enum]{.type-label} + Describes the purpose of the variable set. Clients can use this to offer an editing experience appropriately. + Allowed values: `Variables`, `ScriptModule`. +- **`Description`** :span[string]{.type-label} + A description of this variable set that explains the purpose of the variable set to other users. This field may contain markdown. +- **`Name`** :span[string]{.type-label} *(required)* + The name of this variable set. This should be short, preferably 5-20 characters. Minimum length 1. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`Templates`** :span[array of object]{.type-label} + Variable templates for tenant-specific values: each template defines a variable (name, label, help text, control type and default value) that every tenant connected to a linked project must supply a value for. Leave empty unless working with tenants. + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "ContentType": "Variables", + "Description": "string", + "Name": "string", + "SpaceId": "string", + "Templates": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ] +} +``` +::: + +**Response** + +`201` — Created + +- **`ContentType`** :span[enum]{.type-label} + Describes the purpose of the variable set. Clients can use this to offer an editing experience appropriately. + Allowed values: `Variables`, `ScriptModule`. +- **`Description`** :span[string]{.type-label} + Gets or sets a description of this variable set that explains the purpose of the variable set to other users. This field may contain markdown. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this variable set. This should be short, preferably 5-20 characters. +- **`SpaceId`** :span[string]{.type-label} +- **`Templates`** :span[array of object]{.type-label} + Gets the variable templates. + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`VariableSetId`** :span[string]{.type-label} + Gets or sets the id of the associated variable set. +- **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +{ + "ContentType": "Variables", + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpaceId": "string", + "Templates": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "VariableSetId": "string", + "Version": 0 +} +``` +::: + +## Get a list of Library Variable Sets + +:endpoint{method="GET" path="/api/\{spaceId\}/libraryvariablesets/all"} + +Also reachable at `/api/libraryvariablesets/all`, `/api/spaces/{spaceIdentifier}/libraryvariablesets/all`. + +Lists all the Library Variable Sets in the supplied Space. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`contentType`** :span[string]{.type-label} + A content type use to filter Library Variable Sets. +- **`ids`** :span[array of string]{.type-label} + A list of Library Variable Set ids used to filter. + +**Response** + +`200` — Requested list of Library Variable Sets + +- **`ContentType`** :span[enum]{.type-label} + Describes the purpose of the variable set. Clients can use this to offer an editing experience appropriately. + Allowed values: `Variables`, `ScriptModule`. +- **`Description`** :span[string]{.type-label} + Gets or sets a description of this variable set that explains the purpose of the variable set to other users. This field may contain markdown. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this variable set. This should be short, preferably 5-20 characters. +- **`SpaceId`** :span[string]{.type-label} +- **`Templates`** :span[array of object]{.type-label} + Gets the variable templates. + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`VariableSetId`** :span[string]{.type-label} + Gets or sets the id of the associated variable set. +- **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +[ + { + "ContentType": "Variables", + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpaceId": "string", + "Templates": [ + { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "VariableSetId": "string", + "Version": 0 + } +] +``` +::: + +## Get a list of Library Variable Sets + +:endpoint{method="GET" path="/api/\{spaceId\}/libraryvariablesets/all/v1"} + +Also reachable at `/api/libraryvariablesets/all/v1`, `/api/spaces/{spaceIdentifier}/libraryvariablesets/all/v1`. + +Lists all the Library Variable Sets in the supplied Space. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`contentType`** :span[string]{.type-label} + A content type use to filter Library Variable Sets. +- **`ids`** :span[array of string]{.type-label} + A list of Library Variable Set ids used to filter. + +**Response** + +`200` — Requested list of Library Variable Sets + +- **`LibraryVariableSets`** :span[array of object]{.type-label} + - **`ContentType`** :span[enum]{.type-label} + Describes the purpose of the variable set. Clients can use this to offer an editing experience appropriately. + Allowed values: `Variables`, `ScriptModule`. + - **`Description`** :span[string]{.type-label} + Gets or sets a description of this variable set that explains the purpose of the variable set to other users. This field may contain markdown. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this variable set. This should be short, preferably 5-20 characters. + - **`SpaceId`** :span[string]{.type-label} + - **`Templates`** :span[array of object]{.type-label} + Gets the variable templates. + - **`VariableSetId`** :span[string]{.type-label} + Gets or sets the id of the associated variable set. + - **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +{ + "LibraryVariableSets": [ + { + "ContentType": "Variables", + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpaceId": "string", + "Templates": [ + {} + ], + "VariableSetId": "string", + "Version": 0 + } + ] +} +``` +::: + +## Get a list of Library Variable Sets + +:endpoint{method="POST" path="/api/\{spaceId\}/libraryvariablesets/all/v1"} + +Lists all the Library Variable Sets in the supplied Space. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`contentType`** :span[string]{.type-label} + A content type use to filter Library Variable Sets. +- **`ids`** :span[array of string]{.type-label} + A list of Library Variable Set ids used to filter. + +**Response** + +`200` — Requested list of Library Variable Sets + +- **`LibraryVariableSets`** :span[array of object]{.type-label} + - **`ContentType`** :span[enum]{.type-label} + Describes the purpose of the variable set. Clients can use this to offer an editing experience appropriately. + Allowed values: `Variables`, `ScriptModule`. + - **`Description`** :span[string]{.type-label} + Gets or sets a description of this variable set that explains the purpose of the variable set to other users. This field may contain markdown. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this variable set. This should be short, preferably 5-20 characters. + - **`SpaceId`** :span[string]{.type-label} + - **`Templates`** :span[array of object]{.type-label} + Gets the variable templates. + - **`VariableSetId`** :span[string]{.type-label} + Gets or sets the id of the associated variable set. + - **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +{ + "LibraryVariableSets": [ + { + "ContentType": "Variables", + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpaceId": "string", + "Templates": [ + {} + ], + "VariableSetId": "string", + "Version": 0 + } + ] +} +``` +::: + +## Get a list of Library Variable Sets + +:endpoint{method="POST" path="/api/spaces/\{spaceIdentifier\}/libraryvariablesets/all/v1"} + +Also reachable at `/api/libraryvariablesets/all/v1`. + +Lists all the Library Variable Sets in the supplied Space. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceIdentifier`** :span[string]{.type-label} *(required)* + Identifier (ID or slug) of the space. + +**Query Parameters** + +- **`contentType`** :span[string]{.type-label} + A content type use to filter Library Variable Sets. +- **`ids`** :span[array of string]{.type-label} + A list of Library Variable Set ids used to filter. + +**Response** + +`200` — Requested list of Library Variable Sets + +- **`LibraryVariableSets`** :span[array of object]{.type-label} + - **`ContentType`** :span[enum]{.type-label} + Describes the purpose of the variable set. Clients can use this to offer an editing experience appropriately. + Allowed values: `Variables`, `ScriptModule`. + - **`Description`** :span[string]{.type-label} + Gets or sets a description of this variable set that explains the purpose of the variable set to other users. This field may contain markdown. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this variable set. This should be short, preferably 5-20 characters. + - **`SpaceId`** :span[string]{.type-label} + - **`Templates`** :span[array of object]{.type-label} + Gets the variable templates. + - **`VariableSetId`** :span[string]{.type-label} + Gets or sets the id of the associated variable set. + - **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +{ + "LibraryVariableSets": [ + { + "ContentType": "Variables", + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpaceId": "string", + "Templates": [ + {} + ], + "VariableSetId": "string", + "Version": 0 + } + ] +} +``` +::: + +## Get a Library Variable Set by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/libraryvariablesets/\{id\}"} + +Also reachable at `/api/libraryvariablesets/{id}`, `/api/spaces/{spaceIdentifier}/libraryvariablesets/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Library Variable Set to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The Library Variable Set with matching ID. + +- **`ContentType`** :span[enum]{.type-label} + Describes the purpose of the variable set. Clients can use this to offer an editing experience appropriately. + Allowed values: `Variables`, `ScriptModule`. +- **`Description`** :span[string]{.type-label} + Gets or sets a description of this variable set that explains the purpose of the variable set to other users. This field may contain markdown. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this variable set. This should be short, preferably 5-20 characters. +- **`SpaceId`** :span[string]{.type-label} +- **`Templates`** :span[array of object]{.type-label} + Gets the variable templates. + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`VariableSetId`** :span[string]{.type-label} + Gets or sets the id of the associated variable set. +- **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +{ + "ContentType": "Variables", + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpaceId": "string", + "Templates": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "VariableSetId": "string", + "Version": 0 +} +``` +::: + +## Modify an existing library variable set + +:endpoint{method="PUT" path="/api/\{spaceId\}/libraryvariablesets/\{id\}"} + +Also reachable at `/api/libraryvariablesets/{id}`, `/api/spaces/{spaceIdentifier}/libraryvariablesets/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the library variable set. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* + The ID of the library variable set. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`Templates`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Id": "string", + "Name": "string", + "SpaceId": "string", + "Templates": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "Version": 0 +} +``` +::: + +**Response** + +`200` — The modified library variable set. + +- **`ContentType`** :span[enum]{.type-label} + Describes the purpose of the variable set. Clients can use this to offer an editing experience appropriately. + Allowed values: `Variables`, `ScriptModule`. +- **`Description`** :span[string]{.type-label} + Gets or sets a description of this variable set that explains the purpose of the variable set to other users. This field may contain markdown. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this variable set. This should be short, preferably 5-20 characters. +- **`SpaceId`** :span[string]{.type-label} +- **`Templates`** :span[array of object]{.type-label} + Gets the variable templates. + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`VariableSetId`** :span[string]{.type-label} + Gets or sets the id of the associated variable set. +- **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +{ + "ContentType": "Variables", + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpaceId": "string", + "Templates": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "VariableSetId": "string", + "Version": 0 +} +``` +::: + +## Delete an existing Library Variable Set + +:endpoint{method="DELETE" path="/api/\{spaceId\}/libraryvariablesets/\{id\}"} + +Also reachable at `/api/libraryvariablesets/{id}`, `/api/spaces/{spaceIdentifier}/libraryvariablesets/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Library Variable Set to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +## List projects and deployments which are using an library variable set + +:endpoint{method="GET" path="/api/\{spaceId\}/libraryvariablesets/\{id\}/usages"} + +Also reachable at `/api/libraryvariablesets/{id}/usages`, `/api/spaces/{spaceIdentifier}/libraryvariablesets/{id}/usages`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the Library Variable Set. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space. + +**Response** + +`200` — The usages of the library variable set. + +- **`CountOfProjectsUserCannotSee`** :span[integer]{.type-label} +- **`CountOfReleasesUserCannotSee`** :span[integer]{.type-label} +- **`CountOfRunbookSnapshotsUserCannotSee`** :span[integer]{.type-label} +- **`Projects`** :span[array of object]{.type-label} + - **`IsCurrentlyBeingUsedInProject`** :span[boolean]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`ProjectSlug`** :span[string]{.type-label} + - **`Releases`** :span[array of object]{.type-label} + - **`RunbookSnapshots`** :span[array of object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CountOfProjectsUserCannotSee": 0, + "CountOfReleasesUserCannotSee": 0, + "CountOfRunbookSnapshotsUserCannotSee": 0, + "Projects": [ + { + "IsCurrentlyBeingUsedInProject": true, + "ProjectId": "string", + "ProjectName": "string", + "ProjectSlug": "string", + "Releases": [ + {} + ], + "RunbookSnapshots": [ + {} + ] + } + ] +} +``` +::: diff --git a/src/pages/docs/api/licenses.md b/src/pages/docs/api/licenses.md new file mode 100644 index 0000000000..f92db4e1a8 --- /dev/null +++ b/src/pages/docs/api/licenses.md @@ -0,0 +1,307 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Licenses +--- + +## Return the details of the current license in use by the Octopus Cluster + +:endpoint{method="GET" path="/api/licenses/licenses-current"} + +**Response** + +`200` — The requested License + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LicenseText`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`SerialNumber`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LicenseText": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "SerialNumber": "string" +} +``` +::: + +## Update the current Octopus cluster license + +:endpoint{method="PUT" path="/api/licenses/licenses-current"} + +Updates the license for the Octopus cluster. + +**Request Body** + +- **`LicenseText`** :span[string]{.type-label} +- **`SerialNumber`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "LicenseText": "string", + "SerialNumber": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Current License has been modified, containing the new License + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LicenseText`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`SerialNumber`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LicenseText": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "SerialNumber": "string" +} +``` +::: + +## Return a list of enabled features from the license + +:endpoint{method="GET" path="/api/licenses/licenses-current-features"} + +**Response** + +`200` — The list of enabled features from the license + +- **`EnabledFeatures`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "EnabledFeatures": [ + "string" + ] +} +``` +::: + +## Get the status of the current Octopus license + +:endpoint{method="GET" path="/api/licenses/licenses-current-status"} + +Calculates the status of the current Octopus license including compliance and maintenance expiry. + +**Response** + +`200` — The requested License Status + +- **`ComplianceSummary`** :span[string]{.type-label} +- **`DaysToEffectiveExpiryDate`** :span[integer]{.type-label} +- **`DoesExpiryBlockKeyActivities`** :span[boolean]{.type-label} +- **`EffectiveClusterTaskLimit`** :span[integer]{.type-label} +- **`EffectiveExpiryDate`** :span[string]{.type-label} +- **`EffectiveNodeTaskLimit`** :span[integer]{.type-label} +- **`EffectiveStartDate`** :span[string]{.type-label} +- **`HostingEnvironment`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsClusterTaskLimitControlledByLicense`** :span[boolean]{.type-label} +- **`IsCompliant`** :span[boolean]{.type-label} +- **`IsInitialisationLicense`** :span[boolean]{.type-label} +- **`IsNodeTaskLimitControlledByLicense`** :span[boolean]{.type-label} +- **`IsPtm`** :span[boolean]{.type-label} +- **`IsTrial`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Limits`** :span[array of object]{.type-label} + - **`CurrentUsage`** :span[integer]{.type-label} + - **`Disposition`** :span[enum]{.type-label} + Allowed values: `Information`, `Notice`, `Warning`, `Error`. + - **`EffectiveLimit`** :span[integer]{.type-label} + - **`EffectiveLimitDescription`** :span[string]{.type-label} + - **`IsUnlimited`** :span[boolean]{.type-label} + - **`LicenseLimitDescription`** :span[string]{.type-label} + - **`LicensedLimit`** :span[integer]{.type-label} + - **`LimitStatus`** :span[enum]{.type-label} + Allowed values: `UnderLimit`, `AlmostAtLimit`, `AtLimit`, `InOverrun`, `ExceedingLimit`. + - **`Message`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`TargetTypes`** :span[array of string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Messages`** :span[array of object]{.type-label} + - **`Disposition`** :span[enum]{.type-label} + Allowed values: `Information`, `Notice`, `Warning`, `Error`. + - **`Message`** :span[string]{.type-label} + - **`MessagePolicy`** :span[enum]{.type-label} + Allowed values: `LicensePeriodPolicy`, `AuditStreamPolicy`, `InsightsLicensePolicy`, `TimeLimitedPolicy`, `MaintenancePeriodPolicy`, `TimeLimitedTestLicensePolicy`, `CommunityEditionPolicy`, `NodeLimitPolicy`. +- **`PermissionsMode`** :span[enum]{.type-label} + Allowed values: `Unspecified`, `Restricted`, `Full`. +- **`SerialNumber`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ComplianceSummary": "string", + "DaysToEffectiveExpiryDate": 0, + "DoesExpiryBlockKeyActivities": true, + "EffectiveClusterTaskLimit": 0, + "EffectiveExpiryDate": "string", + "EffectiveNodeTaskLimit": 0, + "EffectiveStartDate": "string", + "HostingEnvironment": "string", + "Id": "string", + "IsClusterTaskLimitControlledByLicense": true, + "IsCompliant": true, + "IsInitialisationLicense": true, + "IsNodeTaskLimitControlledByLicense": true, + "IsPtm": true, + "IsTrial": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Limits": [ + { + "CurrentUsage": 0, + "Disposition": "Information", + "EffectiveLimit": 0, + "EffectiveLimitDescription": "string", + "IsUnlimited": true, + "LicenseLimitDescription": "string", + "LicensedLimit": 0, + "LimitStatus": "UnderLimit", + "Message": "string", + "Name": "string", + "TargetTypes": [ + "string" + ] + } + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Messages": [ + { + "Disposition": "Information", + "Message": "string", + "MessagePolicy": "LicensePeriodPolicy" + } + ], + "PermissionsMode": "Unspecified", + "SerialNumber": "string" +} +``` +::: + +## Get the usage of the current Octopus server + +:endpoint{method="GET" path="/api/licenses/licenses-current-usage"} + +Calculates the usage of the current Octopus server. + +**Response** + +`200` — Success + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsPtm`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Limits`** :span[array of object]{.type-label} + - **`CurrentUsage`** :span[integer]{.type-label} + - **`Disposition`** :span[enum]{.type-label} + Allowed values: `Information`, `Notice`, `Warning`, `Error`. + - **`EffectiveLimit`** :span[integer]{.type-label} + - **`EffectiveLimitDescription`** :span[string]{.type-label} + - **`IsUnlimited`** :span[boolean]{.type-label} + - **`LicenseLimitDescription`** :span[string]{.type-label} + - **`LicensedLimit`** :span[integer]{.type-label} + - **`LimitStatus`** :span[enum]{.type-label} + Allowed values: `UnderLimit`, `AlmostAtLimit`, `AtLimit`, `InOverrun`, `ExceedingLimit`. + - **`LimitUsageDescription`** :span[string]{.type-label} + - **`Message`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`TargetTypes`** :span[array of string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`SpacesUsage`** :span[array of object]{.type-label} + - **`MachinesCount`** :span[integer]{.type-label} + - **`ProjectsCount`** :span[integer]{.type-label} + - **`SpaceName`** :span[string]{.type-label} + - **`TenantsCount`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "IsPtm": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Limits": [ + { + "CurrentUsage": 0, + "Disposition": "Information", + "EffectiveLimit": 0, + "EffectiveLimitDescription": "string", + "IsUnlimited": true, + "LicenseLimitDescription": "string", + "LicensedLimit": 0, + "LimitStatus": "UnderLimit", + "LimitUsageDescription": "string", + "Message": "string", + "Name": "string", + "TargetTypes": [ + "string" + ] + } + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "SpacesUsage": [ + { + "MachinesCount": 0, + "ProjectsCount": 0, + "SpaceName": "string", + "TenantsCount": 0 + } + ] +} +``` +::: diff --git a/src/pages/docs/api/lifecycles.md b/src/pages/docs/api/lifecycles.md new file mode 100644 index 0000000000..cc04ee342b --- /dev/null +++ b/src/pages/docs/api/lifecycles.md @@ -0,0 +1,1152 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Lifecycles +--- + +## List the Lifecycles in the supplied Octopus Deploy Space in pages. The results will be sorted alphabetically by name + +:endpoint{method="GET" path="/api/\{spaceId\}/lifecycles"} + +Also reachable at `/api/lifecycles`, `/api/spaces/{spaceIdentifier}/lifecycles`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} +- **`name`** :span[string]{.type-label} + The exact name of a Lifecycle to be matched. +- **`partialName`** :span[string]{.type-label} +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — A paginated list of lifecycles + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`Phases`** :span[array of object]{.type-label} + - **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`TentacleRetentionPolicy`** :span[object]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Phases": [ + {} + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "Slug": "string", + "SpaceId": "string", + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new Lifecycle + +:endpoint{method="POST" path="/api/\{spaceId\}/lifecycles"} + +Also reachable at `/api/lifecycles`, `/api/spaces/{spaceIdentifier}/lifecycles`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the Space for the Lifecycle. + +**Request Body** + +- **`Description`** :span[string]{.type-label} + A description of the Lifecycle. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the Lifecycle. Minimum length 1. +- **`Phases`** :span[array of object]{.type-label} + The promotion phases in order. Each phase lists environments deployed to automatically (AutomaticDeploymentTargets) or manually (OptionalDeploymentTargets); an environment may appear in only one phase, and at most one phase may list no environments, meaning all remaining environments. MinimumEnvironmentsBeforePromotion is how many of the phase's environments must be deployed before a release can progress (0 means all). IsOptionalPhase allows skipping the phase, but not every phase may be optional. Per-phase retention policies override the lifecycle-level ones. Leave each phase's Id blank; the server assigns it. + - **`AutomaticDeploymentTargets`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsOptionalPhase`** :span[boolean]{.type-label} + - **`IsPriorityPhase`** :span[boolean]{.type-label} + - **`MinimumEnvironmentsBeforePromotion`** :span[integer]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OptionalDeploymentTargets`** :span[array of string]{.type-label} + - **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`TentacleRetentionPolicy`** :span[object]{.type-label} +- **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`Slug`** :span[string]{.type-label} + A slug for the Lifecycle. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The id of the Space for the Lifecycle. +- **`TentacleRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Name": "string", + "Phases": [ + { + "AutomaticDeploymentTargets": [ + "string" + ], + "Id": "string", + "IsOptionalPhase": true, + "IsPriorityPhase": true, + "MinimumEnvironmentsBeforePromotion": 0, + "Name": "string", + "OptionalDeploymentTargets": [ + "string" + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } + } + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "Slug": "string", + "SpaceId": "string", + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } +} +``` +::: + +**Response** + +`201` — Created + +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Phases`** :span[array of object]{.type-label} + - **`AutomaticDeploymentTargets`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsOptionalPhase`** :span[boolean]{.type-label} + - **`IsPriorityPhase`** :span[boolean]{.type-label} + - **`MinimumEnvironmentsBeforePromotion`** :span[integer]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OptionalDeploymentTargets`** :span[array of string]{.type-label} + - **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`TentacleRetentionPolicy`** :span[object]{.type-label} +- **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TentacleRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Phases": [ + { + "AutomaticDeploymentTargets": [ + "string" + ], + "Id": "string", + "IsOptionalPhase": true, + "IsPriorityPhase": true, + "MinimumEnvironmentsBeforePromotion": 0, + "Name": "string", + "OptionalDeploymentTargets": [ + "string" + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } + } + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "Slug": "string", + "SpaceId": "string", + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } +} +``` +::: + +## List all the lifecycles in the supplied Octopus Deploy Space + +:endpoint{method="GET" path="/api/\{spaceId\}/lifecycles/all"} + +Also reachable at `/api/lifecycles/all`, `/api/spaces/{spaceIdentifier}/lifecycles/all`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — All of the lifecycles in the supplied Octopus Deploy Space. + +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Phases`** :span[array of object]{.type-label} + - **`AutomaticDeploymentTargets`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsOptionalPhase`** :span[boolean]{.type-label} + - **`IsPriorityPhase`** :span[boolean]{.type-label} + - **`MinimumEnvironmentsBeforePromotion`** :span[integer]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OptionalDeploymentTargets`** :span[array of string]{.type-label} + - **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`TentacleRetentionPolicy`** :span[object]{.type-label} +- **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TentacleRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. + +:::api-example{label="Response"} +```json +[ + { + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Phases": [ + { + "AutomaticDeploymentTargets": [ + "string" + ], + "Id": "string", + "IsOptionalPhase": true, + "IsPriorityPhase": true, + "MinimumEnvironmentsBeforePromotion": 0, + "Name": "string", + "OptionalDeploymentTargets": [ + "string" + ], + "ReleaseRetentionPolicy": {}, + "TentacleRetentionPolicy": {} + } + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "Slug": "string", + "SpaceId": "string", + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } + } +] +``` +::: + +## Get a list of Lifecycle previews + +:endpoint{method="GET" path="/api/\{spaceId\}/lifecycles/previews"} + +Also reachable at `/api/lifecycles/previews`, `/api/spaces/{spaceIdentifier}/lifecycles/previews`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The Space ID of the Lifecycles. + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} *(required)* + The IDs of the Lifecycles to retrieve. + +**Response** + +`200` — Get a list of Lifecycle previews + +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Phases`** :span[array of object]{.type-label} + - **`AutomaticDeploymentTargets`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsOptionalPhase`** :span[boolean]{.type-label} + - **`IsPriorityPhase`** :span[boolean]{.type-label} + - **`MinimumEnvironmentsBeforePromotion`** :span[integer]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OptionalDeploymentTargets`** :span[array of string]{.type-label} + - **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`TentacleRetentionPolicy`** :span[object]{.type-label} +- **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TentacleRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. + +:::api-example{label="Response"} +```json +[ + { + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Phases": [ + { + "AutomaticDeploymentTargets": [ + "string" + ], + "Id": "string", + "IsOptionalPhase": true, + "IsPriorityPhase": true, + "MinimumEnvironmentsBeforePromotion": 0, + "Name": "string", + "OptionalDeploymentTargets": [ + "string" + ], + "ReleaseRetentionPolicy": {}, + "TentacleRetentionPolicy": {} + } + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "Slug": "string", + "SpaceId": "string", + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } + } +] +``` +::: + +## Get a specific Lifecycle + +:endpoint{method="GET" path="/api/\{spaceId\}/lifecycles/\{id\}"} + +Also reachable at `/api/lifecycles/{id}`, `/api/spaces/{spaceIdentifier}/lifecycles/{id}`. + +This request does not support getting Lifecycles that belong to Templated Projects + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested Lifecycle + +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Phases`** :span[array of object]{.type-label} + - **`AutomaticDeploymentTargets`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsOptionalPhase`** :span[boolean]{.type-label} + - **`IsPriorityPhase`** :span[boolean]{.type-label} + - **`MinimumEnvironmentsBeforePromotion`** :span[integer]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OptionalDeploymentTargets`** :span[array of string]{.type-label} + - **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`TentacleRetentionPolicy`** :span[object]{.type-label} +- **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TentacleRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Phases": [ + { + "AutomaticDeploymentTargets": [ + "string" + ], + "Id": "string", + "IsOptionalPhase": true, + "IsPriorityPhase": true, + "MinimumEnvironmentsBeforePromotion": 0, + "Name": "string", + "OptionalDeploymentTargets": [ + "string" + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } + } + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "Slug": "string", + "SpaceId": "string", + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } +} +``` +::: + +## Modify a Lifecycle + +:endpoint{method="PUT" path="/api/\{spaceId\}/lifecycles/\{id\}"} + +Also reachable at `/api/lifecycles/{id}`, `/api/spaces/{spaceIdentifier}/lifecycles/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The Id of the Lifecycle to modify. +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the Space for the Lifecycle. + +**Request Body** + +- **`Description`** :span[string]{.type-label} + A description of the Lifecycle. +- **`Id`** :span[string]{.type-label} *(required)* + The Id of the Lifecycle to modify. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the Lifecycle. Minimum length 1. +- **`Phases`** :span[array of object]{.type-label} + The complete list of promotion phases in order; existing phases not resubmitted are deleted. Each phase lists environments deployed to automatically (AutomaticDeploymentTargets) or manually (OptionalDeploymentTargets); an environment may appear in only one phase, and at most one phase may list no environments, meaning all remaining environments. MinimumEnvironmentsBeforePromotion is how many of the phase's environments must be deployed before a release can progress (0 means all). IsOptionalPhase allows skipping the phase, but not every phase may be optional. Per-phase retention policies override the lifecycle-level ones. + - **`AutomaticDeploymentTargets`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsOptionalPhase`** :span[boolean]{.type-label} + - **`IsPriorityPhase`** :span[boolean]{.type-label} + - **`MinimumEnvironmentsBeforePromotion`** :span[integer]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OptionalDeploymentTargets`** :span[array of string]{.type-label} + - **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`TentacleRetentionPolicy`** :span[object]{.type-label} +- **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`Slug`** :span[string]{.type-label} + The slug of the Lifecycle. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The id of the Space for the Lifecycle. +- **`TentacleRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Id": "string", + "Name": "string", + "Phases": [ + { + "AutomaticDeploymentTargets": [ + "string" + ], + "Id": "string", + "IsOptionalPhase": true, + "IsPriorityPhase": true, + "MinimumEnvironmentsBeforePromotion": 0, + "Name": "string", + "OptionalDeploymentTargets": [ + "string" + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } + } + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "Slug": "string", + "SpaceId": "string", + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } +} +``` +::: + +**Response** + +`200` — Contains a Lifecycle resource which represents changes to the Lifecycle. + +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Phases`** :span[array of object]{.type-label} + - **`AutomaticDeploymentTargets`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsOptionalPhase`** :span[boolean]{.type-label} + - **`IsPriorityPhase`** :span[boolean]{.type-label} + - **`MinimumEnvironmentsBeforePromotion`** :span[integer]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OptionalDeploymentTargets`** :span[array of string]{.type-label} + - **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`TentacleRetentionPolicy`** :span[object]{.type-label} +- **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TentacleRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Phases": [ + { + "AutomaticDeploymentTargets": [ + "string" + ], + "Id": "string", + "IsOptionalPhase": true, + "IsPriorityPhase": true, + "MinimumEnvironmentsBeforePromotion": 0, + "Name": "string", + "OptionalDeploymentTargets": [ + "string" + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } + } + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "Slug": "string", + "SpaceId": "string", + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } +} +``` +::: + +## Delete an existing Lifecycle + +:endpoint{method="DELETE" path="/api/\{spaceId\}/lifecycles/\{id\}"} + +Also reachable at `/api/lifecycles/{id}`, `/api/spaces/{spaceIdentifier}/lifecycles/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the lifecycle to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get a Lifecycle preview by Lifecycle id + +:endpoint{method="GET" path="/api/\{spaceId\}/lifecycles/\{id\}/preview"} + +Also reachable at `/api/lifecycles/{id}/preview`, `/api/spaces/{spaceIdentifier}/lifecycles/{id}/preview`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the Lifecycle. +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the space for the Lifecycle. + +**Response** + +`200` — Returns a Lifecycle preview + +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Phases`** :span[array of object]{.type-label} + - **`AutomaticDeploymentTargets`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsOptionalPhase`** :span[boolean]{.type-label} + - **`IsPriorityPhase`** :span[boolean]{.type-label} + - **`MinimumEnvironmentsBeforePromotion`** :span[integer]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OptionalDeploymentTargets`** :span[array of string]{.type-label} + - **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`TentacleRetentionPolicy`** :span[object]{.type-label} +- **`ReleaseRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TentacleRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Phases": [ + { + "AutomaticDeploymentTargets": [ + "string" + ], + "Id": "string", + "IsOptionalPhase": true, + "IsPriorityPhase": true, + "MinimumEnvironmentsBeforePromotion": 0, + "Name": "string", + "OptionalDeploymentTargets": [ + "string" + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } + } + ], + "ReleaseRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "Slug": "string", + "SpaceId": "string", + "TentacleRetentionPolicy": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } +} +``` +::: + +## Get all projects that use this lifecycle + +:endpoint{method="GET" path="/api/\{spaceId\}/lifecycles/\{id\}/projects"} + +Also reachable at `/api/lifecycles/{id}/projects`, `/api/spaces/{spaceIdentifier}/lifecycles/{id}/projects`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the Lifecycle. +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the space for the Lifecycle and projects. + +**Response** + +`200` — Get all projects that use this lifecycle. + +- **`AllowIgnoreChannelRules`** :span[boolean]{.type-label} +- **`AutoCreateRelease`** :span[boolean]{.type-label} +- **`AutoDeployReleaseOverrides`** :span[array of object]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ReleaseId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`ClonedFromProjectId`** :span[string]{.type-label} +- **`CombineHealthAndSyncStatusInDashboardLiveStatus`** :span[boolean]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`DefaultPowerShellEdition`** :span[string]{.type-label} +- **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} +- **`DeploymentChangesTemplate`** :span[string]{.type-label} +- **`DeploymentProcessId`** :span[string]{.type-label} +- **`DeprovisioningRunbookId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`DiscreteChannelRelease`** :span[boolean]{.type-label} + Treats releases of different channels to the same environment as a seperate deployment dimension. 'False' indicates a "hotfix"-style usage of channels (single release active per environment ignoring channels), whereas `True` indicates "microservice"-style usage (single release per environment per channel). +- **`ExecuteDeploymentsOnEventBasedPipeline`** :span[boolean]{.type-label} +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IncludedLibraryVariableSetIds`** :span[array of string]{.type-label} + Library variable sets included in the project. Sets are listed in order of precedence, with earlier items in the list overriding any variables with the same name and scope definition appearing later in the list. +- **`IsBadgesEnabled`** :span[boolean]{.type-label} +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsVersionControlled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LifecycleId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`PersistenceSettings`** :span[object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `Database`, `VersionControlled`. +- **`ProjectConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`ProjectGroupId`** :span[string]{.type-label} +- **`ProjectTags`** :span[array of string]{.type-label} + List of tags assigned to this project. +- **`ProjectTemplateDetails`** :span[object]{.type-label} + - **`IsShared`** :span[boolean]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`VersionMask`** :span[string]{.type-label} + Minimum length 1. +- **`ProvisioningRunbookId`** :span[string]{.type-label} +- **`ReleaseCreationStrategy`** :span[object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`ReleaseCreationPackage`** :span[object]{.type-label} +- **`ReleaseNotesTemplate`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Templates`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`TenantedDeploymentMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`VariableSetId`** :span[string]{.type-label} +- **`VersioningStrategy`** :span[object]{.type-label} + - **`DonorPackage`** :span[object]{.type-label} + - **`Template`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "AllowIgnoreChannelRules": true, + "AutoCreateRelease": true, + "AutoDeployReleaseOverrides": [ + { + "EnvironmentId": "string", + "ReleaseId": "string", + "TenantId": "string" + } + ], + "ClonedFromProjectId": "string", + "CombineHealthAndSyncStatusInDashboardLiveStatus": true, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultPowerShellEdition": "string", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "DeploymentProcessId": "string", + "DeprovisioningRunbookId": "string", + "Description": "string", + "DiscreteChannelRelease": true, + "ExecuteDeploymentsOnEventBasedPipeline": true, + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "ForcePackageDownload": true, + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IncludedLibraryVariableSetIds": [ + "string" + ], + "IsBadgesEnabled": true, + "IsDisabled": true, + "IsVersionControlled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PersistenceSettings": { + "Type": "Database" + }, + "ProjectConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "ProjectGroupId": "string", + "ProjectTags": [ + "string" + ], + "ProjectTemplateDetails": { + "IsShared": true, + "Slug": "string", + "VersionMask": "string" + }, + "ProvisioningRunbookId": "string", + "ReleaseCreationStrategy": { + "ChannelId": "string", + "ReleaseCreationPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + } + }, + "ReleaseNotesTemplate": "string", + "Slug": "string", + "SpaceId": "string", + "Templates": [ + { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "TenantedDeploymentMode": "Untenanted", + "VariableSetId": "string", + "VersioningStrategy": { + "DonorPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + }, + "Template": "string" + } + } +] +``` +::: diff --git a/src/pages/docs/api/machine-policies.md b/src/pages/docs/api/machine-policies.md new file mode 100644 index 0000000000..97ec5bfda0 --- /dev/null +++ b/src/pages/docs/api/machine-policies.md @@ -0,0 +1,1386 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Machine Policies +--- + +## Get a paginated list of the Machine Policies in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name + +:endpoint{method="GET" path="/api/\{spaceId\}/machinepolicies"} + +Also reachable at `/api/machinepolicies`, `/api/spaces/{spaceIdentifier}/machinepolicies`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + Specific machine policy IDs to filter out. +- **`partialName`** :span[string]{.type-label} + A partial machine policy name used for a sub-string search. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — A paginated list of the Machine Policies in the supplied Octopus Deploy Space (sorted alphabetically by name). + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`ConnectionConnectTimeout`** :span[string]{.type-label} + Format `date-span`. + - **`ConnectionRetryCountLimit`** :span[integer]{.type-label} + - **`ConnectionRetrySleepInterval`** :span[string]{.type-label} + Format `date-span`. + - **`ConnectionRetryTimeLimit`** :span[string]{.type-label} + Format `date-span`. + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDefault`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MachineCleanupPolicy`** :span[object]{.type-label} + - **`MachineConnectivityPolicy`** :span[object]{.type-label} + - **`MachineHealthCheckPolicy`** :span[object]{.type-label} + - **`MachinePackageCacheRetentionPolicy`** :span[object]{.type-label} + - **`MachineRpcCallRetryPolicy`** :span[object]{.type-label} + - **`MachineUpdatePolicy`** :span[object]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`PollingRequestQueueTimeout`** :span[string]{.type-label} + Format `date-span`. + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "ConnectionConnectTimeout": "string", + "ConnectionRetryCountLimit": 0, + "ConnectionRetrySleepInterval": "string", + "ConnectionRetryTimeLimit": "string", + "Description": "string", + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachineCleanupPolicy": { + "DeleteMachinesBehavior": "DoNotDelete", + "DeleteMachinesElapsedTimeSpan": "string" + }, + "MachineConnectivityPolicy": { + "MachineConnectivityBehavior": "ExpectedToBeOnline" + }, + "MachineHealthCheckPolicy": { + "BashHealthCheckPolicy": {}, + "HealthCheckCron": "string", + "HealthCheckCronTimezone": "string", + "HealthCheckInterval": "string", + "HealthCheckType": "RunScript", + "PowerShellHealthCheckPolicy": {} + }, + "MachinePackageCacheRetentionPolicy": { + "PackageUnit": "Items", + "QuantityOfPackagesToKeep": 0, + "QuantityOfVersionsToKeep": 0, + "Strategy": "Default", + "VersionUnit": "Items" + }, + "MachineRpcCallRetryPolicy": { + "Enabled": true, + "HealthCheckRetryDuration": "string", + "RetryDuration": "string" + }, + "MachineUpdatePolicy": { + "CalamariUpdateBehavior": "UpdateOnDeployment", + "KubernetesAgentUpdateBehavior": "NeverUpdate", + "TentacleUpdateAccountId": "string", + "TentacleUpdateBehavior": "NeverUpdate" + }, + "Name": "string", + "PollingRequestQueueTimeout": "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 +} +``` +::: + +## Create a new Machine Policy + +:endpoint{method="POST" path="/api/\{spaceId\}/machinepolicies"} + +Also reachable at `/api/machinepolicies`, `/api/spaces/{spaceIdentifier}/machinepolicies`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ConnectionConnectTimeout`** :span[string]{.type-label} + Format `date-span`. +- **`ConnectionRetryCountLimit`** :span[integer]{.type-label} +- **`ConnectionRetrySleepInterval`** :span[string]{.type-label} + Format `date-span`. +- **`ConnectionRetryTimeLimit`** :span[string]{.type-label} + Format `date-span`. +- **`Description`** :span[string]{.type-label} +- **`IsDefault`** :span[boolean]{.type-label} +- **`MachineCleanupPolicy`** :span[object]{.type-label} + - **`DeleteMachinesBehavior`** :span[enum]{.type-label} + Allowed values: `DoNotDelete`, `DeleteUnavailableMachines`. + - **`DeleteMachinesElapsedTimeSpan`** :span[string]{.type-label} + Format `date-span`. +- **`MachineConnectivityPolicy`** :span[object]{.type-label} + - **`MachineConnectivityBehavior`** :span[enum]{.type-label} + Allowed values: `ExpectedToBeOnline`, `MayBeOfflineAndCanBeSkipped`. +- **`MachineHealthCheckPolicy`** :span[object]{.type-label} + - **`BashHealthCheckPolicy`** :span[object]{.type-label} + - **`HealthCheckCron`** :span[string]{.type-label} + - **`HealthCheckCronTimezone`** :span[string]{.type-label} + - **`HealthCheckInterval`** :span[string]{.type-label} + Format `date-span`. + - **`HealthCheckType`** :span[enum]{.type-label} + Allowed values: `RunScript`, `OnlyConnectivity`. + - **`PowerShellHealthCheckPolicy`** :span[object]{.type-label} +- **`MachinePackageCacheRetentionPolicy`** :span[object]{.type-label} + - **`PackageUnit`** :span[enum]{.type-label} + Allowed values: `Items`. + - **`QuantityOfPackagesToKeep`** :span[integer]{.type-label} + - **`QuantityOfVersionsToKeep`** :span[integer]{.type-label} + - **`Strategy`** :span[enum]{.type-label} + Allowed values: `Default`, `Quantities`. + - **`VersionUnit`** :span[enum]{.type-label} + Allowed values: `Items`. +- **`MachineRpcCallRetryPolicy`** :span[object]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} + - **`HealthCheckRetryDuration`** :span[string]{.type-label} + Format `date-span`. + - **`RetryDuration`** :span[string]{.type-label} + Format `date-span`. +- **`MachineUpdatePolicy`** :span[object]{.type-label} + - **`CalamariUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `UpdateOnDeployment`, `UpdateOnNewMachine`, `UpdateAlways`. + - **`KubernetesAgentUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `NeverUpdate`, `Update`, `Block`. + - **`TentacleUpdateAccountId`** :span[string]{.type-label} + - **`TentacleUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `NeverUpdate`, `Update`. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`PollingRequestQueueTimeout`** :span[string]{.type-label} + Format `date-span`. +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "ConnectionConnectTimeout": "string", + "ConnectionRetryCountLimit": 0, + "ConnectionRetrySleepInterval": "string", + "ConnectionRetryTimeLimit": "string", + "Description": "string", + "IsDefault": true, + "MachineCleanupPolicy": { + "DeleteMachinesBehavior": "DoNotDelete", + "DeleteMachinesElapsedTimeSpan": "string" + }, + "MachineConnectivityPolicy": { + "MachineConnectivityBehavior": "ExpectedToBeOnline" + }, + "MachineHealthCheckPolicy": { + "BashHealthCheckPolicy": { + "RunType": "InheritFromDefault", + "ScriptBody": "string" + }, + "HealthCheckCron": "string", + "HealthCheckCronTimezone": "string", + "HealthCheckInterval": "string", + "HealthCheckType": "RunScript", + "PowerShellHealthCheckPolicy": { + "RunType": "InheritFromDefault", + "ScriptBody": "string" + } + }, + "MachinePackageCacheRetentionPolicy": { + "PackageUnit": "Items", + "QuantityOfPackagesToKeep": 0, + "QuantityOfVersionsToKeep": 0, + "Strategy": "Default", + "VersionUnit": "Items" + }, + "MachineRpcCallRetryPolicy": { + "Enabled": true, + "HealthCheckRetryDuration": "string", + "RetryDuration": "string" + }, + "MachineUpdatePolicy": { + "CalamariUpdateBehavior": "UpdateOnDeployment", + "KubernetesAgentUpdateBehavior": "NeverUpdate", + "TentacleUpdateAccountId": "string", + "TentacleUpdateBehavior": "NeverUpdate" + }, + "Name": "string", + "PollingRequestQueueTimeout": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`ConnectionConnectTimeout`** :span[string]{.type-label} + Format `date-span`. +- **`ConnectionRetryCountLimit`** :span[integer]{.type-label} +- **`ConnectionRetrySleepInterval`** :span[string]{.type-label} + Format `date-span`. +- **`ConnectionRetryTimeLimit`** :span[string]{.type-label} + Format `date-span`. +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachineCleanupPolicy`** :span[object]{.type-label} + - **`DeleteMachinesBehavior`** :span[enum]{.type-label} + Allowed values: `DoNotDelete`, `DeleteUnavailableMachines`. + - **`DeleteMachinesElapsedTimeSpan`** :span[string]{.type-label} + Format `date-span`. +- **`MachineConnectivityPolicy`** :span[object]{.type-label} + - **`MachineConnectivityBehavior`** :span[enum]{.type-label} + Allowed values: `ExpectedToBeOnline`, `MayBeOfflineAndCanBeSkipped`. +- **`MachineHealthCheckPolicy`** :span[object]{.type-label} + - **`BashHealthCheckPolicy`** :span[object]{.type-label} + - **`HealthCheckCron`** :span[string]{.type-label} + - **`HealthCheckCronTimezone`** :span[string]{.type-label} + - **`HealthCheckInterval`** :span[string]{.type-label} + Format `date-span`. + - **`HealthCheckType`** :span[enum]{.type-label} + Allowed values: `RunScript`, `OnlyConnectivity`. + - **`PowerShellHealthCheckPolicy`** :span[object]{.type-label} +- **`MachinePackageCacheRetentionPolicy`** :span[object]{.type-label} + - **`PackageUnit`** :span[enum]{.type-label} + Allowed values: `Items`. + - **`QuantityOfPackagesToKeep`** :span[integer]{.type-label} + - **`QuantityOfVersionsToKeep`** :span[integer]{.type-label} + - **`Strategy`** :span[enum]{.type-label} + Allowed values: `Default`, `Quantities`. + - **`VersionUnit`** :span[enum]{.type-label} + Allowed values: `Items`. +- **`MachineRpcCallRetryPolicy`** :span[object]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} + - **`HealthCheckRetryDuration`** :span[string]{.type-label} + Format `date-span`. + - **`RetryDuration`** :span[string]{.type-label} + Format `date-span`. +- **`MachineUpdatePolicy`** :span[object]{.type-label} + - **`CalamariUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `UpdateOnDeployment`, `UpdateOnNewMachine`, `UpdateAlways`. + - **`KubernetesAgentUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `NeverUpdate`, `Update`, `Block`. + - **`TentacleUpdateAccountId`** :span[string]{.type-label} + - **`TentacleUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `NeverUpdate`, `Update`. +- **`Name`** :span[string]{.type-label} +- **`PollingRequestQueueTimeout`** :span[string]{.type-label} + Format `date-span`. +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConnectionConnectTimeout": "string", + "ConnectionRetryCountLimit": 0, + "ConnectionRetrySleepInterval": "string", + "ConnectionRetryTimeLimit": "string", + "Description": "string", + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachineCleanupPolicy": { + "DeleteMachinesBehavior": "DoNotDelete", + "DeleteMachinesElapsedTimeSpan": "string" + }, + "MachineConnectivityPolicy": { + "MachineConnectivityBehavior": "ExpectedToBeOnline" + }, + "MachineHealthCheckPolicy": { + "BashHealthCheckPolicy": { + "RunType": "InheritFromDefault", + "ScriptBody": "string" + }, + "HealthCheckCron": "string", + "HealthCheckCronTimezone": "string", + "HealthCheckInterval": "string", + "HealthCheckType": "RunScript", + "PowerShellHealthCheckPolicy": { + "RunType": "InheritFromDefault", + "ScriptBody": "string" + } + }, + "MachinePackageCacheRetentionPolicy": { + "PackageUnit": "Items", + "QuantityOfPackagesToKeep": 0, + "QuantityOfVersionsToKeep": 0, + "Strategy": "Default", + "VersionUnit": "Items" + }, + "MachineRpcCallRetryPolicy": { + "Enabled": true, + "HealthCheckRetryDuration": "string", + "RetryDuration": "string" + }, + "MachineUpdatePolicy": { + "CalamariUpdateBehavior": "UpdateOnDeployment", + "KubernetesAgentUpdateBehavior": "NeverUpdate", + "TentacleUpdateAccountId": "string", + "TentacleUpdateBehavior": "NeverUpdate" + }, + "Name": "string", + "PollingRequestQueueTimeout": "string", + "SpaceId": "string" +} +``` +::: + +## Get a list of Machine Policies + +:endpoint{method="GET" path="/api/\{spaceId\}/machinepolicies/all"} + +Also reachable at `/api/machinepolicies/all`, `/api/spaces/{spaceIdentifier}/machinepolicies/all`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — All the Machine Policies in the supplied Octopus Deploy Space. + +- **`ConnectionConnectTimeout`** :span[string]{.type-label} + Format `date-span`. +- **`ConnectionRetryCountLimit`** :span[integer]{.type-label} +- **`ConnectionRetrySleepInterval`** :span[string]{.type-label} + Format `date-span`. +- **`ConnectionRetryTimeLimit`** :span[string]{.type-label} + Format `date-span`. +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachineCleanupPolicy`** :span[object]{.type-label} + - **`DeleteMachinesBehavior`** :span[enum]{.type-label} + Allowed values: `DoNotDelete`, `DeleteUnavailableMachines`. + - **`DeleteMachinesElapsedTimeSpan`** :span[string]{.type-label} + Format `date-span`. +- **`MachineConnectivityPolicy`** :span[object]{.type-label} + - **`MachineConnectivityBehavior`** :span[enum]{.type-label} + Allowed values: `ExpectedToBeOnline`, `MayBeOfflineAndCanBeSkipped`. +- **`MachineHealthCheckPolicy`** :span[object]{.type-label} + - **`BashHealthCheckPolicy`** :span[object]{.type-label} + - **`HealthCheckCron`** :span[string]{.type-label} + - **`HealthCheckCronTimezone`** :span[string]{.type-label} + - **`HealthCheckInterval`** :span[string]{.type-label} + Format `date-span`. + - **`HealthCheckType`** :span[enum]{.type-label} + Allowed values: `RunScript`, `OnlyConnectivity`. + - **`PowerShellHealthCheckPolicy`** :span[object]{.type-label} +- **`MachinePackageCacheRetentionPolicy`** :span[object]{.type-label} + - **`PackageUnit`** :span[enum]{.type-label} + Allowed values: `Items`. + - **`QuantityOfPackagesToKeep`** :span[integer]{.type-label} + - **`QuantityOfVersionsToKeep`** :span[integer]{.type-label} + - **`Strategy`** :span[enum]{.type-label} + Allowed values: `Default`, `Quantities`. + - **`VersionUnit`** :span[enum]{.type-label} + Allowed values: `Items`. +- **`MachineRpcCallRetryPolicy`** :span[object]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} + - **`HealthCheckRetryDuration`** :span[string]{.type-label} + Format `date-span`. + - **`RetryDuration`** :span[string]{.type-label} + Format `date-span`. +- **`MachineUpdatePolicy`** :span[object]{.type-label} + - **`CalamariUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `UpdateOnDeployment`, `UpdateOnNewMachine`, `UpdateAlways`. + - **`KubernetesAgentUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `NeverUpdate`, `Update`, `Block`. + - **`TentacleUpdateAccountId`** :span[string]{.type-label} + - **`TentacleUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `NeverUpdate`, `Update`. +- **`Name`** :span[string]{.type-label} +- **`PollingRequestQueueTimeout`** :span[string]{.type-label} + Format `date-span`. +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "ConnectionConnectTimeout": "string", + "ConnectionRetryCountLimit": 0, + "ConnectionRetrySleepInterval": "string", + "ConnectionRetryTimeLimit": "string", + "Description": "string", + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachineCleanupPolicy": { + "DeleteMachinesBehavior": "DoNotDelete", + "DeleteMachinesElapsedTimeSpan": "string" + }, + "MachineConnectivityPolicy": { + "MachineConnectivityBehavior": "ExpectedToBeOnline" + }, + "MachineHealthCheckPolicy": { + "BashHealthCheckPolicy": { + "RunType": "InheritFromDefault", + "ScriptBody": "string" + }, + "HealthCheckCron": "string", + "HealthCheckCronTimezone": "string", + "HealthCheckInterval": "string", + "HealthCheckType": "RunScript", + "PowerShellHealthCheckPolicy": { + "RunType": "InheritFromDefault", + "ScriptBody": "string" + } + }, + "MachinePackageCacheRetentionPolicy": { + "PackageUnit": "Items", + "QuantityOfPackagesToKeep": 0, + "QuantityOfVersionsToKeep": 0, + "Strategy": "Default", + "VersionUnit": "Items" + }, + "MachineRpcCallRetryPolicy": { + "Enabled": true, + "HealthCheckRetryDuration": "string", + "RetryDuration": "string" + }, + "MachineUpdatePolicy": { + "CalamariUpdateBehavior": "UpdateOnDeployment", + "KubernetesAgentUpdateBehavior": "NeverUpdate", + "TentacleUpdateAccountId": "string", + "TentacleUpdateBehavior": "NeverUpdate" + }, + "Name": "string", + "PollingRequestQueueTimeout": "string", + "SpaceId": "string" + } +] +``` +::: + +## Get a template for a new Machine Policy, which includes any defaults + +:endpoint{method="GET" path="/api/\{spaceId\}/machinepolicies/template"} + +Also reachable at `/api/machinepolicies/template`, `/api/spaces/{spaceIdentifier}/machinepolicies/template`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested Machine Policy Template + +- **`ConnectionConnectTimeout`** :span[string]{.type-label} + Format `date-span`. +- **`ConnectionRetryCountLimit`** :span[integer]{.type-label} +- **`ConnectionRetrySleepInterval`** :span[string]{.type-label} + Format `date-span`. +- **`ConnectionRetryTimeLimit`** :span[string]{.type-label} + Format `date-span`. +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachineCleanupPolicy`** :span[object]{.type-label} + - **`DeleteMachinesBehavior`** :span[enum]{.type-label} + Allowed values: `DoNotDelete`, `DeleteUnavailableMachines`. + - **`DeleteMachinesElapsedTimeSpan`** :span[string]{.type-label} + Format `date-span`. +- **`MachineConnectivityPolicy`** :span[object]{.type-label} + - **`MachineConnectivityBehavior`** :span[enum]{.type-label} + Allowed values: `ExpectedToBeOnline`, `MayBeOfflineAndCanBeSkipped`. +- **`MachineHealthCheckPolicy`** :span[object]{.type-label} + - **`BashHealthCheckPolicy`** :span[object]{.type-label} + - **`HealthCheckCron`** :span[string]{.type-label} + - **`HealthCheckCronTimezone`** :span[string]{.type-label} + - **`HealthCheckInterval`** :span[string]{.type-label} + Format `date-span`. + - **`HealthCheckType`** :span[enum]{.type-label} + Allowed values: `RunScript`, `OnlyConnectivity`. + - **`PowerShellHealthCheckPolicy`** :span[object]{.type-label} +- **`MachinePackageCacheRetentionPolicy`** :span[object]{.type-label} + - **`PackageUnit`** :span[enum]{.type-label} + Allowed values: `Items`. + - **`QuantityOfPackagesToKeep`** :span[integer]{.type-label} + - **`QuantityOfVersionsToKeep`** :span[integer]{.type-label} + - **`Strategy`** :span[enum]{.type-label} + Allowed values: `Default`, `Quantities`. + - **`VersionUnit`** :span[enum]{.type-label} + Allowed values: `Items`. +- **`MachineRpcCallRetryPolicy`** :span[object]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} + - **`HealthCheckRetryDuration`** :span[string]{.type-label} + Format `date-span`. + - **`RetryDuration`** :span[string]{.type-label} + Format `date-span`. +- **`MachineUpdatePolicy`** :span[object]{.type-label} + - **`CalamariUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `UpdateOnDeployment`, `UpdateOnNewMachine`, `UpdateAlways`. + - **`KubernetesAgentUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `NeverUpdate`, `Update`, `Block`. + - **`TentacleUpdateAccountId`** :span[string]{.type-label} + - **`TentacleUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `NeverUpdate`, `Update`. +- **`Name`** :span[string]{.type-label} +- **`PollingRequestQueueTimeout`** :span[string]{.type-label} + Format `date-span`. +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConnectionConnectTimeout": "string", + "ConnectionRetryCountLimit": 0, + "ConnectionRetrySleepInterval": "string", + "ConnectionRetryTimeLimit": "string", + "Description": "string", + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachineCleanupPolicy": { + "DeleteMachinesBehavior": "DoNotDelete", + "DeleteMachinesElapsedTimeSpan": "string" + }, + "MachineConnectivityPolicy": { + "MachineConnectivityBehavior": "ExpectedToBeOnline" + }, + "MachineHealthCheckPolicy": { + "BashHealthCheckPolicy": { + "RunType": "InheritFromDefault", + "ScriptBody": "string" + }, + "HealthCheckCron": "string", + "HealthCheckCronTimezone": "string", + "HealthCheckInterval": "string", + "HealthCheckType": "RunScript", + "PowerShellHealthCheckPolicy": { + "RunType": "InheritFromDefault", + "ScriptBody": "string" + } + }, + "MachinePackageCacheRetentionPolicy": { + "PackageUnit": "Items", + "QuantityOfPackagesToKeep": 0, + "QuantityOfVersionsToKeep": 0, + "Strategy": "Default", + "VersionUnit": "Items" + }, + "MachineRpcCallRetryPolicy": { + "Enabled": true, + "HealthCheckRetryDuration": "string", + "RetryDuration": "string" + }, + "MachineUpdatePolicy": { + "CalamariUpdateBehavior": "UpdateOnDeployment", + "KubernetesAgentUpdateBehavior": "NeverUpdate", + "TentacleUpdateAccountId": "string", + "TentacleUpdateBehavior": "NeverUpdate" + }, + "Name": "string", + "PollingRequestQueueTimeout": "string", + "SpaceId": "string" +} +``` +::: + +## Get a Machine Policy by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/machinepolicies/\{id\}"} + +Also reachable at `/api/machinepolicies/{id}`, `/api/spaces/{spaceIdentifier}/machinepolicies/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Machine Policy. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested machine policy + +- **`ConnectionConnectTimeout`** :span[string]{.type-label} + Format `date-span`. +- **`ConnectionRetryCountLimit`** :span[integer]{.type-label} +- **`ConnectionRetrySleepInterval`** :span[string]{.type-label} + Format `date-span`. +- **`ConnectionRetryTimeLimit`** :span[string]{.type-label} + Format `date-span`. +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachineCleanupPolicy`** :span[object]{.type-label} + - **`DeleteMachinesBehavior`** :span[enum]{.type-label} + Allowed values: `DoNotDelete`, `DeleteUnavailableMachines`. + - **`DeleteMachinesElapsedTimeSpan`** :span[string]{.type-label} + Format `date-span`. +- **`MachineConnectivityPolicy`** :span[object]{.type-label} + - **`MachineConnectivityBehavior`** :span[enum]{.type-label} + Allowed values: `ExpectedToBeOnline`, `MayBeOfflineAndCanBeSkipped`. +- **`MachineHealthCheckPolicy`** :span[object]{.type-label} + - **`BashHealthCheckPolicy`** :span[object]{.type-label} + - **`HealthCheckCron`** :span[string]{.type-label} + - **`HealthCheckCronTimezone`** :span[string]{.type-label} + - **`HealthCheckInterval`** :span[string]{.type-label} + Format `date-span`. + - **`HealthCheckType`** :span[enum]{.type-label} + Allowed values: `RunScript`, `OnlyConnectivity`. + - **`PowerShellHealthCheckPolicy`** :span[object]{.type-label} +- **`MachinePackageCacheRetentionPolicy`** :span[object]{.type-label} + - **`PackageUnit`** :span[enum]{.type-label} + Allowed values: `Items`. + - **`QuantityOfPackagesToKeep`** :span[integer]{.type-label} + - **`QuantityOfVersionsToKeep`** :span[integer]{.type-label} + - **`Strategy`** :span[enum]{.type-label} + Allowed values: `Default`, `Quantities`. + - **`VersionUnit`** :span[enum]{.type-label} + Allowed values: `Items`. +- **`MachineRpcCallRetryPolicy`** :span[object]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} + - **`HealthCheckRetryDuration`** :span[string]{.type-label} + Format `date-span`. + - **`RetryDuration`** :span[string]{.type-label} + Format `date-span`. +- **`MachineUpdatePolicy`** :span[object]{.type-label} + - **`CalamariUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `UpdateOnDeployment`, `UpdateOnNewMachine`, `UpdateAlways`. + - **`KubernetesAgentUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `NeverUpdate`, `Update`, `Block`. + - **`TentacleUpdateAccountId`** :span[string]{.type-label} + - **`TentacleUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `NeverUpdate`, `Update`. +- **`Name`** :span[string]{.type-label} +- **`PollingRequestQueueTimeout`** :span[string]{.type-label} + Format `date-span`. +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConnectionConnectTimeout": "string", + "ConnectionRetryCountLimit": 0, + "ConnectionRetrySleepInterval": "string", + "ConnectionRetryTimeLimit": "string", + "Description": "string", + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachineCleanupPolicy": { + "DeleteMachinesBehavior": "DoNotDelete", + "DeleteMachinesElapsedTimeSpan": "string" + }, + "MachineConnectivityPolicy": { + "MachineConnectivityBehavior": "ExpectedToBeOnline" + }, + "MachineHealthCheckPolicy": { + "BashHealthCheckPolicy": { + "RunType": "InheritFromDefault", + "ScriptBody": "string" + }, + "HealthCheckCron": "string", + "HealthCheckCronTimezone": "string", + "HealthCheckInterval": "string", + "HealthCheckType": "RunScript", + "PowerShellHealthCheckPolicy": { + "RunType": "InheritFromDefault", + "ScriptBody": "string" + } + }, + "MachinePackageCacheRetentionPolicy": { + "PackageUnit": "Items", + "QuantityOfPackagesToKeep": 0, + "QuantityOfVersionsToKeep": 0, + "Strategy": "Default", + "VersionUnit": "Items" + }, + "MachineRpcCallRetryPolicy": { + "Enabled": true, + "HealthCheckRetryDuration": "string", + "RetryDuration": "string" + }, + "MachineUpdatePolicy": { + "CalamariUpdateBehavior": "UpdateOnDeployment", + "KubernetesAgentUpdateBehavior": "NeverUpdate", + "TentacleUpdateAccountId": "string", + "TentacleUpdateBehavior": "NeverUpdate" + }, + "Name": "string", + "PollingRequestQueueTimeout": "string", + "SpaceId": "string" +} +``` +::: + +## Modify an existing Machine Policy + +:endpoint{method="PUT" path="/api/\{spaceId\}/machinepolicies/\{id\}"} + +Also reachable at `/api/machinepolicies/{id}`, `/api/spaces/{spaceIdentifier}/machinepolicies/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The Machine Policy ID. +- **`spaceId`** :span[string]{.type-label} *(required)* + The Space ID. + +**Request Body** + +- **`ConnectionConnectTimeout`** :span[string]{.type-label} + Format `date-span`. +- **`ConnectionRetryCountLimit`** :span[integer]{.type-label} +- **`ConnectionRetrySleepInterval`** :span[string]{.type-label} + Format `date-span`. +- **`ConnectionRetryTimeLimit`** :span[string]{.type-label} + Format `date-span`. +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* + The Machine Policy ID. +- **`IsDefault`** :span[boolean]{.type-label} +- **`MachineCleanupPolicy`** :span[object]{.type-label} + - **`DeleteMachinesBehavior`** :span[enum]{.type-label} + Allowed values: `DoNotDelete`, `DeleteUnavailableMachines`. + - **`DeleteMachinesElapsedTimeSpan`** :span[string]{.type-label} + Format `date-span`. +- **`MachineConnectivityPolicy`** :span[object]{.type-label} + - **`MachineConnectivityBehavior`** :span[enum]{.type-label} + Allowed values: `ExpectedToBeOnline`, `MayBeOfflineAndCanBeSkipped`. +- **`MachineHealthCheckPolicy`** :span[object]{.type-label} + - **`BashHealthCheckPolicy`** :span[object]{.type-label} + - **`HealthCheckCron`** :span[string]{.type-label} + - **`HealthCheckCronTimezone`** :span[string]{.type-label} + - **`HealthCheckInterval`** :span[string]{.type-label} + Format `date-span`. + - **`HealthCheckType`** :span[enum]{.type-label} + Allowed values: `RunScript`, `OnlyConnectivity`. + - **`PowerShellHealthCheckPolicy`** :span[object]{.type-label} +- **`MachinePackageCacheRetentionPolicy`** :span[object]{.type-label} + - **`PackageUnit`** :span[enum]{.type-label} + Allowed values: `Items`. + - **`QuantityOfPackagesToKeep`** :span[integer]{.type-label} + - **`QuantityOfVersionsToKeep`** :span[integer]{.type-label} + - **`Strategy`** :span[enum]{.type-label} + Allowed values: `Default`, `Quantities`. + - **`VersionUnit`** :span[enum]{.type-label} + Allowed values: `Items`. +- **`MachineRpcCallRetryPolicy`** :span[object]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} + - **`HealthCheckRetryDuration`** :span[string]{.type-label} + Format `date-span`. + - **`RetryDuration`** :span[string]{.type-label} + Format `date-span`. +- **`MachineUpdatePolicy`** :span[object]{.type-label} + - **`CalamariUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `UpdateOnDeployment`, `UpdateOnNewMachine`, `UpdateAlways`. + - **`KubernetesAgentUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `NeverUpdate`, `Update`, `Block`. + - **`TentacleUpdateAccountId`** :span[string]{.type-label} + - **`TentacleUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `NeverUpdate`, `Update`. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`PollingRequestQueueTimeout`** :span[string]{.type-label} + Format `date-span`. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The Space ID. + +:::api-example{label="Request"} +```json +{ + "ConnectionConnectTimeout": "string", + "ConnectionRetryCountLimit": 0, + "ConnectionRetrySleepInterval": "string", + "ConnectionRetryTimeLimit": "string", + "Description": "string", + "Id": "string", + "IsDefault": true, + "MachineCleanupPolicy": { + "DeleteMachinesBehavior": "DoNotDelete", + "DeleteMachinesElapsedTimeSpan": "string" + }, + "MachineConnectivityPolicy": { + "MachineConnectivityBehavior": "ExpectedToBeOnline" + }, + "MachineHealthCheckPolicy": { + "BashHealthCheckPolicy": { + "RunType": "InheritFromDefault", + "ScriptBody": "string" + }, + "HealthCheckCron": "string", + "HealthCheckCronTimezone": "string", + "HealthCheckInterval": "string", + "HealthCheckType": "RunScript", + "PowerShellHealthCheckPolicy": { + "RunType": "InheritFromDefault", + "ScriptBody": "string" + } + }, + "MachinePackageCacheRetentionPolicy": { + "PackageUnit": "Items", + "QuantityOfPackagesToKeep": 0, + "QuantityOfVersionsToKeep": 0, + "Strategy": "Default", + "VersionUnit": "Items" + }, + "MachineRpcCallRetryPolicy": { + "Enabled": true, + "HealthCheckRetryDuration": "string", + "RetryDuration": "string" + }, + "MachineUpdatePolicy": { + "CalamariUpdateBehavior": "UpdateOnDeployment", + "KubernetesAgentUpdateBehavior": "NeverUpdate", + "TentacleUpdateAccountId": "string", + "TentacleUpdateBehavior": "NeverUpdate" + }, + "Name": "string", + "PollingRequestQueueTimeout": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Machine Policy was modified, containing the new Policy + +- **`ConnectionConnectTimeout`** :span[string]{.type-label} + Format `date-span`. +- **`ConnectionRetryCountLimit`** :span[integer]{.type-label} +- **`ConnectionRetrySleepInterval`** :span[string]{.type-label} + Format `date-span`. +- **`ConnectionRetryTimeLimit`** :span[string]{.type-label} + Format `date-span`. +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachineCleanupPolicy`** :span[object]{.type-label} + - **`DeleteMachinesBehavior`** :span[enum]{.type-label} + Allowed values: `DoNotDelete`, `DeleteUnavailableMachines`. + - **`DeleteMachinesElapsedTimeSpan`** :span[string]{.type-label} + Format `date-span`. +- **`MachineConnectivityPolicy`** :span[object]{.type-label} + - **`MachineConnectivityBehavior`** :span[enum]{.type-label} + Allowed values: `ExpectedToBeOnline`, `MayBeOfflineAndCanBeSkipped`. +- **`MachineHealthCheckPolicy`** :span[object]{.type-label} + - **`BashHealthCheckPolicy`** :span[object]{.type-label} + - **`HealthCheckCron`** :span[string]{.type-label} + - **`HealthCheckCronTimezone`** :span[string]{.type-label} + - **`HealthCheckInterval`** :span[string]{.type-label} + Format `date-span`. + - **`HealthCheckType`** :span[enum]{.type-label} + Allowed values: `RunScript`, `OnlyConnectivity`. + - **`PowerShellHealthCheckPolicy`** :span[object]{.type-label} +- **`MachinePackageCacheRetentionPolicy`** :span[object]{.type-label} + - **`PackageUnit`** :span[enum]{.type-label} + Allowed values: `Items`. + - **`QuantityOfPackagesToKeep`** :span[integer]{.type-label} + - **`QuantityOfVersionsToKeep`** :span[integer]{.type-label} + - **`Strategy`** :span[enum]{.type-label} + Allowed values: `Default`, `Quantities`. + - **`VersionUnit`** :span[enum]{.type-label} + Allowed values: `Items`. +- **`MachineRpcCallRetryPolicy`** :span[object]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} + - **`HealthCheckRetryDuration`** :span[string]{.type-label} + Format `date-span`. + - **`RetryDuration`** :span[string]{.type-label} + Format `date-span`. +- **`MachineUpdatePolicy`** :span[object]{.type-label} + - **`CalamariUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `UpdateOnDeployment`, `UpdateOnNewMachine`, `UpdateAlways`. + - **`KubernetesAgentUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `NeverUpdate`, `Update`, `Block`. + - **`TentacleUpdateAccountId`** :span[string]{.type-label} + - **`TentacleUpdateBehavior`** :span[enum]{.type-label} + Allowed values: `NeverUpdate`, `Update`. +- **`Name`** :span[string]{.type-label} +- **`PollingRequestQueueTimeout`** :span[string]{.type-label} + Format `date-span`. +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConnectionConnectTimeout": "string", + "ConnectionRetryCountLimit": 0, + "ConnectionRetrySleepInterval": "string", + "ConnectionRetryTimeLimit": "string", + "Description": "string", + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachineCleanupPolicy": { + "DeleteMachinesBehavior": "DoNotDelete", + "DeleteMachinesElapsedTimeSpan": "string" + }, + "MachineConnectivityPolicy": { + "MachineConnectivityBehavior": "ExpectedToBeOnline" + }, + "MachineHealthCheckPolicy": { + "BashHealthCheckPolicy": { + "RunType": "InheritFromDefault", + "ScriptBody": "string" + }, + "HealthCheckCron": "string", + "HealthCheckCronTimezone": "string", + "HealthCheckInterval": "string", + "HealthCheckType": "RunScript", + "PowerShellHealthCheckPolicy": { + "RunType": "InheritFromDefault", + "ScriptBody": "string" + } + }, + "MachinePackageCacheRetentionPolicy": { + "PackageUnit": "Items", + "QuantityOfPackagesToKeep": 0, + "QuantityOfVersionsToKeep": 0, + "Strategy": "Default", + "VersionUnit": "Items" + }, + "MachineRpcCallRetryPolicy": { + "Enabled": true, + "HealthCheckRetryDuration": "string", + "RetryDuration": "string" + }, + "MachineUpdatePolicy": { + "CalamariUpdateBehavior": "UpdateOnDeployment", + "KubernetesAgentUpdateBehavior": "NeverUpdate", + "TentacleUpdateAccountId": "string", + "TentacleUpdateBehavior": "NeverUpdate" + }, + "Name": "string", + "PollingRequestQueueTimeout": "string", + "SpaceId": "string" +} +``` +::: + +## Delete the specified Machine Policy + +:endpoint{method="DELETE" path="/api/\{spaceId\}/machinepolicies/\{id\}"} + +Also reachable at `/api/machinepolicies/{id}`, `/api/spaces/{spaceIdentifier}/machinepolicies/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Machine Policy to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Get a paginated list of the machines that belong to the given Machine Policy + +:endpoint{method="GET" path="/api/\{spaceId\}/machinepolicies/\{id\}/machines"} + +Also reachable at `/api/machinepolicies/{id}/machines`, `/api/spaces/{spaceIdentifier}/machinepolicies/{id}/machines`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Machine Policy. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 10. Minimum `0`. + +**Response** + +`200` — A paginated list of the machines that belong to the given Machine Policy + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Architecture`** :span[string]{.type-label} + - **`Endpoint`** :span[object]{.type-label} + - **`EnvironmentIds`** :span[array of string]{.type-label} + - **`HasLatestCalamari`** :span[boolean]{.type-label} + - **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`IsInProcess`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MachinePolicyId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OperatingSystem`** :span[string]{.type-label} + - **`OperatingSystemVersion`** :span[string]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`ShellName`** :span[string]{.type-label} + - **`ShellVersion`** :span[string]{.type-label} + - **`SkipInitialHealthCheck`** :span[boolean]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`StatusSummary`** :span[string]{.type-label} + - **`TenantIds`** :span[array of string]{.type-label} + - **`TenantTags`** :span[array of string]{.type-label} + - **`TenantedDeploymentParticipation`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + - **`Thumbprint`** :span[string]{.type-label} + - **`Uri`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {} + }, + "EnvironmentIds": [ + "string" + ], + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "Roles": [ + "string" + ], + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "TenantIds": [ + "string" + ], + "TenantTags": [ + "string" + ], + "TenantedDeploymentParticipation": "Untenanted", + "Thumbprint": "string", + "Uri": "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 +} +``` +::: + +## Delete the specified Machine Policy + +:endpoint{method="DELETE" path="/api/\{spaceId\}/machinepolicies/\{id\}/v1"} + +Also reachable at `/api/machinepolicies/{id}/v1`, `/api/spaces/{spaceIdentifier}/machinepolicies/{id}/v1`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Machine Policy to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the Machine Policy has been deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get a paginated list of the workers that belong to the given Machine Policy + +:endpoint{method="GET" path="/api/\{spaceId\}/machinepolicies/\{id\}/workers"} + +Also reachable at `/api/machinepolicies/{id}/workers`, `/api/spaces/{spaceIdentifier}/machinepolicies/{id}/workers`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Machine Policy. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 10. Minimum `0`. + +**Response** + +`200` — A paginated list of the machines that belong to the given Machine Policy + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Architecture`** :span[string]{.type-label} + - **`Endpoint`** :span[object]{.type-label} + - **`HasLatestCalamari`** :span[boolean]{.type-label} + - **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`IsInProcess`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MachinePolicyId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OperatingSystem`** :span[string]{.type-label} + - **`OperatingSystemVersion`** :span[string]{.type-label} + - **`ShellName`** :span[string]{.type-label} + - **`ShellVersion`** :span[string]{.type-label} + - **`SkipInitialHealthCheck`** :span[boolean]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`StatusSummary`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Uri`** :span[string]{.type-label} + - **`WorkerPoolIds`** :span[array of string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {} + }, + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "Thumbprint": "string", + "Uri": "string", + "WorkerPoolIds": [ + "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 +} +``` +::: diff --git a/src/pages/docs/api/machine-roles.md b/src/pages/docs/api/machine-roles.md new file mode 100644 index 0000000000..1ce97768d4 --- /dev/null +++ b/src/pages/docs/api/machine-roles.md @@ -0,0 +1,56 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Machine Roles +--- + +## Get all machine roles that have been defined in this Octopus installation + +:endpoint{method="GET" path="/api/\{spaceId\}/machineroles/all"} + +Also reachable at `/api/machineroles/all`, `/api/spaces/{spaceIdentifier}/machineroles/all`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested list of Machine Roles + +:::api-example{label="Response"} +```json +[ + "string" +] +``` +::: + +## Get all machine roles that have been defined in this Octopus installation + +:endpoint{method="GET" path="/api/\{spaceId\}/machineroles/all/v1"} + +Also reachable at `/api/machineroles/all/v1`, `/api/spaces/{spaceIdentifier}/machineroles/all/v1`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested list of Machine Roles + +- **`MachineRoles`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "MachineRoles": [ + "string" + ] +} +``` +::: diff --git a/src/pages/docs/api/machines.md b/src/pages/docs/api/machines.md new file mode 100644 index 0000000000..6a383408cb --- /dev/null +++ b/src/pages/docs/api/machines.md @@ -0,0 +1,74 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Machines +--- + +## Get the status of the network connection between the Octopus server and a machine + +:endpoint{method="GET" path="/api/\{spaceId\}/machines/\{id\}/connection"} + +Also reachable at `/api/machines/{id}/connection`, `/api/spaces/{spaceIdentifier}/machines/{id}/connection`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the machine whose connection status is being requested. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the space. + +**Response** + +`200` — The connection status + +- **`CurrentTentacleVersion`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastChecked`** :span[string]{.type-label} + Format `date-time`. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Logs`** :span[array of object]{.type-label} + - **`Category`** :span[string]{.type-label} + - **`Detail`** :span[string]{.type-label} + - **`GapLastNumber`** :span[integer]{.type-label} + - **`MessageText`** :span[string]{.type-label} + - **`Number`** :span[integer]{.type-label} + - **`OccurredAt`** :span[string]{.type-label} + Format `date-time`. +- **`MachineId`** :span[string]{.type-label} +- **`Status`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CurrentTentacleVersion": "string", + "Id": "string", + "LastChecked": "2020-01-01T00:00:00.000Z", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Logs": [ + { + "Category": "string", + "Detail": "string", + "GapLastNumber": 0, + "MessageText": "string", + "Number": 0, + "OccurredAt": "2020-01-01T00:00:00.000Z" + } + ], + "MachineId": "string", + "Status": "string" +} +``` +::: diff --git a/src/pages/docs/api/maintenance-configuration.md b/src/pages/docs/api/maintenance-configuration.md new file mode 100644 index 0000000000..e628b88f4f --- /dev/null +++ b/src/pages/docs/api/maintenance-configuration.md @@ -0,0 +1,135 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Maintenance Configuration +--- + +## Get information about the maintenance configuration in use by the Octopus Server + +:endpoint{method="GET" path="/api/maintenanceconfiguration"} + +**Response** + +`200` — The requested Maintenance Configuration + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsInMaintenanceMode`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "IsInMaintenanceMode": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +## Update the maintenance configuration used by the Octopus Server + +:endpoint{method="PUT" path="/api/maintenanceconfiguration"} + +**Request Body** + +- **`IsInMaintenanceMode`** :span[boolean]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "IsInMaintenanceMode": true +} +``` +::: + +**Response** + +`200` — Confirmation that the Maintenance Configuration has been modified, containing the updated configuration + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsInMaintenanceMode`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "IsInMaintenanceMode": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +## Update the maintenance configuration used by the Octopus Server + +:endpoint{method="PUT" path="/api/maintenanceconfiguration/v1"} + +**Request Body** + +- **`IsInMaintenanceMode`** :span[boolean]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "IsInMaintenanceMode": true +} +``` +::: + +**Response** + +`200` — Confirmation that the Maintenance Configuration has been modified, containing the updated configuration + +- **`Resource`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsInMaintenanceMode`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + +:::api-example{label="Response"} +```json +{ + "Resource": { + "Id": "string", + "IsInMaintenanceMode": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + } +} +``` +::: diff --git a/src/pages/docs/api/migrations.md b/src/pages/docs/api/migrations.md new file mode 100644 index 0000000000..4d37b2219c --- /dev/null +++ b/src/pages/docs/api/migrations.md @@ -0,0 +1,209 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Migrations +--- + +## Create and queue a migration import task, from an export created via the migration partial-export api + +:endpoint{method="POST" path="/api/migrations/import"} + +The migration API provides the ability to back-up and restore parts of an Octopus Deploy instance remotely Further details can be found in the docs. + +**Request Body** + +- **`DeletePackageOnCompletion`** :span[boolean]{.type-label} +- **`FailureCallbackUri`** :span[string]{.type-label} +- **`IsDryRun`** :span[boolean]{.type-label} +- **`IsEncryptedPackage`** :span[boolean]{.type-label} +- **`OverwriteExisting`** :span[boolean]{.type-label} +- **`PackageFeedSpaceId`** :span[string]{.type-label} +- **`PackageId`** :span[string]{.type-label} *(required)* +- **`PackageVersion`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Password`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`SuccessCallbackUri`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "DeletePackageOnCompletion": true, + "FailureCallbackUri": "string", + "IsDryRun": true, + "IsEncryptedPackage": true, + "OverwriteExisting": true, + "PackageFeedSpaceId": "string", + "PackageId": "string", + "PackageVersion": "string", + "Password": "string", + "SuccessCallbackUri": "string" +} +``` +::: + +**Response** + +`200` — The requested import task that has been queued. + +- **`DeletePackageOnCompletion`** :span[boolean]{.type-label} +- **`FailureCallbackUri`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDryRun`** :span[boolean]{.type-label} +- **`IsEncryptedPackage`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`OverwriteExisting`** :span[boolean]{.type-label} +- **`PackageFeedSpaceId`** :span[string]{.type-label} +- **`PackageId`** :span[string]{.type-label} +- **`PackageVersion`** :span[string]{.type-label} +- **`Password`** :span[string]{.type-label} +- **`SuccessCallbackUri`** :span[string]{.type-label} +- **`TaskId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DeletePackageOnCompletion": true, + "FailureCallbackUri": "string", + "Id": "string", + "IsDryRun": true, + "IsEncryptedPackage": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "OverwriteExisting": true, + "PackageFeedSpaceId": "string", + "PackageId": "string", + "PackageVersion": "string", + "Password": "string", + "SuccessCallbackUri": "string", + "TaskId": "string" +} +``` +::: + +## Create and queue a partial-export migration task + +:endpoint{method="POST" path="/api/migrations/partialexport"} + +The migration API provides the ability to back-up and restore parts of an Octopus Deploy instance remotely Further details can be found in the docs. + +**Request Body** + +- **`DestinationApiKey`** :span[string]{.type-label} +- **`DestinationPackageFeed`** :span[string]{.type-label} +- **`DestinationPackageFeedSpaceId`** :span[string]{.type-label} +- **`EncryptPackage`** :span[boolean]{.type-label} +- **`FailureCallbackUri`** :span[string]{.type-label} +- **`IgnoreCertificates`** :span[boolean]{.type-label} +- **`IgnoreDeployments`** :span[boolean]{.type-label} +- **`IgnoreMachines`** :span[boolean]{.type-label} +- **`IgnoreTenants`** :span[boolean]{.type-label} +- **`IncludeTaskLogs`** :span[boolean]{.type-label} +- **`PackageId`** :span[string]{.type-label} +- **`PackageVersion`** :span[string]{.type-label} +- **`Password`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Projects`** :span[array of string]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} +- **`SuccessCallbackUri`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "DestinationApiKey": "string", + "DestinationPackageFeed": "string", + "DestinationPackageFeedSpaceId": "string", + "EncryptPackage": true, + "FailureCallbackUri": "string", + "IgnoreCertificates": true, + "IgnoreDeployments": true, + "IgnoreMachines": true, + "IgnoreTenants": true, + "IncludeTaskLogs": true, + "PackageId": "string", + "PackageVersion": "string", + "Password": "string", + "Projects": [ + "string" + ], + "SpaceId": "string", + "SuccessCallbackUri": "string" +} +``` +::: + +**Response** + +`200` — The requested partial export task that has been queued. + +- **`DestinationApiKey`** :span[string]{.type-label} +- **`DestinationPackageFeed`** :span[string]{.type-label} +- **`DestinationPackageFeedSpaceId`** :span[string]{.type-label} +- **`EncryptPackage`** :span[boolean]{.type-label} +- **`FailureCallbackUri`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IgnoreCertificates`** :span[boolean]{.type-label} +- **`IgnoreDeployments`** :span[boolean]{.type-label} +- **`IgnoreMachines`** :span[boolean]{.type-label} +- **`IgnoreTenants`** :span[boolean]{.type-label} +- **`IncludeTaskLogs`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`PackageId`** :span[string]{.type-label} +- **`PackageVersion`** :span[string]{.type-label} +- **`Password`** :span[string]{.type-label} +- **`Projects`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SuccessCallbackUri`** :span[string]{.type-label} +- **`TaskId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DestinationApiKey": "string", + "DestinationPackageFeed": "string", + "DestinationPackageFeedSpaceId": "string", + "EncryptPackage": true, + "FailureCallbackUri": "string", + "Id": "string", + "IgnoreCertificates": true, + "IgnoreDeployments": true, + "IgnoreMachines": true, + "IgnoreTenants": true, + "IncludeTaskLogs": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PackageId": "string", + "PackageVersion": "string", + "Password": "string", + "Projects": [ + "string" + ], + "SpaceId": "string", + "SuccessCallbackUri": "string", + "TaskId": "string" +} +``` +::: diff --git a/src/pages/docs/api/nuget.md b/src/pages/docs/api/nuget.md new file mode 100644 index 0000000000..0c8e4bc8c8 --- /dev/null +++ b/src/pages/docs/api/nuget.md @@ -0,0 +1,135 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Nuget +--- + +## Push packages to this endpoint using NuGet.exe or compatible tools + +:endpoint{method="PUT" path="/api/\{spaceId\}/nuget/packages"} + +Also reachable at `/api/nuget/packages`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — PackageFromBuiltInFeedResource returned + +- **`Description`** :span[string]{.type-label} +- **`FeedId`** :span[string]{.type-label} +- **`FileExtension`** :span[string]{.type-label} +- **`Hash`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NuGetFeedId`** :span[string]{.type-label} +- **`NuGetPackageId`** :span[string]{.type-label} +- **`PackageId`** :span[string]{.type-label} +- **`PackageSizeBytes`** :span[integer]{.type-label} +- **`PackageVersionBuildInformation`** :span[object]{.type-label} + - **`Branch`** :span[string]{.type-label} + - **`BuildEnvironment`** :span[string]{.type-label} + - **`BuildNumber`** :span[string]{.type-label} + - **`BuildUrl`** :span[string]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IncompleteDataWarning`** :span[string]{.type-label} + - **`IssueTrackerName`** :span[string]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`PackageId`** :span[string]{.type-label} + - **`VcsCommitNumber`** :span[string]{.type-label} + - **`VcsCommitUrl`** :span[string]{.type-label} + - **`VcsRoot`** :span[string]{.type-label} + - **`VcsType`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} +- **`Published`** :span[string]{.type-label} + Format `date-time`. +- **`ReleaseNotes`** :span[string]{.type-label} +- **`Summary`** :span[string]{.type-label} +- **`Title`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "FeedId": "string", + "FileExtension": "string", + "Hash": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NuGetFeedId": "string", + "NuGetPackageId": "string", + "PackageId": "string", + "PackageSizeBytes": 0, + "PackageVersionBuildInformation": { + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + { + "Comment": "string", + "Id": "string", + "LinkUrl": "string" + } + ], + "Created": "2020-01-01T00:00:00.000Z", + "Id": "string", + "IncompleteDataWarning": "string", + "IssueTrackerName": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + { + "Description": "string", + "Id": "string", + "LinkUrl": "string", + "Source": "string" + } + ] + }, + "Published": "2020-01-01T00:00:00.000Z", + "ReleaseNotes": "string", + "Summary": "string", + "Title": "string", + "Version": "string" +} +``` +::: diff --git a/src/pages/docs/api/observability.md b/src/pages/docs/api/observability.md new file mode 100644 index 0000000000..2227201133 --- /dev/null +++ b/src/pages/docs/api/observability.md @@ -0,0 +1,562 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Observability +--- + +## Register and trusts new Kubernetes Monitor + +:endpoint{method="POST" path="/api/\{spaceId\}/observability/agents"} + +Also reachable at `/api/spaces/{spaceIdentifier}/observability/agents`, `/api/spaces/{spaceIdentifier}/observability/kubernetes-monitors`, `/api/{spaceId}/observability/kubernetes-monitors`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`InstallationId`** :span[string]{.type-label} *(required)* + Installation ID of that uniquely identifies the physical installation of the agent. Format `uuid`. +- **`MachineId`** :span[string]{.type-label} *(required)* + Machine ID of that uniquely identifies the deployment target or worker that is being observed. +- **`PreserveAuthenticationToken`** :span[boolean]{.type-label} + Controls whether the authentication token should be preserved during re-registration. If not supplied (null), the token will be regenerated (default behavior). If false, the token will be regenerated. If true, the existing token will be preserved. +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "InstallationId": "00000000-0000-0000-0000-000000000000", + "MachineId": "string", + "PreserveAuthenticationToken": true, + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Response containing the registered agent. + +- **`AuthenticationToken`** :span[string]{.type-label} + Authentication token for the monitor. Will be null if PreserveAuthenticationToken was set to true in the request and not registering a new monitor. +- **`CertificateThumbprint`** :span[string]{.type-label} + Minimum length 1. +- **`Resource`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`InstallationId`** :span[string]{.type-label} + Format `uuid`. + - **`MachineId`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AuthenticationToken": "string", + "CertificateThumbprint": "string", + "Resource": { + "Id": "string", + "InstallationId": "00000000-0000-0000-0000-000000000000", + "MachineId": "string", + "SpaceId": "string" + } +} +``` +::: + +## Request the Kubernetes monitor to start sending events for the specified resource + +:endpoint{method="POST" path="/api/\{spaceId\}/observability/events/sessions"} + +Also reachable at `/api/spaces/{spaceIdentifier}/observability/events/sessions`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`DesiredOrKubernetesMonitoredResourceId`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`EnvironmentId`** :span[string]{.type-label} *(required)* +- **`MachineId`** :span[string]{.type-label} *(required)* +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantId`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "DesiredOrKubernetesMonitoredResourceId": "string", + "EnvironmentId": "string", + "MachineId": "string", + "ProjectId": "string", + "SpaceId": "string", + "TenantId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation response containing a session ID for the event session + +- **`SessionId`** :span[string]{.type-label} + Format `uuid`. + +:::api-example{label="Response"} +```json +{ + "SessionId": "00000000-0000-0000-0000-000000000000" +} +``` +::: + +## Request to fetch all the events for the specified session + +:endpoint{method="GET" path="/api/\{spaceId\}/observability/events/sessions/\{sessionId\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/observability/events/sessions/{sessionId}`. + +**Path Parameters** + +- **`sessionId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Response containing the events for a sessionID + +- **`Error`** :span[object]{.type-label} + - **`ErrorCode`** :span[string]{.type-label} + Minimum length 1. + - **`ErrorMessage`** :span[string]{.type-label} + Minimum length 1. +- **`Events`** :span[array of object]{.type-label} + - **`Action`** :span[string]{.type-label} + - **`Count`** :span[integer]{.type-label} + - **`FirstObservedTime`** :span[string]{.type-label} + - **`LastObservedTime`** :span[string]{.type-label} + - **`Manifest`** :span[string]{.type-label} + - **`Note`** :span[string]{.type-label} + - **`Reason`** :span[string]{.type-label} + - **`ReportingController`** :span[string]{.type-label} + - **`ReportingInstance`** :span[string]{.type-label} + - **`Type`** :span[string]{.type-label} +- **`IsSessionCompleted`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Error": { + "ErrorCode": "string", + "ErrorMessage": "string" + }, + "Events": [ + { + "Action": "string", + "Count": 0, + "FirstObservedTime": "string", + "LastObservedTime": "string", + "Manifest": "string", + "Note": "string", + "Reason": "string", + "ReportingController": "string", + "ReportingInstance": "string", + "Type": "string" + } + ], + "IsSessionCompleted": true +} +``` +::: + +## Get a Kubernetes Monitor by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/observability/kubernetes-monitors/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/observability/kubernetes-monitors/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Kubernetes Monitor. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Kubernetes Monitor + +- **`Resource`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`InstallationId`** :span[string]{.type-label} + Format `uuid`. + - **`MachineId`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Resource": { + "Id": "string", + "InstallationId": "00000000-0000-0000-0000-000000000000", + "MachineId": "string", + "SpaceId": "string" + } +} +``` +::: + +## Delete a Kubernetes Monitor by ID + +:endpoint{method="DELETE" path="/api/\{spaceId\}/observability/kubernetes-monitors/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/observability/kubernetes-monitors/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Kubernetes Monitor. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Response for deleting a Kubernetes Monitor + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Request the Kubernetes monitor to start sending logs for the specified container + +:endpoint{method="POST" path="/api/\{spaceId\}/observability/logs/sessions"} + +Also reachable at `/api/spaces/{spaceIdentifier}/observability/logs/sessions`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ContainerName`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`DesiredOrKubernetesMonitoredResourceId`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`EnvironmentId`** :span[string]{.type-label} *(required)* +- **`MachineId`** :span[string]{.type-label} *(required)* +- **`PodName`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`ShowPreviousContainer`** :span[boolean]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantId`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "ContainerName": "string", + "DesiredOrKubernetesMonitoredResourceId": "string", + "EnvironmentId": "string", + "MachineId": "string", + "PodName": "string", + "ProjectId": "string", + "ShowPreviousContainer": true, + "SpaceId": "string", + "TenantId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation response containing any errors that might have occurred during communications with the Kubernetes Monitor + +- **`SessionId`** :span[string]{.type-label} + Format `uuid`. + +:::api-example{label="Response"} +```json +{ + "SessionId": "00000000-0000-0000-0000-000000000000" +} +``` +::: + +## Request to fetch all the logs for the specified session + +:endpoint{method="GET" path="/api/\{spaceId\}/observability/logs/sessions/\{sessionId\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/observability/logs/sessions/{sessionId}`. + +**Path Parameters** + +- **`sessionId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Response containing the logs for a sessionID + +- **`Error`** :span[object]{.type-label} + - **`ErrorCode`** :span[string]{.type-label} + Minimum length 1. + - **`ErrorMessage`** :span[string]{.type-label} + Minimum length 1. +- **`IsSessionCompleted`** :span[boolean]{.type-label} +- **`Logs`** :span[array of object]{.type-label} + - **`Message`** :span[string]{.type-label} + - **`Timestamp`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Error": { + "ErrorCode": "string", + "ErrorMessage": "string" + }, + "IsSessionCompleted": true, + "Logs": [ + { + "Message": "string", + "Timestamp": "string" + } + ] +} +``` +::: + +## Request the live status for a Project/Environment/Tenant + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/environments/\{environmentId\}/tenants/\{tenantId\}/livestatus"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/{environmentId}/tenants/{tenantId}/livestatus`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/{environmentId}/untenanted/livestatus`, `/api/{spaceId}/projects/{projectId}/environments/{environmentId}/untenanted/livestatus`. + +**Path Parameters** + +- **`environmentId`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* +- **`tenantId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`summaryOnly`** :span[boolean]{.type-label} + +**Response** + +`200` — Live status for a given Project/Environment/Tenant + +- **`MachineStatuses`** :span[array of object]{.type-label} + - **`MachineId`** :span[string]{.type-label} + - **`Resources`** :span[array of object]{.type-label} + - **`Status`** :span[string]{.type-label} + Minimum length 1. +- **`Summary`** :span[object]{.type-label} + - **`HealthStatus`** :span[string]{.type-label} + Minimum length 1. + - **`LastUpdated`** :span[string]{.type-label} + - **`Status`** :span[string]{.type-label} + Minimum length 1. + - **`SyncStatus`** :span[string]{.type-label} + Minimum length 1. + - **`SyncStatusMessage`** :span[string]{.type-label} + - **`TotalOrphanCount`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "MachineStatuses": [ + { + "MachineId": "string", + "Resources": [ + {} + ], + "Status": "string" + } + ], + "Summary": { + "HealthStatus": "string", + "LastUpdated": "string", + "Status": "string", + "SyncStatus": "string", + "SyncStatusMessage": "string", + "TotalOrphanCount": 0 + } +} +``` +::: + +## Get a detailed summary of a live Kubernetes resource - either a top-level resource or a child resource + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/environments/\{environmentId\}/tenants/\{tenantId\}/machines/\{sourceId\}/resources/\{desiredOrKubernetesMonitoredResourceId\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/{environmentId}/tenants/{tenantId}/machines/{sourceId}/resources/{desiredOrKubernetesMonitoredResourceId}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/{environmentId}/untenanted/machines/{sourceId}/resources/{desiredOrKubernetesMonitoredResourceId}`, `/api/{spaceId}/projects/{projectId}/environments/{environmentId}/untenanted/machines/{sourceId}/resources/{desiredOrKubernetesMonitoredResourceId}`. + +**Path Parameters** + +- **`desiredOrKubernetesMonitoredResourceId`** :span[string]{.type-label} *(required)* +- **`environmentId`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`sourceId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* +- **`tenantId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Response containing detailed summary of a live kubernetes resource - Either a top level resource or a child resource + +- **`Resource`** :span[object]{.type-label} + - **`Children`** :span[array of object]{.type-label} + - **`DesiredResourceId`** :span[string]{.type-label} + Format `uuid`. + - **`ExternalLink`** :span[object]{.type-label} + - **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Stale`. + - **`HealthStatusMessage`** :span[string]{.type-label} + - **`Kind`** :span[string]{.type-label} + Minimum length 1. + - **`LastUpdated`** :span[string]{.type-label} + - **`ManifestSummary`** :span[object]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Namespace`** :span[string]{.type-label} + - **`ResourceId`** :span[string]{.type-label} + Format `uuid`. + - **`ResourceSourceId`** :span[string]{.type-label} + - **`SourceType`** :span[enum]{.type-label} + Allowed values: `KubernetesMonitor`, `ArgoCDInstance`, `ArgoCDApplication`. + - **`SyncStatus`** :span[string]{.type-label} + - **`SyncStatusMessage`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Resource": { + "Children": [], + "DesiredResourceId": "00000000-0000-0000-0000-000000000000", + "ExternalLink": { + "Label": "string", + "Uri": "string" + }, + "HealthStatus": "Stale", + "HealthStatusMessage": "string", + "Kind": "string", + "LastUpdated": "string", + "ManifestSummary": { + "Annotations": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "CreationTimestamp": "2020-01-01T00:00:00.000Z", + "Kind": "string", + "Labels": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Name": "string", + "Namespace": "string", + "ResourceId": "00000000-0000-0000-0000-000000000000", + "ResourceSourceId": "string", + "SourceType": "KubernetesMonitor", + "SyncStatus": "string", + "SyncStatusMessage": "string" + } +} +``` +::: + +## Request for retrieving the manifest for a live kubernetes resource + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/environments/\{environmentId\}/tenants/\{tenantId\}/machines/\{sourceId\}/resources/\{desiredOrKubernetesMonitoredResourceId\}/manifest"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/{environmentId}/tenants/{tenantId}/machines/{sourceId}/resources/{desiredOrKubernetesMonitoredResourceId}/manifest`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/{environmentId}/untenanted/machines/{sourceId}/resources/{desiredOrKubernetesMonitoredResourceId}/manifest`, `/api/{spaceId}/projects/{projectId}/environments/{environmentId}/untenanted/machines/{sourceId}/resources/{desiredOrKubernetesMonitoredResourceId}/manifest`. + +**Path Parameters** + +- **`desiredOrKubernetesMonitoredResourceId`** :span[string]{.type-label} *(required)* +- **`environmentId`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`sourceId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* +- **`tenantId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Contains the manifest for a live resource + +- **`DesiredManifest`** :span[string]{.type-label} +- **`Diff`** :span[object]{.type-label} + - **`Diff`** :span[string]{.type-label} + Minimum length 1. + - **`Left`** :span[string]{.type-label} + Minimum length 1. + - **`Right`** :span[string]{.type-label} + Minimum length 1. +- **`LiveManifest`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "DesiredManifest": "string", + "Diff": { + "Diff": "string", + "Left": "string", + "Right": "string" + }, + "LiveManifest": "string" +} +``` +::: + +## Request for retrieving the manifest for a live kubernetes resource + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/environments/\{environmentId\}/tenants/\{tenantId\}/machines/\{sourceId\}/resources/\{desiredOrKubernetesMonitoredResourceId\}/manifest/v2"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/{environmentId}/tenants/{tenantId}/machines/{sourceId}/resources/{desiredOrKubernetesMonitoredResourceId}/manifest/v2`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/environments/{environmentId}/untenanted/machines/{sourceId}/resources/{desiredOrKubernetesMonitoredResourceId}/manifest/v2`, `/api/{spaceId}/projects/{projectId}/environments/{environmentId}/untenanted/machines/{sourceId}/resources/{desiredOrKubernetesMonitoredResourceId}/manifest/v2`. + +**Path Parameters** + +- **`desiredOrKubernetesMonitoredResourceId`** :span[string]{.type-label} *(required)* +- **`environmentId`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`sourceId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* +- **`tenantId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Contains the manifest for a live resource + +- **`DesiredManifest`** :span[string]{.type-label} +- **`Diff`** :span[object]{.type-label} + - **`Diff`** :span[string]{.type-label} + Minimum length 1. + - **`Left`** :span[string]{.type-label} + Minimum length 1. + - **`Right`** :span[string]{.type-label} + Minimum length 1. +- **`LiveManifest`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DesiredManifest": "string", + "Diff": { + "Diff": "string", + "Left": "string", + "Right": "string" + }, + "LiveManifest": "string" +} +``` +::: diff --git a/src/pages/docs/api/octopus-server-nodes.md b/src/pages/docs/api/octopus-server-nodes.md new file mode 100644 index 0000000000..fa107f6f22 --- /dev/null +++ b/src/pages/docs/api/octopus-server-nodes.md @@ -0,0 +1,408 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Octopus Server Nodes +--- + +## Get a list of Octopus Server Nodes + +:endpoint{method="GET" path="/api/octopusservernodes"} + +Lists all of the Octopus Server Nodes participating in the current Octopus Server cluster. + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + List of IDs. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested list of Octopus Server Nodes + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsInMaintenanceMode`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MaxConcurrentTasks`** :span[integer]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Id": "string", + "IsInMaintenanceMode": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MaxConcurrentTasks": 0, + "Name": "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 +} +``` +::: + +## Get all Octopus Server Nodes + +:endpoint{method="GET" path="/api/octopusservernodes/all"} + +Lists the name and ID of all Octopus Server nodes + +**Response** + +`200` — The requested list of Octopus Server Nodes + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsInMaintenanceMode`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MaxConcurrentTasks`** :span[integer]{.type-label} +- **`Name`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Id": "string", + "IsInMaintenanceMode": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MaxConcurrentTasks": 0, + "Name": "string" + } +] +``` +::: + +## Ping an octopus server node + +:endpoint{method="GET" path="/api/octopusservernodes/ping"} + +Returns HTTP ImATeapot (418) when the Octopus Server node is draining or offline, otherwise HTTP OK (200). Always returns the node information in the body. + +**Response** + +`200` — Contains information about the octopus server node + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsInMaintenanceMode`** :span[boolean]{.type-label} +- **`IsOffline`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSeen`** :span[string]{.type-label} + Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MaxConcurrentTasks`** :span[integer]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "IsInMaintenanceMode": true, + "IsOffline": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSeen": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MaxConcurrentTasks": 0, + "Name": "string", + "Version": "string" +} +``` +::: + +**Error Responses** + +- **`418`** — Indicates that the node is draining or offline + +## Return all octopus server nodes in the cluster including their status information + +:endpoint{method="GET" path="/api/octopusservernodes/summary"} + +**Response** + +`200` — The Octopus Server Nodes Summary + +- **`Links`** :span[object]{.type-label} +- **`Nodes`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsInMaintenanceMode`** :span[boolean]{.type-label} + - **`IsOffline`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastSeen`** :span[string]{.type-label} + Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MaxConcurrentTasks`** :span[integer]{.type-label} + - **`MaxSqlConnectionPoolSize`** :span[integer]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RecommendedMaxSqlConnectionPoolSize`** :span[integer]{.type-label} + - **`RunningTaskCount`** :span[integer]{.type-label} + - **`Version`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Nodes": [ + { + "Id": "string", + "IsInMaintenanceMode": true, + "IsOffline": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSeen": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MaxConcurrentTasks": 0, + "MaxSqlConnectionPoolSize": 0, + "Name": "string", + "RecommendedMaxSqlConnectionPoolSize": 0, + "RunningTaskCount": 0, + "Version": "string" + } + ] +} +``` +::: + +## Get an Octopus Server Node by ID + +:endpoint{method="GET" path="/api/octopusservernodes/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the OctopusServerNode to load. + +**Response** + +`200` — The requested Octopus Server Node + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsInMaintenanceMode`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MaxConcurrentTasks`** :span[integer]{.type-label} +- **`Name`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "IsInMaintenanceMode": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MaxConcurrentTasks": 0, + "Name": "string" +} +``` +::: + +## Modify an existing OctopusServerNodeResource by ID + +:endpoint{method="PUT" path="/api/octopusservernodes/\{id\}"} + +Modifies an existing Octopus Server node. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the OctopusServerNodeResource to modify. + +**Request Body** + +- **`Id`** :span[string]{.type-label} *(required)* + ID of the OctopusServerNodeResource to modify. +- **`IsInMaintenanceMode`** :span[boolean]{.type-label} + The updated maintenance mode of the OctopusServerNodeResource to modify. +- **`MaxConcurrentTasks`** :span[integer]{.type-label} + The updated max concurrent tasks value of the OctopusServerNodeResource to modify. + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "IsInMaintenanceMode": true, + "MaxConcurrentTasks": 0 +} +``` +::: + +**Response** + +`200` — Confirmation that the Octopus Server Node was modified, containing the new Node + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsInMaintenanceMode`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MaxConcurrentTasks`** :span[integer]{.type-label} +- **`Name`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "IsInMaintenanceMode": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MaxConcurrentTasks": 0, + "Name": "string" +} +``` +::: + +## Delete an existing Octopus Server Node + +:endpoint{method="DELETE" path="/api/octopusservernodes/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Octopus Server Node to delete. + +**Response** + +`200` — Confirmation that the Octopus Server Node was deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Return a count of the running tasks on an octopus server node + +:endpoint{method="GET" path="/api/octopusservernodes/\{id\}/details"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the OctopusServerNode to load details. + +**Response** + +`200` — Details about the requested Octopus Server Node + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`RunningTasks`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "RunningTasks": 0 +} +``` +::: diff --git a/src/pages/docs/api/open-id-connect.md b/src/pages/docs/api/open-id-connect.md new file mode 100644 index 0000000000..9db8c40663 --- /dev/null +++ b/src/pages/docs/api/open-id-connect.md @@ -0,0 +1,171 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Open ID Connect +--- + +## Get OpenID Connect configuration + +:endpoint{method="GET" path="/api/.well-known/openid-configuration"} + +**Response** + +`200` — OpenID Configuration response + +- **`claims_supported`** :span[array of string]{.type-label} +- **`id_token_signing_alg_values_supported`** :span[array of string]{.type-label} +- **`issuer`** :span[string]{.type-label} + Minimum length 1. +- **`jwks_uri`** :span[string]{.type-label} + Minimum length 1. +- **`response_types_supported`** :span[array of string]{.type-label} +- **`scopes_supported`** :span[array of string]{.type-label} +- **`subject_types_supported`** :span[array of string]{.type-label} +- **`token_endpoint`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "claims_supported": [ + "string" + ], + "id_token_signing_alg_values_supported": [ + "string" + ], + "issuer": "string", + "jwks_uri": "string", + "response_types_supported": [ + "string" + ], + "scopes_supported": [ + "string" + ], + "subject_types_supported": [ + "string" + ], + "token_endpoint": "string" +} +``` +::: + +## POST /api/users/authenticate/AzureAD + +:endpoint{method="POST" path="/api/users/authenticate/AzureAD"} + +**Response** + +`200` — OK + +## POST /api/users/authenticate/GenericOidc + +:endpoint{method="POST" path="/api/users/authenticate/GenericOidc"} + +**Response** + +`200` — OK + +## POST /api/users/authenticate/GoogleApps + +:endpoint{method="POST" path="/api/users/authenticate/GoogleApps"} + +**Response** + +`200` — OK + +## POST /api/users/authenticate/OctopusID + +:endpoint{method="POST" path="/api/users/authenticate/OctopusID"} + +**Response** + +`200` — OK + +## POST /api/users/authenticate/Okta + +:endpoint{method="POST" path="/api/users/authenticate/Okta"} + +**Response** + +`200` — OK + +## GET /api/users/authenticatedToken/AzureAD + +:endpoint{method="GET" path="/api/users/authenticatedToken/AzureAD"} + +**Response** + +`200` — OK + +## POST /api/users/authenticatedToken/AzureAD + +:endpoint{method="POST" path="/api/users/authenticatedToken/AzureAD"} + +**Response** + +`200` — OK + +## GET /api/users/authenticatedToken/GenericOidc + +:endpoint{method="GET" path="/api/users/authenticatedToken/GenericOidc"} + +**Response** + +`200` — OK + +## POST /api/users/authenticatedToken/GenericOidc + +:endpoint{method="POST" path="/api/users/authenticatedToken/GenericOidc"} + +**Response** + +`200` — OK + +## GET /api/users/authenticatedToken/GoogleApps + +:endpoint{method="GET" path="/api/users/authenticatedToken/GoogleApps"} + +**Response** + +`200` — OK + +## POST /api/users/authenticatedToken/GoogleApps + +:endpoint{method="POST" path="/api/users/authenticatedToken/GoogleApps"} + +**Response** + +`200` — OK + +## GET /api/users/authenticatedToken/OctopusID + +:endpoint{method="GET" path="/api/users/authenticatedToken/OctopusID"} + +**Response** + +`200` — OK + +## POST /api/users/authenticatedToken/OctopusID + +:endpoint{method="POST" path="/api/users/authenticatedToken/OctopusID"} + +**Response** + +`200` — OK + +## GET /api/users/authenticatedToken/Okta + +:endpoint{method="GET" path="/api/users/authenticatedToken/Okta"} + +**Response** + +`200` — OK + +## POST /api/users/authenticatedToken/Okta + +:endpoint{method="POST" path="/api/users/authenticatedToken/Okta"} + +**Response** + +`200` — OK diff --git a/src/pages/docs/api/open-telemetry.md b/src/pages/docs/api/open-telemetry.md new file mode 100644 index 0000000000..6bc3f84e79 --- /dev/null +++ b/src/pages/docs/api/open-telemetry.md @@ -0,0 +1,66 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Open Telemetry +--- + +## Request the open telemetry trace file exporter config + +:endpoint{method="GET" path="/api/configuration/open-telemetry-trace-file-export"} + +**Response** + +`200` — The requested OpenTelemetry trace file export configuration. + +- **`Enabled`** :span[boolean]{.type-label} +- **`MaxStorageSizeMegabytes`** :span[integer]{.type-label} +- **`RetentionDays`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Enabled": true, + "MaxStorageSizeMegabytes": 0, + "RetentionDays": 0 +} +``` +::: + +## Modify OpenTelemetry trace file export configuration + +:endpoint{method="PUT" path="/api/configuration/open-telemetry-trace-file-export"} + +**Request Body** + +- **`Enabled`** :span[boolean]{.type-label} *(required)* +- **`MaxStorageSizeMegabytes`** :span[integer]{.type-label} *(required)* +- **`RetentionDays`** :span[integer]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Enabled": true, + "MaxStorageSizeMegabytes": 0, + "RetentionDays": 0 +} +``` +::: + +**Response** + +`200` — The configuration response for modifying OpenTelemetry trace file export configuration + +- **`Enabled`** :span[boolean]{.type-label} +- **`MaxStorageSizeMegabytes`** :span[integer]{.type-label} +- **`RetentionDays`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Enabled": true, + "MaxStorageSizeMegabytes": 0, + "RetentionDays": 0 +} +``` +::: diff --git a/src/pages/docs/api/packages.md b/src/pages/docs/api/packages.md new file mode 100644 index 0000000000..7e1f77e989 --- /dev/null +++ b/src/pages/docs/api/packages.md @@ -0,0 +1,961 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Packages +--- + +## List packages according to specified search criteria + +:endpoint{method="GET" path="/api/\{spaceId\}/feeds/\{feedId\}/packages"} + +Also reachable at `/api/feeds/{feedId}/packages`, `/api/spaces/{spaceIdentifier}/feeds/{feedId}/packages`. + +**Path Parameters** + +- **`feedId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`descriptionsOptional`** :span[boolean]{.type-label} +- **`includeMultipleVersions`** :span[boolean]{.type-label} +- **`includeNotes`** :span[boolean]{.type-label} +- **`includePreRelease`** :span[boolean]{.type-label} +- **`includeWorkItems`** :span[boolean]{.type-label} +- **`packageId`** :span[string]{.type-label} +- **`packageIds`** :span[array of string]{.type-label} +- **`partialMatch`** :span[boolean]{.type-label} +- **`preReleaseTag`** :span[string]{.type-label} +- **`take`** :span[integer]{.type-label} +- **`versionRange`** :span[string]{.type-label} +- **`versionTagRegex`** :span[string]{.type-label} + Applied to the full version string when set. +- **`versioningStrategy`** :span[string]{.type-label} + SemVer or MostRecentlyPublished. + +**Response** + +`200` — The requested Packages + +- **`Description`** :span[string]{.type-label} +- **`FeedId`** :span[string]{.type-label} +- **`FileExtension`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NuGetFeedId`** :span[string]{.type-label} +- **`NuGetPackageId`** :span[string]{.type-label} +- **`PackageId`** :span[string]{.type-label} +- **`PackageVersionBuildInformation`** :span[object]{.type-label} + - **`Branch`** :span[string]{.type-label} + - **`BuildEnvironment`** :span[string]{.type-label} + - **`BuildNumber`** :span[string]{.type-label} + - **`BuildUrl`** :span[string]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IncompleteDataWarning`** :span[string]{.type-label} + - **`IssueTrackerName`** :span[string]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`PackageId`** :span[string]{.type-label} + - **`VcsCommitNumber`** :span[string]{.type-label} + - **`VcsCommitUrl`** :span[string]{.type-label} + - **`VcsRoot`** :span[string]{.type-label} + - **`VcsType`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} +- **`Published`** :span[string]{.type-label} + Format `date-time`. +- **`ReleaseNotes`** :span[string]{.type-label} +- **`Summary`** :span[string]{.type-label} +- **`Title`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Description": "string", + "FeedId": "string", + "FileExtension": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NuGetFeedId": "string", + "NuGetPackageId": "string", + "PackageId": "string", + "PackageVersionBuildInformation": { + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + {} + ], + "Created": "2020-01-01T00:00:00.000Z", + "Id": "string", + "IncompleteDataWarning": "string", + "IssueTrackerName": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + {} + ] + }, + "Published": "2020-01-01T00:00:00.000Z", + "ReleaseNotes": "string", + "Summary": "string", + "Title": "string", + "Version": "string" + } +] +``` +::: + +## Get the release notes for the specified package + +:endpoint{method="GET" path="/api/\{spaceId\}/feeds/\{feedId\}/packages/notes"} + +Also reachable at `/api/feeds/{feedId}/packages/notes`, `/api/spaces/{spaceIdentifier}/feeds/{feedId}/packages/notes`. + +**Path Parameters** + +- **`feedId`** :span[string]{.type-label} *(required)* + ID of the Feed. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`packageId`** :span[string]{.type-label} *(required)* + ID of the package. +- **`version`** :span[string]{.type-label} *(required)* + Version of the package. + +**Response** + +`200` — The requested Package Notes + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Get the built in packages + +:endpoint{method="GET" path="/api/\{spaceId\}/packages"} + +Also reachable at `/api/packages`, `/api/spaces/{spaceIdentifier}/packages`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`filter`** :span[string]{.type-label} + Only return the latest versions of packages which contain this value, if specified. +- **`includeNotes`** :span[boolean]{.type-label} + Include release notes in the response. +- **`includeWorkItems`** :span[boolean]{.type-label} +- **`latest`** :span[boolean]{.type-label} + Indicates whether or not to only return the latest version of any packages found. +- **`nuGetPackageId`** :span[string]{.type-label} + Return versions of the NuGet package with this id, if specified. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested list of Built-in Packages + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`FeedId`** :span[string]{.type-label} + - **`FileExtension`** :span[string]{.type-label} + - **`Hash`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`NuGetFeedId`** :span[string]{.type-label} + - **`NuGetPackageId`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`PackageSizeBytes`** :span[integer]{.type-label} + - **`PackageVersionBuildInformation`** :span[object]{.type-label} + - **`Published`** :span[string]{.type-label} + Format `date-time`. + - **`ReleaseNotes`** :span[string]{.type-label} + - **`Summary`** :span[string]{.type-label} + - **`Title`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Description": "string", + "FeedId": "string", + "FileExtension": "string", + "Hash": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NuGetFeedId": "string", + "NuGetPackageId": "string", + "PackageId": "string", + "PackageSizeBytes": 0, + "PackageVersionBuildInformation": { + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + {} + ], + "Created": "2020-01-01T00:00:00.000Z", + "Id": "string", + "IncompleteDataWarning": "string", + "IssueTrackerName": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {}, + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + {} + ] + }, + "Published": "2020-01-01T00:00:00.000Z", + "ReleaseNotes": "string", + "Summary": "string", + "Title": "string", + "Version": "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 +} +``` +::: + +## Bulk delete Packages + +:endpoint{method="DELETE" path="/api/\{spaceId\}/packages/bulk"} + +Also reachable at `/api/packages/bulk`, `/api/spaces/{spaceIdentifier}/packages/bulk`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Ids`** :span[array of string]{.type-label} *(required)* + Ids of the Packages to delete. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Ids": [ + "string" + ], + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Success + +## Bulk delete Packages + +:endpoint{method="DELETE" path="/api/\{spaceId\}/packages/bulk/v1"} + +Also reachable at `/api/packages/bulk/v1`, `/api/spaces/{spaceIdentifier}/packages/bulk/v1`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Ids`** :span[array of string]{.type-label} *(required)* + Ids of the Packages to delete. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Ids": [ + "string" + ], + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Packages were deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Request a list of Release Notes for the specified Packages + +:endpoint{method="GET" path="/api/\{spaceId\}/packages/notes"} + +Also reachable at `/api/packages/notes`, `/api/spaces/{spaceIdentifier}/packages/notes`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`packageIds`** :span[array of string]{.type-label} + List of package IDs. + +**Response** + +`200` — The requested list of Notes + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Packages`** :span[array of object]{.type-label} + - **`FeedId`** :span[string]{.type-label} + - **`Notes`** :span[object]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Packages": [ + { + "FeedId": "string", + "Notes": { + "DisplayMessage": "string", + "FailureReason": "string", + "Notes": "string", + "Published": "2020-01-01T00:00:00.000Z", + "Succeeded": true + }, + "PackageId": "string", + "Version": "string" + } + ] +} +``` +::: + +## Upload a package to the built in package feed + +:endpoint{method="POST" path="/api/\{spaceId\}/packages/raw"} + +Also reachable at `/api/packages/raw`, `/api/spaces/{spaceIdentifier}/packages/raw`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — PackageFromBuiltInFeedResource returned + +- **`Description`** :span[string]{.type-label} +- **`FeedId`** :span[string]{.type-label} +- **`FileExtension`** :span[string]{.type-label} +- **`Hash`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NuGetFeedId`** :span[string]{.type-label} +- **`NuGetPackageId`** :span[string]{.type-label} +- **`PackageId`** :span[string]{.type-label} +- **`PackageSizeBytes`** :span[integer]{.type-label} +- **`PackageVersionBuildInformation`** :span[object]{.type-label} + - **`Branch`** :span[string]{.type-label} + - **`BuildEnvironment`** :span[string]{.type-label} + - **`BuildNumber`** :span[string]{.type-label} + - **`BuildUrl`** :span[string]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IncompleteDataWarning`** :span[string]{.type-label} + - **`IssueTrackerName`** :span[string]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`PackageId`** :span[string]{.type-label} + - **`VcsCommitNumber`** :span[string]{.type-label} + - **`VcsCommitUrl`** :span[string]{.type-label} + - **`VcsRoot`** :span[string]{.type-label} + - **`VcsType`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} +- **`Published`** :span[string]{.type-label} + Format `date-time`. +- **`ReleaseNotes`** :span[string]{.type-label} +- **`Summary`** :span[string]{.type-label} +- **`Title`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "FeedId": "string", + "FileExtension": "string", + "Hash": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NuGetFeedId": "string", + "NuGetPackageId": "string", + "PackageId": "string", + "PackageSizeBytes": 0, + "PackageVersionBuildInformation": { + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + { + "Comment": "string", + "Id": "string", + "LinkUrl": "string" + } + ], + "Created": "2020-01-01T00:00:00.000Z", + "Id": "string", + "IncompleteDataWarning": "string", + "IssueTrackerName": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + { + "Description": "string", + "Id": "string", + "LinkUrl": "string", + "Source": "string" + } + ] + }, + "Published": "2020-01-01T00:00:00.000Z", + "ReleaseNotes": "string", + "Summary": "string", + "Title": "string", + "Version": "string" +} +``` +::: + +## Validate a package intended for the built in package feed, but does not write the package + +:endpoint{method="POST" path="/api/\{spaceId\}/packages/raw/validate"} + +Also reachable at `/api/packages/raw/validate`, `/api/spaces/{spaceIdentifier}/packages/raw/validate`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The validation issue detected for a package, or null if the package passes all validation checks. + +- **`Issue`** :span[enum]{.type-label} + Allowed values: `CorruptedNugetPackage`, `CouldNotValidate`, `EmptyFile`, `FileNameTooLong`, `InvalidCharactersInFileName`, `InvalidPackageId`, `PackageAlreadyExists`, `UnsupportedFileExtension`. + +:::api-example{label="Response"} +```json +{ + "Issue": "CorruptedNugetPackage" +} +``` +::: + +## Return package information for the specified package id + +:endpoint{method="GET" path="/api/\{spaceId\}/packages/\{id\}"} + +Also reachable at `/api/packages/{id}`, `/api/spaces/{spaceIdentifier}/packages/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the package to retrieve. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`includeNotes`** :span[boolean]{.type-label} + Include release notes in the response. +- **`includeWorkItems`** :span[boolean]{.type-label} + +**Response** + +`200` — The requested Built-in package + +- **`Description`** :span[string]{.type-label} +- **`FeedId`** :span[string]{.type-label} +- **`FileExtension`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NuGetFeedId`** :span[string]{.type-label} +- **`NuGetPackageId`** :span[string]{.type-label} +- **`PackageId`** :span[string]{.type-label} +- **`PackageVersionBuildInformation`** :span[object]{.type-label} + - **`Branch`** :span[string]{.type-label} + - **`BuildEnvironment`** :span[string]{.type-label} + - **`BuildNumber`** :span[string]{.type-label} + - **`BuildUrl`** :span[string]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IncompleteDataWarning`** :span[string]{.type-label} + - **`IssueTrackerName`** :span[string]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`PackageId`** :span[string]{.type-label} + - **`VcsCommitNumber`** :span[string]{.type-label} + - **`VcsCommitUrl`** :span[string]{.type-label} + - **`VcsRoot`** :span[string]{.type-label} + - **`VcsType`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} +- **`Published`** :span[string]{.type-label} + Format `date-time`. +- **`ReleaseNotes`** :span[string]{.type-label} +- **`Summary`** :span[string]{.type-label} +- **`Title`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "FeedId": "string", + "FileExtension": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NuGetFeedId": "string", + "NuGetPackageId": "string", + "PackageId": "string", + "PackageVersionBuildInformation": { + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + { + "Comment": "string", + "Id": "string", + "LinkUrl": "string" + } + ], + "Created": "2020-01-01T00:00:00.000Z", + "Id": "string", + "IncompleteDataWarning": "string", + "IssueTrackerName": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + { + "Description": "string", + "Id": "string", + "LinkUrl": "string", + "Source": "string" + } + ] + }, + "Published": "2020-01-01T00:00:00.000Z", + "ReleaseNotes": "string", + "Summary": "string", + "Title": "string", + "Version": "string" +} +``` +::: + +## Delete the specified Package + +:endpoint{method="DELETE" path="/api/\{spaceId\}/packages/\{id\}"} + +Also reachable at `/api/packages/{id}`, `/api/spaces/{spaceIdentifier}/packages/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Package to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Download the specified package from the built in feed + +:endpoint{method="GET" path="/api/\{spaceId\}/packages/\{id\}/raw"} + +Also reachable at `/api/packages/{id}/raw`, `/api/spaces/{spaceIdentifier}/packages/{id}/raw`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the package to download. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Delete the specified Package + +:endpoint{method="DELETE" path="/api/\{spaceId\}/packages/\{id\}/v1"} + +Also reachable at `/api/packages/{id}/v1`, `/api/spaces/{spaceIdentifier}/packages/{id}/v1`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Package to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the Package was deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Upload a delta patch for the given file. Used to optimize file upload + +:endpoint{method="POST" path="/api/\{spaceId\}/packages/\{packageId\}/\{baseVersion\}/delta"} + +Also reachable at `/api/packages/{packageId}/{baseVersion}/delta`, `/api/spaces/{spaceIdentifier}/packages/{packageId}/{baseVersion}/delta`. + +**Path Parameters** + +- **`baseVersion`** :span[string]{.type-label} *(required)* + The version of the package that was used to create the signature. +- **`packageId`** :span[string]{.type-label} *(required)* + Package ID of the package to be uploaded. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — PackageFromBuiltInFeedResource returned + +- **`Description`** :span[string]{.type-label} +- **`FeedId`** :span[string]{.type-label} +- **`FileExtension`** :span[string]{.type-label} +- **`Hash`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NuGetFeedId`** :span[string]{.type-label} +- **`NuGetPackageId`** :span[string]{.type-label} +- **`PackageId`** :span[string]{.type-label} +- **`PackageSizeBytes`** :span[integer]{.type-label} +- **`PackageVersionBuildInformation`** :span[object]{.type-label} + - **`Branch`** :span[string]{.type-label} + - **`BuildEnvironment`** :span[string]{.type-label} + - **`BuildNumber`** :span[string]{.type-label} + - **`BuildUrl`** :span[string]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IncompleteDataWarning`** :span[string]{.type-label} + - **`IssueTrackerName`** :span[string]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`PackageId`** :span[string]{.type-label} + - **`VcsCommitNumber`** :span[string]{.type-label} + - **`VcsCommitUrl`** :span[string]{.type-label} + - **`VcsRoot`** :span[string]{.type-label} + - **`VcsType`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} +- **`Published`** :span[string]{.type-label} + Format `date-time`. +- **`ReleaseNotes`** :span[string]{.type-label} +- **`Summary`** :span[string]{.type-label} +- **`Title`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "FeedId": "string", + "FileExtension": "string", + "Hash": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NuGetFeedId": "string", + "NuGetPackageId": "string", + "PackageId": "string", + "PackageSizeBytes": 0, + "PackageVersionBuildInformation": { + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + { + "Comment": "string", + "Id": "string", + "LinkUrl": "string" + } + ], + "Created": "2020-01-01T00:00:00.000Z", + "Id": "string", + "IncompleteDataWarning": "string", + "IssueTrackerName": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + { + "Description": "string", + "Id": "string", + "LinkUrl": "string", + "Source": "string" + } + ] + }, + "Published": "2020-01-01T00:00:00.000Z", + "ReleaseNotes": "string", + "Summary": "string", + "Title": "string", + "Version": "string" +} +``` +::: + +## Request the delta-signature for a given package. Used to optimize file upload + +:endpoint{method="GET" path="/api/\{spaceId\}/packages/\{packageId\}/\{version\}/delta-signature"} + +Also reachable at `/api/packages/{packageId}/{version}/delta-signature`, `/api/spaces/{spaceIdentifier}/packages/{packageId}/{version}/delta-signature`. + +**Path Parameters** + +- **`packageId`** :span[string]{.type-label} *(required)* + Package ID of the package to be uploaded. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`version`** :span[string]{.type-label} *(required)* + The version of the package to be uploaded. + +**Response** + +`200` — Returns the delta-signature for a given package. Used to optimize file upload. + +- **`BaseVersion`** :span[string]{.type-label} +- **`Signature`** :span[string]{.type-label} + Format `byte`. + +:::api-example{label="Response"} +```json +{ + "BaseVersion": "string", + "Signature": "c3RyaW5n" +} +``` +::: diff --git a/src/pages/docs/api/parent-environments.md b/src/pages/docs/api/parent-environments.md new file mode 100644 index 0000000000..c69fd9be8a --- /dev/null +++ b/src/pages/docs/api/parent-environments.md @@ -0,0 +1,200 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Parent Environments +--- + +## Create a new parent environment + +:endpoint{method="POST" path="/api/\{spaceId\}/parentEnvironments"} + +Also reachable at `/api/spaces/{spaceIdentifier}/parentEnvironments`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`AutomaticDeprovisioningRule`** :span[object]{.type-label} + - **`ExpiryDays`** :span[integer]{.type-label} + - **`ExpiryHours`** :span[integer]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. Maximum length 50. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`UseGuidedFailure`** :span[boolean]{.type-label} + +:::api-example{label="Request"} +```json +{ + "AutomaticDeprovisioningRule": { + "ExpiryDays": 0, + "ExpiryHours": 0 + }, + "Description": "string", + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "UseGuidedFailure": true +} +``` +::: + +**Response** + +`201` — Created + +- **`Id`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string" +} +``` +::: + +## Modify an existing parent environment + +:endpoint{method="PUT" path="/api/\{spaceId\}/parentEnvironments/\{environmentId\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/parentEnvironments/{environmentId}`. + +**Path Parameters** + +- **`environmentId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`AutomaticDeprovisioningRule`** :span[object]{.type-label} + - **`ExpiryDays`** :span[integer]{.type-label} + - **`ExpiryHours`** :span[integer]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`EnvironmentId`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`UseGuidedFailure`** :span[boolean]{.type-label} + +:::api-example{label="Request"} +```json +{ + "AutomaticDeprovisioningRule": { + "ExpiryDays": 0, + "ExpiryHours": 0 + }, + "Description": "string", + "EnvironmentId": "string", + "Name": "string", + "Slug": "string", + "SortOrder": 0, + "SpaceId": "string", + "UseGuidedFailure": true +} +``` +::: + +**Response** + +`200` — The parent environment after modifications have been applied. + +- **`AutomaticDeprovisioningRule`** :span[object]{.type-label} + - **`ExpiryDays`** :span[integer]{.type-label} + - **`ExpiryHours`** :span[integer]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. +- **`SortOrder`** :span[integer]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`UseGuidedFailure`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AutomaticDeprovisioningRule": { + "ExpiryDays": 0, + "ExpiryHours": 0 + }, + "Description": "string", + "Id": "string", + "Name": "string", + "Slug": "string", + "SortOrder": 0, + "SpaceId": "string", + "UseGuidedFailure": true +} +``` +::: + +## Get a specific Parent Environment + +:endpoint{method="GET" path="/api/\{spaceId\}/parentEnvironments/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/parentEnvironments/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Parent Environment to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested Parent Environment + +- **`AutomaticDeprovisioningRule`** :span[object]{.type-label} + - **`ExpiryDays`** :span[integer]{.type-label} + - **`ExpiryHours`** :span[integer]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. +- **`SortOrder`** :span[integer]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`UseGuidedFailure`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AutomaticDeprovisioningRule": { + "ExpiryDays": 0, + "ExpiryHours": 0 + }, + "Description": "string", + "Id": "string", + "Name": "string", + "Slug": "string", + "SortOrder": 0, + "SpaceId": "string", + "UseGuidedFailure": true +} +``` +::: + +## Delete an existing Parent Environment + +:endpoint{method="DELETE" path="/api/\{spaceId\}/parentEnvironments/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/parentEnvironments/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Parent Environment to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success diff --git a/src/pages/docs/api/performance.md b/src/pages/docs/api/performance.md new file mode 100644 index 0000000000..a193bd4916 --- /dev/null +++ b/src/pages/docs/api/performance.md @@ -0,0 +1,89 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Performance +--- + +## Request the current performance configuration + +:endpoint{method="GET" path="/api/performanceconfiguration"} + +**Response** + +`200` — The current performance configuration + +- **`DefaultDashboardRenderMode`** :span[enum]{.type-label} + Allowed values: `VirtualizeColumns`, `VirtualizeRowsAndColumns`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + +:::api-example{label="Response"} +```json +{ + "DefaultDashboardRenderMode": "VirtualizeColumns", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +## Set the performance configuration + +:endpoint{method="PUT" path="/api/performanceconfiguration"} + +**Request Body** + +- **`DefaultDashboardRenderMode`** :span[enum]{.type-label} *(required)* + Allowed values: `VirtualizeColumns`, `VirtualizeRowsAndColumns`. + +:::api-example{label="Request"} +```json +{ + "DefaultDashboardRenderMode": "VirtualizeColumns" +} +``` +::: + +**Response** + +`200` — The updated performance configuration + +- **`DefaultDashboardRenderMode`** :span[enum]{.type-label} + Allowed values: `VirtualizeColumns`, `VirtualizeRowsAndColumns`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + +:::api-example{label="Response"} +```json +{ + "DefaultDashboardRenderMode": "VirtualizeColumns", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: diff --git a/src/pages/docs/api/permissions.md b/src/pages/docs/api/permissions.md new file mode 100644 index 0000000000..305dc2c8f5 --- /dev/null +++ b/src/pages/docs/api/permissions.md @@ -0,0 +1,1829 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Permissions +--- + +## Get all the available permissions and their descriptions and restrictions + +:endpoint{method="GET" path="/api/permissions/all"} + +**Response** + +`200` — A dictionary keyed by permission with their description + +- **`AccountCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`AccountDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`AccountEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`AccountView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ActionTemplateCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ActionTemplateDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ActionTemplateEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ActionTemplateView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`AdministerSystem`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`AiAgentTranscriptView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ApprovalPolicyAdminister`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ArtifactCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ArtifactDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ArtifactEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ArtifactView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`BuildInformationAdminister`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`BuildInformationPush`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`BuiltInFeedAdminister`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`BuiltInFeedDownload`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`BuiltInFeedPush`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`CertificateCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`CertificateDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`CertificateEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`CertificateExportPrivateKey`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`CertificateView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ConfigureServer`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`DefectReport`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`DefectResolve`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`DeployedResourceAdminister`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`DeploymentCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`DeploymentDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`DeploymentFreezeAdminister`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`DeploymentView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`EnvironmentCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`EnvironmentDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`EnvironmentEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`EnvironmentView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`EventRetentionDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`EventRetentionView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`EventView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`FeatureToggleEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`FeedEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`FeedView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`GitCredentialEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`GitCredentialView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`InsightsReportCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`InsightsReportDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`InsightsReportEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`InsightsReportView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`InterruptionSubmit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`InterruptionView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`InterruptionViewSubmitResponsible`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`LibraryVariableSetCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`LibraryVariableSetDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`LibraryVariableSetEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`LibraryVariableSetView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`LifecycleCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`LifecycleDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`LifecycleEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`LifecycleView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`MachineCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`MachineDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`MachineEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`MachinePolicyCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`MachinePolicyDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`MachinePolicyEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`MachinePolicyView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`MachineView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`PlatformHubEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`PlatformHubView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ProcessEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ProcessView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ProjectCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ProjectDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ProjectEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ProjectGroupCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ProjectGroupDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ProjectGroupEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ProjectGroupView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ProjectView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ProxyCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ProxyDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ProxyEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ProxyView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ReleaseCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ReleaseDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ReleaseEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`ReleaseView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`RetentionAdminister`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`RunbookEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`RunbookRunCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`RunbookRunDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`RunbookRunView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`RunbookSnapshotCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`RunbookView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`SpaceCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`SpaceDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`SpaceEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`SpaceView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`SshKnownHostsAdminister`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`SshKnownHostsView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`SubscriptionCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`SubscriptionDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`SubscriptionEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`SubscriptionView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TagSetCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TagSetDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TagSetEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TargetTagAdminister`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TargetTagView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TaskCancel`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TaskCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TaskEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TaskPrioritize`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TaskView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TeamCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TeamDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TeamEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TeamView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TelemetryView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TenantCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TenantDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TenantEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TenantView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TriggerCreate`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TriggerDelete`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TriggerEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`TriggerView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`UserEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`UserInvite`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`UserRoleEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`UserRoleView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`UserView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`VariableEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`VariableEditUnscoped`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`VariableView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`VariableViewUnscoped`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`WorkerEdit`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`WorkerView`** :span[object]{.type-label} + - **`CanApplyAtSpaceLevel`** :span[boolean]{.type-label} + - **`CanApplyAtSystemLevel`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AccountCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "AccountDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "AccountEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "AccountView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ActionTemplateCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ActionTemplateDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ActionTemplateEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ActionTemplateView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "AdministerSystem": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "AiAgentTranscriptView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ApprovalPolicyAdminister": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ArtifactCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ArtifactDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ArtifactEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ArtifactView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "BuildInformationAdminister": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "BuildInformationPush": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "BuiltInFeedAdminister": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "BuiltInFeedDownload": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "BuiltInFeedPush": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "CertificateCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "CertificateDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "CertificateEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "CertificateExportPrivateKey": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "CertificateView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ConfigureServer": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "DefectReport": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "DefectResolve": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "DeployedResourceAdminister": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "DeploymentCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "DeploymentDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "DeploymentFreezeAdminister": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "DeploymentView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "EnvironmentCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "EnvironmentDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "EnvironmentEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "EnvironmentView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "EventRetentionDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "EventRetentionView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "EventView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "FeatureToggleEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "FeedEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "FeedView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "GitCredentialEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "GitCredentialView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "InsightsReportCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "InsightsReportDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "InsightsReportEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "InsightsReportView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "InterruptionSubmit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "InterruptionView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "InterruptionViewSubmitResponsible": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "LibraryVariableSetCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "LibraryVariableSetDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "LibraryVariableSetEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "LibraryVariableSetView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "LifecycleCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "LifecycleDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "LifecycleEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "LifecycleView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "MachineCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "MachineDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "MachineEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "MachinePolicyCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "MachinePolicyDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "MachinePolicyEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "MachinePolicyView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "MachineView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "PlatformHubEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "PlatformHubView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ProcessEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ProcessView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ProjectCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ProjectDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ProjectEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ProjectGroupCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ProjectGroupDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ProjectGroupEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ProjectGroupView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ProjectView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ProxyCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ProxyDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ProxyEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ProxyView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ReleaseCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ReleaseDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ReleaseEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "ReleaseView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "RetentionAdminister": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "RunbookEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "RunbookRunCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "RunbookRunDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "RunbookRunView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "RunbookSnapshotCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "RunbookView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "SpaceCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "SpaceDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "SpaceEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "SpaceView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "SshKnownHostsAdminister": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "SshKnownHostsView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "SubscriptionCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "SubscriptionDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "SubscriptionEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "SubscriptionView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TagSetCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TagSetDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TagSetEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TargetTagAdminister": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TargetTagView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TaskCancel": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TaskCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TaskEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TaskPrioritize": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TaskView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TeamCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TeamDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TeamEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TeamView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TelemetryView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TenantCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TenantDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TenantEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TenantView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TriggerCreate": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TriggerDelete": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TriggerEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "TriggerView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "UserEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "UserInvite": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "UserRoleEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "UserRoleView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "UserView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "VariableEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "VariableEditUnscoped": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "VariableView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "VariableViewUnscoped": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "WorkerEdit": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + }, + "WorkerView": { + "CanApplyAtSpaceLevel": true, + "CanApplyAtSystemLevel": true, + "Description": "string", + "SupportedRestrictions": [ + "string" + ] + } +} +``` +::: diff --git a/src/pages/docs/api/platform-hub.md b/src/pages/docs/api/platform-hub.md new file mode 100644 index 0000000000..bfb6da6f6f --- /dev/null +++ b/src/pages/docs/api/platform-hub.md @@ -0,0 +1,2822 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Platform Hub +--- + +## Get Platform Hub accounts + +:endpoint{method="GET" path="/api/platformhub/accounts"} + +**Query Parameters** + +- **`accountType`** :span[array of string]{.type-label} + The type of accounts to return. +- **`name`** :span[string]{.type-label} + Filter by partial name match. +- **`skip`** :span[integer]{.type-label} + Number of records to skip. +- **`take`** :span[integer]{.type-label} + Number of records to take. + +**Response** + +`200` — Success + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Details`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`Slug`** :span[string]{.type-label} + Minimum length 1. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "Description": "string", + "Details": { + "AccountType": "string" + }, + "Id": "string", + "Name": "string", + "Slug": "string" + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new Platform Hub account + +:endpoint{method="POST" path="/api/platformhub/accounts"} + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} *(required)* + - **`AccountType`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Slug`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Details": { + "AccountType": "string" + }, + "Name": "string", + "Slug": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Id`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string" +} +``` +::: + +## Get a specific Platform Hub account + +:endpoint{method="GET" path="/api/platformhub/accounts/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the account to get. + +**Response** + +`200` — An Account within the Platform Hub + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} + - **`AccountType`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Details": { + "AccountType": "string" + }, + "Id": "string", + "Name": "string", + "Slug": "string" +} +``` +::: + +## Modify an existing Platform Hub account + +:endpoint{method="PUT" path="/api/platformhub/accounts/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} *(required)* + - **`AccountType`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Slug`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Details": { + "AccountType": "string" + }, + "Id": "string", + "Name": "string", + "Slug": "string" +} +``` +::: + +**Response** + +`200` — Indicates that the Platform Hub account was successfully modified. + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Delete an existing Platform Hub account + +:endpoint{method="DELETE" path="/api/platformhub/accounts/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the account to delete. + +**Response** + +`200` — Confirmation that the Platform Hub account has been deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get Platform Hub certificates + +:endpoint{method="GET" path="/api/platformhub/certificates"} + +**Query Parameters** + +- **`archived`** :span[boolean]{.type-label} + If true, returns only archived certificates. Otherwise, returns only non-archived certificates. +- **`firstResult`** :span[string]{.type-label} + Certificate ID which if specified, adds the certificate with matching ID to the result if it is not already included. +- **`ids`** :span[string]{.type-label} + Comma delimited list of certificate IDs used to filter the result. +- **`orderBy`** :span[string]{.type-label} + If the value is 'recent' (case-insensitive), the result is sorted by Created instead of NotAfter. +- **`partialName`** :span[string]{.type-label} + Alternative parameter to Search; filters certificates by Name, Subject, or Thumbprint. +- **`search`** :span[string]{.type-label} + Filters certificates by Name, Subject, or Thumbprint. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 15. Minimum `0`. + +**Response** + +`200` — The requested Platform Hub certificates. + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Archived`** :span[string]{.type-label} + Format `date-time`. + - **`CertificateChain`** :span[array of object]{.type-label} + - **`CertificateData`** :span[sensitive value]{.type-label} + - **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. + - **`HasPrivateKey`** :span[boolean]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsExpired`** :span[boolean]{.type-label} + - **`IssuerCommonName`** :span[string]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`IssuerOrganization`** :span[string]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`Notes`** :span[string]{.type-label} + - **`Password`** :span[sensitive value]{.type-label} + - **`ReplacedBy`** :span[string]{.type-label} + - **`SelfSigned`** :span[boolean]{.type-label} + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`Slug`** :span[string]{.type-label} + The slug of the certificate. + - **`SubjectAlternativeNames`** :span[array of string]{.type-label} + - **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + {} + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "Slug": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "Thumbprint": "string", + "Version": 0 + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new Platform Hub certificate + +:endpoint{method="POST" path="/api/platformhub/certificates"} + +**Request Body** + +- **`CertificateData`** :span[sensitive value]{.type-label} *(required)* + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Notes`** :span[string]{.type-label} + Maximum length 10240. +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Name": "string", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Slug": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Archived`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateChain`** :span[array of object]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`CertificateData`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`HasPrivateKey`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsExpired`** :span[boolean]{.type-label} +- **`IssuerCommonName`** :span[string]{.type-label} +- **`IssuerDistinguishedName`** :span[string]{.type-label} +- **`IssuerOrganization`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`NotAfter`** :span[string]{.type-label} + Format `date-time`. +- **`NotBefore`** :span[string]{.type-label} + Format `date-time`. +- **`Notes`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`ReplacedBy`** :span[string]{.type-label} +- **`SelfSigned`** :span[boolean]{.type-label} +- **`SerialNumber`** :span[string]{.type-label} +- **`SignatureAlgorithmName`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} + The slug of the certificate. +- **`SubjectAlternativeNames`** :span[array of string]{.type-label} +- **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`SubjectDistinguishedName`** :span[string]{.type-label} +- **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`Thumbprint`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + { + "IssuerDistinguishedName": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SubjectDistinguishedName": "string", + "Thumbprint": "string", + "Version": 0 + } + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "Slug": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "Thumbprint": "string", + "Version": 0 +} +``` +::: + +## Create a self-signed Platform Hub certificate + +:endpoint{method="POST" path="/api/platformhub/certificates/generate"} + +**Request Body** + +- **`Archived`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateChain`** :span[array of object]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`CertificateData`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`HasPrivateKey`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsExpired`** :span[boolean]{.type-label} +- **`IssuerCommonName`** :span[string]{.type-label} +- **`IssuerDistinguishedName`** :span[string]{.type-label} +- **`IssuerOrganization`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`NotAfter`** :span[string]{.type-label} + Format `date-time`. +- **`NotBefore`** :span[string]{.type-label} + Format `date-time`. +- **`Notes`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`ReplacedBy`** :span[string]{.type-label} +- **`SelfSigned`** :span[boolean]{.type-label} +- **`SelfSignedCertificateCurve`** :span[string]{.type-label} +- **`SerialNumber`** :span[string]{.type-label} +- **`SignatureAlgorithmName`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} + The slug of the certificate. +- **`SubjectAlternativeNames`** :span[array of string]{.type-label} +- **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`SubjectDistinguishedName`** :span[string]{.type-label} +- **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`Thumbprint`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + { + "IssuerDistinguishedName": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SubjectDistinguishedName": "string", + "Thumbprint": "string", + "Version": 0 + } + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SelfSignedCertificateCurve": "string", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "Slug": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "Thumbprint": "string", + "Version": 0 +} +``` +::: + +**Response** + +`200` — The created self-signed Platform Hub certificate. + +- **`Archived`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateChain`** :span[array of object]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`CertificateData`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`HasPrivateKey`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsExpired`** :span[boolean]{.type-label} +- **`IssuerCommonName`** :span[string]{.type-label} +- **`IssuerDistinguishedName`** :span[string]{.type-label} +- **`IssuerOrganization`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`NotAfter`** :span[string]{.type-label} + Format `date-time`. +- **`NotBefore`** :span[string]{.type-label} + Format `date-time`. +- **`Notes`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`ReplacedBy`** :span[string]{.type-label} +- **`SelfSigned`** :span[boolean]{.type-label} +- **`SerialNumber`** :span[string]{.type-label} +- **`SignatureAlgorithmName`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} + The slug of the certificate. +- **`SubjectAlternativeNames`** :span[array of string]{.type-label} +- **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`SubjectDistinguishedName`** :span[string]{.type-label} +- **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`Thumbprint`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + { + "IssuerDistinguishedName": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SubjectDistinguishedName": "string", + "Thumbprint": "string", + "Version": 0 + } + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "Slug": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "Thumbprint": "string", + "Version": 0 +} +``` +::: + +## Get a Platform Hub certificate by ID or Thumbprint + +:endpoint{method="GET" path="/api/platformhub/certificates/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested Platform Hub certificate. + +- **`Archived`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateChain`** :span[array of object]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`CertificateData`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`HasPrivateKey`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsExpired`** :span[boolean]{.type-label} +- **`IssuerCommonName`** :span[string]{.type-label} +- **`IssuerDistinguishedName`** :span[string]{.type-label} +- **`IssuerOrganization`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`NotAfter`** :span[string]{.type-label} + Format `date-time`. +- **`NotBefore`** :span[string]{.type-label} + Format `date-time`. +- **`Notes`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`ReplacedBy`** :span[string]{.type-label} +- **`SelfSigned`** :span[boolean]{.type-label} +- **`SerialNumber`** :span[string]{.type-label} +- **`SignatureAlgorithmName`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} + The slug of the certificate. +- **`SubjectAlternativeNames`** :span[array of string]{.type-label} +- **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`SubjectDistinguishedName`** :span[string]{.type-label} +- **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`Thumbprint`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + { + "IssuerDistinguishedName": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SubjectDistinguishedName": "string", + "Thumbprint": "string", + "Version": 0 + } + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "Slug": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "Thumbprint": "string", + "Version": 0 +} +``` +::: + +## Modify an existing Platform Hub certificate + +:endpoint{method="PUT" path="/api/platformhub/certificates/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Id`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Notes`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "Name": "string", + "Notes": "string", + "Slug": "string" +} +``` +::: + +**Response** + +`200` — The modified Platform Hub certificate. + +- **`Archived`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateChain`** :span[array of object]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`CertificateData`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`HasPrivateKey`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsExpired`** :span[boolean]{.type-label} +- **`IssuerCommonName`** :span[string]{.type-label} +- **`IssuerDistinguishedName`** :span[string]{.type-label} +- **`IssuerOrganization`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`NotAfter`** :span[string]{.type-label} + Format `date-time`. +- **`NotBefore`** :span[string]{.type-label} + Format `date-time`. +- **`Notes`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`ReplacedBy`** :span[string]{.type-label} +- **`SelfSigned`** :span[boolean]{.type-label} +- **`SerialNumber`** :span[string]{.type-label} +- **`SignatureAlgorithmName`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} + The slug of the certificate. +- **`SubjectAlternativeNames`** :span[array of string]{.type-label} +- **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`SubjectDistinguishedName`** :span[string]{.type-label} +- **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`Thumbprint`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + { + "IssuerDistinguishedName": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SubjectDistinguishedName": "string", + "Thumbprint": "string", + "Version": 0 + } + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "Slug": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "Thumbprint": "string", + "Version": 0 +} +``` +::: + +## Delete an existing archived Platform Hub certificate + +:endpoint{method="DELETE" path="/api/platformhub/certificates/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Confirmation that the Platform Hub certificate has been deleted. + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Archive an existing Platform Hub certificate + +:endpoint{method="POST" path="/api/platformhub/certificates/\{id\}/archive"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Confirmation that the Platform Hub certificate has been archived. + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Export the Platform Hub certificate + +:endpoint{method="GET" path="/api/platformhub/certificates/\{id\}/export"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`format`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`includePrivateKey`** :span[boolean]{.type-label} +- **`password`** :span[string]{.type-label} +- **`pemOptions`** :span[enum]{.type-label} + Allowed values: `PrimaryOnly`, `PrimaryAndChain`, `ChainOnly`. + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Replace an existing Platform Hub certificate with another + +:endpoint{method="POST" path="/api/platformhub/certificates/\{id\}/replace"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`CertificateData`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Id`** :span[string]{.type-label} *(required)* +- **`Password`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "CertificateData": "string", + "Id": "string", + "Password": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Platform Hub certificate has been replaced. + +- **`Archived`** :span[string]{.type-label} + Format `date-time`. +- **`CertificateChain`** :span[array of object]{.type-label} + - **`IssuerDistinguishedName`** :span[string]{.type-label} + - **`NotAfter`** :span[string]{.type-label} + Format `date-time`. + - **`NotBefore`** :span[string]{.type-label} + Format `date-time`. + - **`SerialNumber`** :span[string]{.type-label} + - **`SignatureAlgorithmName`** :span[string]{.type-label} + - **`SubjectDistinguishedName`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`CertificateData`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`CertificateDataFormat`** :span[enum]{.type-label} + Allowed values: `Pkcs12`, `Der`, `Pem`, `Unknown`. +- **`HasPrivateKey`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsExpired`** :span[boolean]{.type-label} +- **`IssuerCommonName`** :span[string]{.type-label} +- **`IssuerDistinguishedName`** :span[string]{.type-label} +- **`IssuerOrganization`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`NotAfter`** :span[string]{.type-label} + Format `date-time`. +- **`NotBefore`** :span[string]{.type-label} + Format `date-time`. +- **`Notes`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`ReplacedBy`** :span[string]{.type-label} +- **`SelfSigned`** :span[boolean]{.type-label} +- **`SerialNumber`** :span[string]{.type-label} +- **`SignatureAlgorithmName`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} + The slug of the certificate. +- **`SubjectAlternativeNames`** :span[array of string]{.type-label} +- **`SubjectCommonName`** :span[string]{.type-label} + The certificate subject's common name (CN). When creating a self-signed certificate this becomes the generated certificate's CN, and at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`SubjectDistinguishedName`** :span[string]{.type-label} +- **`SubjectOrganization`** :span[string]{.type-label} + The certificate subject's organization (O). When creating a self-signed certificate, at least one of SubjectCommonName or SubjectOrganization must be supplied. +- **`Thumbprint`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Archived": "2020-01-01T00:00:00.000Z", + "CertificateChain": [ + { + "IssuerDistinguishedName": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "SubjectDistinguishedName": "string", + "Thumbprint": "string", + "Version": 0 + } + ], + "CertificateData": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "CertificateDataFormat": "Pkcs12", + "HasPrivateKey": true, + "Id": "string", + "IsExpired": true, + "IssuerCommonName": "string", + "IssuerDistinguishedName": "string", + "IssuerOrganization": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "NotAfter": "2020-01-01T00:00:00.000Z", + "NotBefore": "2020-01-01T00:00:00.000Z", + "Notes": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "ReplacedBy": "string", + "SelfSigned": true, + "SerialNumber": "string", + "SignatureAlgorithmName": "string", + "Slug": "string", + "SubjectAlternativeNames": [ + "string" + ], + "SubjectCommonName": "string", + "SubjectDistinguishedName": "string", + "SubjectOrganization": "string", + "Thumbprint": "string", + "Version": 0 +} +``` +::: + +## Unarchive an existing archived Platform Hub certificate + +:endpoint{method="POST" path="/api/platformhub/certificates/\{id\}/unarchive"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Confirmation that the Platform Hub certificate has been unarchived. + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get usages for a Platform Hub certificate + +:endpoint{method="GET" path="/api/platformhub/certificates/\{id\}/usages"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The published template versions that use a Platform Hub certificate. + +- **`DefaultBranchProcessTemplateUsageCount`** :span[integer]{.type-label} +- **`DefaultBranchProcessTemplateUsages`** :span[array of object]{.type-label} + - **`GitRef`** :span[string]{.type-label} + Minimum length 1. + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`Slug`** :span[string]{.type-label} + Minimum length 1. + - **`UsageSource`** :span[string]{.type-label} + Minimum length 1. +- **`DefaultBranchProjectTemplateUsageCount`** :span[integer]{.type-label} +- **`DefaultBranchProjectTemplateUsages`** :span[array of object]{.type-label} + - **`GitRef`** :span[string]{.type-label} + Minimum length 1. + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`Slug`** :span[string]{.type-label} + Minimum length 1. + - **`UsageSource`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProcessTemplateVersionUsageCount`** :span[integer]{.type-label} +- **`ProcessTemplateVersionUsages`** :span[array of object]{.type-label} + - **`GitRef`** :span[string]{.type-label} + Minimum length 1. + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PublishedDate`** :span[string]{.type-label} + Format `date-time`. + - **`Slug`** :span[string]{.type-label} + Minimum length 1. + - **`Version`** :span[string]{.type-label} + Minimum length 1. +- **`ProjectTemplateVersionUsageCount`** :span[integer]{.type-label} +- **`ProjectTemplateVersionUsages`** :span[array of object]{.type-label} + - **`GitRef`** :span[string]{.type-label} + Minimum length 1. + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PublishedDate`** :span[string]{.type-label} + Format `date-time`. + - **`Slug`** :span[string]{.type-label} + Minimum length 1. + - **`Version`** :span[string]{.type-label} + Minimum length 1. +- **`TotalUsageCount`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DefaultBranchProcessTemplateUsageCount": 0, + "DefaultBranchProcessTemplateUsages": [ + { + "GitRef": "string", + "Id": "string", + "Name": "string", + "Slug": "string", + "UsageSource": "string" + } + ], + "DefaultBranchProjectTemplateUsageCount": 0, + "DefaultBranchProjectTemplateUsages": [ + { + "GitRef": "string", + "Id": "string", + "Name": "string", + "Slug": "string", + "UsageSource": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProcessTemplateVersionUsageCount": 0, + "ProcessTemplateVersionUsages": [ + { + "GitRef": "string", + "Id": "string", + "Name": "string", + "PublishedDate": "2020-01-01T00:00:00.000Z", + "Slug": "string", + "Version": "string" + } + ], + "ProjectTemplateVersionUsageCount": 0, + "ProjectTemplateVersionUsages": [ + { + "GitRef": "string", + "Id": "string", + "Name": "string", + "PublishedDate": "2020-01-01T00:00:00.000Z", + "Slug": "string", + "Version": "string" + } + ], + "TotalUsageCount": 0 +} +``` +::: + +## Get a list of Platform Hub Feeds + +:endpoint{method="GET" path="/api/platformhub/feeds"} + +**Query Parameters** + +- **`feedType`** :span[array of string]{.type-label} + The feed types to be matched, provided as a comma separated list of strings. +- **`ids`** :span[array of string]{.type-label} + The feed ids to be matched, provided as a comma separated list of strings. +- **`name`** :span[string]{.type-label} + The exact name of a feed to be matched. +- **`partialName`** :span[string]{.type-label} + The partial name of feeds to be matched. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested list of Platform Hub Feeds + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`FeedType`** :span[enum]{.type-label} + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. + - **`Id`** :span[string]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + - **`LastModifiedOn`** :span[string]{.type-label} + Format `date-time`. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageAcquisitionLocationOptions`** :span[array of enum]{.type-label} + Allowed values: `Server`, `ExecutionTarget`, `NotAcquired`. + - **`Slug`** :span[string]{.type-label} + Minimum length 1. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "FeedType": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Name": "string", + "PackageAcquisitionLocationOptions": [ + "Server" + ], + "Slug": "string" + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new Platform Hub Feed + +:endpoint{method="POST" path="/api/platformhub/feeds"} + +**Request Body** + +- **`FeedType`** :span[enum]{.type-label} *(required)* + The type of the feed. + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the feed. Maximum length 44. +- **`PackageAcquisitionLocationOptions`** :span[array of enum]{.type-label} + The feed's package acquisition location options. + Allowed values: `Server`, `ExecutionTarget`, `NotAcquired`. +- **`Slug`** :span[string]{.type-label} + The slug of the feed. + +:::api-example{label="Request"} +```json +{ + "FeedType": "None", + "Name": "string", + "PackageAcquisitionLocationOptions": [ + "Server" + ], + "Slug": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`FeedType`** :span[enum]{.type-label} + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`Id`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} +- **`LastModifiedOn`** :span[string]{.type-label} + Format `date-time`. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`PackageAcquisitionLocationOptions`** :span[array of enum]{.type-label} + Allowed values: `Server`, `ExecutionTarget`, `NotAcquired`. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "FeedType": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Name": "string", + "PackageAcquisitionLocationOptions": [ + "Server" + ], + "Slug": "string" +} +``` +::: + +## Get a Platform Hub Feed by its id + +:endpoint{method="GET" path="/api/platformhub/feeds/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the Platform Hub Feed to get. + +**Response** + +`200` — A Feed within the Platform Hub + +- **`FeedType`** :span[enum]{.type-label} + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`Id`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} +- **`LastModifiedOn`** :span[string]{.type-label} + Format `date-time`. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`PackageAcquisitionLocationOptions`** :span[array of enum]{.type-label} + Allowed values: `Server`, `ExecutionTarget`, `NotAcquired`. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "FeedType": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Name": "string", + "PackageAcquisitionLocationOptions": [ + "Server" + ], + "Slug": "string" +} +``` +::: + +## Modify a Platform Hub Feed + +:endpoint{method="PUT" path="/api/platformhub/feeds/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the feed. + +**Request Body** + +- **`FeedType`** :span[enum]{.type-label} *(required)* + The type of the feed. + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`Id`** :span[string]{.type-label} *(required)* + The id of the feed. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the feed. Maximum length 44. +- **`PackageAcquisitionLocationOptions`** :span[array of enum]{.type-label} + The feed's package acquisition location options. + Allowed values: `Server`, `ExecutionTarget`, `NotAcquired`. +- **`Slug`** :span[string]{.type-label} + The slug of the feed. + +:::api-example{label="Request"} +```json +{ + "FeedType": "None", + "Id": "string", + "Name": "string", + "PackageAcquisitionLocationOptions": [ + "Server" + ], + "Slug": "string" +} +``` +::: + +**Response** + +`200` — The response returned from the request to modify a platform hub feed. + +- **`FeedType`** :span[enum]{.type-label} + Allowed values: `None`, `NuGet`, `Docker`, `Maven`, `OctopusProject`, `GitHub`, `Helm`, `OciRegistry`, `AwsElasticContainerRegistry`, `BuiltIn`, `S3`, `AzureContainerRegistry`, `GoogleContainerRegistry`, `ArtifactoryGeneric`, `Npm`, `GcsStorage`, `PyPi`. +- **`Id`** :span[string]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} +- **`LastModifiedOn`** :span[string]{.type-label} + Format `date-time`. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`PackageAcquisitionLocationOptions`** :span[array of enum]{.type-label} + Allowed values: `Server`, `ExecutionTarget`, `NotAcquired`. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "FeedType": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Name": "string", + "PackageAcquisitionLocationOptions": [ + "Server" + ], + "Slug": "string" +} +``` +::: + +## Delete an existing Platform Hub Feed + +:endpoint{method="DELETE" path="/api/platformhub/feeds/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the Platform Hub Feed to delete. + +**Response** + +`200` — Confirmation that the Platform Hub feed has been deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Search the specified platform hub feed for packages based on the provided search term + +:endpoint{method="GET" path="/api/platformhub/feeds/\{id\}/packages/search"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the feed resource. + +**Query Parameters** + +- **`packageType`** :span[string]{.type-label} + The package type to filter results by. Used by feeds that can contain multiple package types. Valid values are ContainerImage and HelmChart. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 20. Minimum `0`. +- **`term`** :span[string]{.type-label} + The term to search for. + +**Response** + +`200` — Returns a paginated collection of searched package descriptions in platform hub + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`LatestVersion`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "Description": "string", + "Id": "string", + "LatestVersion": "string", + "Name": "string" + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## List available package versions for the specified platform hub feed and package + +:endpoint{method="GET" path="/api/platformhub/feeds/\{id\}/packages/versions"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the feed resource. + +**Query Parameters** + +- **`filter`** :span[string]{.type-label} + Version number text to filter by. +- **`includePreRelease`** :span[boolean]{.type-label} + Flag to include pre-release versions, defaults to true. +- **`includeReleaseNotes`** :span[boolean]{.type-label} + Flag to include release notes, defaults to false. +- **`packageId`** :span[string]{.type-label} *(required)* + The id of the package. +- **`preReleaseTag`** :span[string]{.type-label} + The semver tag regex pattern to filter by. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 20. Minimum `0`. +- **`versionRange`** :span[string]{.type-label} + The range of versions to filter by. + +**Response** + +`200` — Contains a paginated collection of package versions returned from a search + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`FeedId`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`PackageId`** :span[string]{.type-label} + Minimum length 1. + - **`Published`** :span[string]{.type-label} + Format `date-time`. + - **`ReleaseNotes`** :span[string]{.type-label} + - **`SizeBytes`** :span[integer]{.type-label} + - **`Title`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + Minimum length 1. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "FeedId": "string", + "Id": "string", + "PackageId": "string", + "Published": "2020-01-01T00:00:00.000Z", + "ReleaseNotes": "string", + "SizeBytes": 0, + "Title": "string", + "Version": "string" + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get Platform Hub Git credentials + +:endpoint{method="GET" path="/api/platformhub/git-credentials"} + +**Query Parameters** + +- **`name`** :span[string]{.type-label} + Filter by partial name match. +- **`skip`** :span[integer]{.type-label} + Number of records to skip. +- **`take`** :span[integer]{.type-label} + Number of records to take. + +**Response** + +`200` — Success + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Details`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`RepositoryRestrictions`** :span[object]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "Description": "string", + "Details": { + "Type": "UsernamePassword" + }, + "Id": "string", + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + } + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new Platform Hub Git credential + +:endpoint{method="POST" path="/api/platformhub/git-credentials"} + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} *(required)* + - **`Password`** :span[sensitive value]{.type-label} *(required)* + - **`Username`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`RepositoryRestrictions`** :span[object]{.type-label} + - **`AllowedRepositories`** :span[array of string]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Details": { + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Username": "string" + }, + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + } +} +``` +::: + +**Response** + +`201` — Created + +- **`Id`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string" +} +``` +::: + +## Get Platform Hub Git credentials (V2) + +:endpoint{method="GET" path="/api/platformhub/git-credentials/v2"} + +**Query Parameters** + +- **`name`** :span[string]{.type-label} + Filter by partial name match. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Success + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Details`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`RepositoryRestrictions`** :span[object]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "Description": "string", + "Details": { + "Type": "UsernamePassword" + }, + "Id": "string", + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + } + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new Platform Hub Git credential + +:endpoint{method="POST" path="/api/platformhub/git-credentials/v2"} + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} *(required)* + - **`Type`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`RepositoryRestrictions`** :span[object]{.type-label} + - **`AllowedRepositories`** :span[array of string]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Details": { + "Type": "string" + }, + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + } +} +``` +::: + +**Response** + +`201` — Created + +- **`Id`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string" +} +``` +::: + +## Get a specific Platform Hub Git credential + +:endpoint{method="GET" path="/api/platformhub/git-credentials/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Git credential to get. + +**Response** + +`200` — The requested Platform Hub Git Credential + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `UsernamePassword`, `Anonymous`, `Library`, `GitHub`, `NotSpecified`, `SshKey`. +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`RepositoryRestrictions`** :span[object]{.type-label} + - **`AllowedRepositories`** :span[array of string]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Details": { + "Type": "UsernamePassword" + }, + "Id": "string", + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + } +} +``` +::: + +## Modify an existing Platform Hub Git credential + +:endpoint{method="PUT" path="/api/platformhub/git-credentials/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} *(required)* + - **`Password`** :span[sensitive value]{.type-label} *(required)* + - **`Username`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Id`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`RepositoryRestrictions`** :span[object]{.type-label} + - **`AllowedRepositories`** :span[array of string]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Details": { + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Username": "string" + }, + "Id": "string", + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + } +} +``` +::: + +**Response** + +`200` — Indicates that the Platform Hub Git Credential was successfully modified. + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Delete an existing Platform Hub Git credential + +:endpoint{method="DELETE" path="/api/platformhub/git-credentials/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Git credential to delete. + +**Response** + +`200` — Confirmation that the Platform Hub Git Credential has been deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get a specific Platform Hub Git credential (V2) + +:endpoint{method="GET" path="/api/platformhub/git-credentials/\{id\}/v2"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Git credential to get. + +**Response** + +`200` — A Platform Hub Git credential (V2) + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `UsernamePassword`, `Anonymous`, `Library`, `GitHub`, `NotSpecified`, `SshKey`. +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`RepositoryRestrictions`** :span[object]{.type-label} + - **`AllowedRepositories`** :span[array of string]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Details": { + "Type": "UsernamePassword" + }, + "Id": "string", + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + } +} +``` +::: + +## Modify an existing Platform Hub Git credential + +:endpoint{method="PUT" path="/api/platformhub/git-credentials/\{id\}/v2"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} *(required)* + - **`Type`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Id`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`RepositoryRestrictions`** :span[object]{.type-label} + - **`AllowedRepositories`** :span[array of string]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Details": { + "Type": "string" + }, + "Id": "string", + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + } +} +``` +::: + +**Response** + +`200` — Indicates that the Platform Hub Git Credential was successfully modified. + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Request the list of Branches for the Platform Hub + +:endpoint{method="GET" path="/api/platformhub/git/branches"} + +**Query Parameters** + +- **`searchByName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Success + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`CanonicalName`** :span[string]{.type-label} + Minimum length 1. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsProtected`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "CanonicalName": "string", + "Id": "string", + "IsProtected": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a branch given the base git ref, and the new branch's name + +:endpoint{method="POST" path="/api/platformhub/git/branches"} + +**Request Body** + +- **`BaseGitRef`** :span[string]{.type-label} *(required)* +- **`NewBranchName`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "BaseGitRef": "string", + "NewBranchName": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`CanonicalName`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsProtected`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "CanonicalName": "string", + "Id": "string", + "IsProtected": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" +} +``` +::: + +## Request a list of Git Tags for the Platform Hub + +:endpoint{method="GET" path="/api/platformhub/git/tags"} + +**Query Parameters** + +- **`searchByName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Success + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`CanonicalName`** :span[string]{.type-label} + Minimum length 1. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "CanonicalName": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get GitHub App connections for the Platform Hub + +:endpoint{method="GET" path="/api/platformhub/github/connections"} + +Gets a set of GitHub App connections for the Platform Hub. + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} *(required)* + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} *(required)* + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — All GitHub App connections for Platform Hub + +- **`Connections`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Installation`** :span[object]{.type-label} + - **`Status`** :span[enum]{.type-label} + Allowed values: `ConnectionNotFound`, `InstallationNotFound`, `InstallationSuspended`, `Connected`, `Error`. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Connections": [ + { + "Id": "string", + "Installation": { + "AccountAvatarUrl": "string", + "AccountId": "string", + "AccountLogin": "string", + "AccountType": "string", + "AllRepositories": true, + "InstallationId": "string" + }, + "Status": "ConnectionNotFound" + } + ], + "ItemsPerPage": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new GitHub App connection in Platform Hub + +:endpoint{method="POST" path="/api/platformhub/github/connections"} + +**Request Body** + +- **`InstallationId`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`RepositoryIds`** :span[array of string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "InstallationId": "string", + "RepositoryIds": [ + "string" + ] +} +``` +::: + +**Response** + +`201` — Created + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Get a single PlatformHub GitHub app connection by id + +:endpoint{method="GET" path="/api/platformhub/github/connections/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — A PlatformHub GitHub app connection + +- **`Id`** :span[string]{.type-label} +- **`Installation`** :span[object]{.type-label} + - **`AccountAvatarUrl`** :span[string]{.type-label} + - **`AccountId`** :span[string]{.type-label} + - **`AccountLogin`** :span[string]{.type-label} + - **`AccountType`** :span[string]{.type-label} + - **`AllRepositories`** :span[boolean]{.type-label} + true if the installation has access to all repositories in the account, false if it has access to only selected repositories. + - **`InstallationId`** :span[string]{.type-label} +- **`Repositories`** :span[array of object]{.type-label} + - **`DefaultBranch`** :span[string]{.type-label} + - **`GitUrl`** :span[string]{.type-label} + - **`IsAdmin`** :span[boolean]{.type-label} + - **`IsPrivate`** :span[boolean]{.type-label} + - **`Language`** :span[string]{.type-label} + - **`RepositoryId`** :span[string]{.type-label} + - **`RepositoryName`** :span[string]{.type-label} + - **`Visibility`** :span[string]{.type-label} +- **`Status`** :span[string]{.type-label} + Minimum length 1. +- **`StatusUserMessage`** :span[string]{.type-label} +- **`UnknownRepositories`** :span[array of object]{.type-label} + Repositories IDs that are configured on the connection but do not have a matching repository returned from GitHub. + - **`RepositoryId`** :span[string]{.type-label} + - **`RepositoryName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "Installation": { + "AccountAvatarUrl": "string", + "AccountId": "string", + "AccountLogin": "string", + "AccountType": "string", + "AllRepositories": true, + "InstallationId": "string" + }, + "Repositories": [ + { + "DefaultBranch": "string", + "GitUrl": "string", + "IsAdmin": true, + "IsPrivate": true, + "Language": "string", + "RepositoryId": "string", + "RepositoryName": "string", + "Visibility": "string" + } + ], + "Status": "string", + "StatusUserMessage": "string", + "UnknownRepositories": [ + { + "RepositoryId": "string", + "RepositoryName": "string" + } + ] +} +``` +::: + +## Update a Platform Hub GitHub App connection with a new set of repositories + +:endpoint{method="PUT" path="/api/platformhub/github/connections/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Id`** :span[string]{.type-label} *(required)* +- **`RepositoryIds`** :span[array of string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "RepositoryIds": [ + "string" + ] +} +``` +::: + +**Response** + +`200` — Platform Hub GitHub app connection modified result + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Delete a PlatformHub GitHub App connection by id + +:endpoint{method="DELETE" path="/api/platformhub/github/connections/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the GitHub connection to delete. + +**Response** + +`200` — Confirmation that the PlatformHub GitHub App connection has been deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Recover a platfrom hub GitHub App connection after the registration has changed + +:endpoint{method="POST" path="/api/platformhub/github/connections/\{id\}/recover"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Id`** :span[string]{.type-label} *(required)* +- **`RepositoryIds`** :span[array of string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "RepositoryIds": [ + "string" + ] +} +``` +::: + +**Response** + +`200` — Platform Hub GitHub app connection recovery result + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Refresh the Platform Hub GitHub App connection token + +:endpoint{method="POST" path="/api/platformhub/github/connections/\{id\}/refresh"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Platform Hub GitHub app connection has been refreshed + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get a list of GitHub organisations accessible to the current GitHub OAuth user. Request will fail if the user does not have a valid GitHub OAuth token + +:endpoint{method="GET" path="/api/platformhub/github/installations"} + +**Query Parameters** + +- **`excludeConnected`** :span[boolean]{.type-label} + +**Response** + +`200` — List of GitHub organisations accessible to the current GitHub OAuth user + +- **`Installations`** :span[array of object]{.type-label} + - **`AccountAvatarUrl`** :span[string]{.type-label} + - **`AccountId`** :span[string]{.type-label} + - **`AccountLogin`** :span[string]{.type-label} + - **`AccountType`** :span[string]{.type-label} + - **`AllRepositories`** :span[boolean]{.type-label} + true if the installation has access to all repositories in the account, false if it has access to only selected repositories. + - **`InstallationId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Installations": [ + { + "AccountAvatarUrl": "string", + "AccountId": "string", + "AccountLogin": "string", + "AccountType": "string", + "AllRepositories": true, + "InstallationId": "string" + } + ] +} +``` +::: + +## Get platform hub version control settings configuration + +:endpoint{method="GET" path="/api/platformhub/versioncontrol"} + +**Response** + +`200` — The version control settings for the Platform Hub + +- **`BasePath`** :span[string]{.type-label} +- **`Credentials`** :span[object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `Anonymous`, `UsernamePassword`, `Reference`, `GitHub`, `SshKey`. +- **`DefaultBranch`** :span[string]{.type-label} +- **`Url`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "BasePath": "string", + "Credentials": { + "Type": "Anonymous" + }, + "DefaultBranch": "string", + "Url": "string" +} +``` +::: + +## Update the platform hub's existing version control settings configuration + +:endpoint{method="PUT" path="/api/platformhub/versioncontrol"} + +**Request Body** + +- **`BasePath`** :span[string]{.type-label} *(required)* +- **`Credentials`** :span[object]{.type-label} *(required)* + - **`Type`** :span[enum]{.type-label} + Allowed values: `Anonymous`, `UsernamePassword`, `Reference`, `GitHub`, `SshKey`. +- **`DefaultBranch`** :span[string]{.type-label} *(required)* +- **`Url`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "BasePath": "string", + "Credentials": { + "Type": "Anonymous" + }, + "DefaultBranch": "string", + "Url": "string" +} +``` +::: + +**Response** + +`200` — The version control settings for the Platform Hub + +- **`BasePath`** :span[string]{.type-label} +- **`Credentials`** :span[object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `Anonymous`, `UsernamePassword`, `Reference`, `GitHub`, `SshKey`. +- **`DefaultBranch`** :span[string]{.type-label} +- **`Url`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "BasePath": "string", + "Credentials": { + "Type": "Anonymous" + }, + "DefaultBranch": "string", + "Url": "string" +} +``` +::: + +## Get a paginated list of process templates from the specified Git reference (sorted by name) + +:endpoint{method="GET" path="/api/platformhub/\{gitRef\}/processtemplates"} + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — A paginated list of process templates (sorted by name). + +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`ProcessTemplates`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`Icon`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Parameters`** :span[array of object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`Steps`** :span[array of object]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemsPerPage": 0, + "ProcessTemplates": [ + { + "Description": "string", + "GitRef": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "Name": "string", + "Parameters": [ + {} + ], + "Slug": "string", + "Steps": [ + {} + ] + } + ], + "TotalResults": 0 +} +``` +::: diff --git a/src/pages/docs/api/process-templates.md b/src/pages/docs/api/process-templates.md new file mode 100644 index 0000000000..575bcb6d12 --- /dev/null +++ b/src/pages/docs/api/process-templates.md @@ -0,0 +1,944 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Process Templates +--- + +## Get the sharing configuration for a given process template + +:endpoint{method="GET" path="/api/platformhub/processtemplates/\{slug\}/share"} + +**Path Parameters** + +- **`slug`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The sharing configuration of the requested process template + +- **`IndividuallySharedSpaceIds`** :span[array of string]{.type-label} +- **`SharedToAllSpaces`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "IndividuallySharedSpaceIds": [ + "string" + ], + "SharedToAllSpaces": true +} +``` +::: + +## List the process template versions for a given process template + +:endpoint{method="GET" path="/api/platformhub/processtemplates/\{slug\}/versions"} + +**Path Parameters** + +- **`slug`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`fromPublishedDate`** :span[string]{.type-label} + Format `date-time`. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`toPublishedDate`** :span[string]{.type-label} + Format `date-time`. +- **`versionMask`** :span[string]{.type-label} + +**Response** + +`200` — The requested process template version + +- **`Description`** :span[string]{.type-label} +- **`GitCommit`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} + Minimum length 1. +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} +- **`IsPreRelease`** :span[boolean]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Parameters`** :span[array of object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`IsOptional`** :span[boolean]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Values`** :span[array of object]{.type-label} +- **`PublishedDate`** :span[string]{.type-label} + Format `date-time`. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +[ + { + "Description": "string", + "GitCommit": "string", + "GitRef": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsPreRelease": true, + "Name": "string", + "Parameters": [ + { + "DisplaySettings": {}, + "HelpText": "string", + "IsOptional": true, + "Label": "string", + "Name": "string", + "Values": [ + {} + ] + } + ], + "PublishedDate": "2020-01-01T00:00:00.000Z", + "Slug": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": {}, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": "string" + } +] +``` +::: + +## Retrieve a single published process template and its version by version mask (no space context) + +:endpoint{method="GET" path="/api/platformhub/processtemplates/\{slug\}/\{versionMask\}"} + +**Path Parameters** + +- **`slug`** :span[string]{.type-label} *(required)* +- **`versionMask`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested published process template and its version + +- **`ProcessTemplate`** :span[object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`Icon`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Parameters`** :span[array of object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`Steps`** :span[array of object]{.type-label} +- **`ProcessTemplateVersion`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "ProcessTemplate": { + "Description": "string", + "GitRef": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "Name": "string", + "Parameters": [ + { + "DisplaySettings": {}, + "HelpText": "string", + "IsOptional": true, + "Label": "string", + "Name": "string", + "Values": [ + {} + ] + } + ], + "Slug": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": {}, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ] + }, + "ProcessTemplateVersion": "string" +} +``` +::: + +## Create a new process template in the provided source + +:endpoint{method="POST" path="/api/platformhub/\{gitRef\}/processtemplates"} + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChangeDescription`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "ChangeDescription": "string", + "Description": "string", + "GitRef": "string", + "Name": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Description`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`Parameters`** :span[array of object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`IsOptional`** :span[boolean]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Values`** :span[array of object]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "GitRef": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "Name": "string", + "Parameters": [ + { + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "IsOptional": true, + "Label": "string", + "Name": "string", + "Values": [ + {} + ] + } + ], + "Slug": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ] +} +``` +::: + +## Get a single process template by slug + +:endpoint{method="GET" path="/api/platformhub/\{gitRef\}/processtemplates/\{slug\}"} + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`slug`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +- **`Description`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`Parameters`** :span[array of object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`IsOptional`** :span[boolean]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Values`** :span[array of object]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "GitRef": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "Name": "string", + "Parameters": [ + { + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "IsOptional": true, + "Label": "string", + "Name": "string", + "Values": [ + {} + ] + } + ], + "Slug": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ] +} +``` +::: + +## Share new process template to spaces + +:endpoint{method="POST" path="/api/platformhub/\{gitRef\}/processtemplates/\{slug\}/share"} + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`slug`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`IndividuallySharedSpaceIds`** :span[array of string]{.type-label} *(required)* +- **`ShareToAllSpaces`** :span[boolean]{.type-label} *(required)* +- **`Slug`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "GitRef": "string", + "IndividuallySharedSpaceIds": [ + "string" + ], + "ShareToAllSpaces": true, + "Slug": "string" +} +``` +::: + +**Response** + +`200` — Response containing the results of the share process template command + +- **`IndividuallySharedSpaceIds`** :span[array of string]{.type-label} +- **`IndividuallyUnsharedSpaceIds`** :span[array of string]{.type-label} +- **`SharedToAllSpaces`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "IndividuallySharedSpaceIds": [ + "string" + ], + "IndividuallyUnsharedSpaceIds": [ + "string" + ], + "SharedToAllSpaces": true +} +``` +::: + +## Get all the available variable names for a process template + +:endpoint{method="GET" path="/api/platformhub/\{gitRef\}/processtemplates/\{slug\}/variables/names"} + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`slug`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +[ + "string" +] +``` +::: + +## Create a process template version + +:endpoint{method="POST" path="/api/platformhub/\{gitRef\}/processtemplates/\{slug\}/versions"} + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`slug`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`IsPreRelease`** :span[boolean]{.type-label} *(required)* +- **`Slug`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Version`** :span[string]{.type-label} *(required)* + The version of the process template. Must follow the semantic versioning format. Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "GitRef": "string", + "IsPreRelease": true, + "Slug": "string", + "Version": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Description`** :span[string]{.type-label} +- **`GitCommit`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} + Minimum length 1. +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} +- **`IsPreRelease`** :span[boolean]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Parameters`** :span[array of object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`IsOptional`** :span[boolean]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Values`** :span[array of object]{.type-label} +- **`PublishedDate`** :span[string]{.type-label} + Format `date-time`. +- **`Slug`** :span[string]{.type-label} + Minimum length 1. +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "GitCommit": "string", + "GitRef": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsPreRelease": true, + "Name": "string", + "Parameters": [ + { + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "IsOptional": true, + "Label": "string", + "Name": "string", + "Values": [ + {} + ] + } + ], + "PublishedDate": "2020-01-01T00:00:00.000Z", + "Slug": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": "string" +} +``` +::: + +## Modify an existing process template + +:endpoint{method="PUT" path="/api/platformhub/\{gitref\}/processtemplates/\{slug\}"} + +**Path Parameters** + +- **`gitref`** :span[string]{.type-label} *(required)* +- **`slug`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChangeDescription`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Parameters`** :span[array of object]{.type-label} *(required)* + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`IsOptional`** :span[boolean]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Values`** :span[array of object]{.type-label} +- **`Slug`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Steps`** :span[array of object]{.type-label} *(required)* + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. + +:::api-example{label="Request"} +```json +{ + "ChangeDescription": "string", + "Description": "string", + "GitRef": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Name": "string", + "Parameters": [ + { + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "IsOptional": true, + "Label": "string", + "Name": "string", + "Values": [ + {} + ] + } + ], + "Slug": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ] +} +``` +::: + +**Response** + +`200` — Success + +- **`Description`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`Parameters`** :span[array of object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`IsOptional`** :span[boolean]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Values`** :span[array of object]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "GitRef": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "Name": "string", + "Parameters": [ + { + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "IsOptional": true, + "Label": "string", + "Name": "string", + "Values": [ + {} + ] + } + ], + "Slug": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ] +} +``` +::: + +## Delete an existing process template + +:endpoint{method="DELETE" path="/api/platformhub/\{gitref\}/processtemplates/\{slug\}"} + +**Path Parameters** + +- **`gitref`** :span[string]{.type-label} *(required)* +- **`slug`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChangeDescription`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`Slug`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "ChangeDescription": "string", + "GitRef": "string", + "Slug": "string" +} +``` +::: + +**Response** + +`200` — Success + +## Retrieve a single process template and its version by version mask + +:endpoint{method="GET" path="/api/\{spaceId\}/processtemplates/\{slug\}/\{versionMask\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/processtemplates/{slug}/{versionMask}`. + +**Path Parameters** + +- **`slug`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* +- **`versionMask`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested process template and its version + +- **`ProcessTemplate`** :span[object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`Icon`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Parameters`** :span[array of object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`Steps`** :span[array of object]{.type-label} +- **`ProcessTemplateVersion`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "ProcessTemplate": { + "Description": "string", + "GitRef": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "Name": "string", + "Parameters": [ + { + "DisplaySettings": {}, + "HelpText": "string", + "IsOptional": true, + "Label": "string", + "Name": "string", + "Values": [ + {} + ] + } + ], + "Slug": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": {}, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ] + }, + "ProcessTemplateVersion": "string" +} +``` +::: + +## Get the icon for a given process template version + +:endpoint{method="GET" path="/api/\{spaceId\}/processtemplates/\{slug\}/\{versionMask\}/icon"} + +Also reachable at `/api/spaces/{spaceIdentifier}/processtemplates/{slug}/{versionMask}/icon`. + +**Path Parameters** + +- **`slug`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* +- **`versionMask`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: diff --git a/src/pages/docs/api/progression.md b/src/pages/docs/api/progression.md new file mode 100644 index 0000000000..ba1a7c23ea --- /dev/null +++ b/src/pages/docs/api/progression.md @@ -0,0 +1,666 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Progression +--- + +## Return a list of runbook dashboard items, filtered by various criteria including projectIds, environmentIds, tenantIds, tenantTags, runbookIds, runbookTags, taskIds + +:endpoint{method="GET" path="/api/\{spaceId\}/progression/runbooks/taskRuns"} + +Also reachable at `/api/progression/runbooks/taskRuns`, `/api/spaces/{spaceIdentifier}/progression/runbooks/taskRuns`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the space. + +**Query Parameters** + +- **`environmentIds`** :span[array of string]{.type-label} +- **`projectIds`** :span[array of string]{.type-label} +- **`runbookIds`** :span[array of string]{.type-label} +- **`runbookTags`** :span[array of string]{.type-label} +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`taskIds`** :span[array of string]{.type-label} +- **`tenantIds`** :span[array of string]{.type-label} +- **`tenantTags`** :span[array of string]{.type-label} + +**Response** + +`200` — The list of runbook dashboard items + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`CompletedTime`** :span[string]{.type-label} + Format `date-time`. + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`Duration`** :span[string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ErrorMessage`** :span[string]{.type-label} + - **`GitReference`** :span[object]{.type-label} + - **`HasPendingInterruptions`** :span[boolean]{.type-label} + - **`HasPendingPreconditions`** :span[boolean]{.type-label} + - **`HasWarningsOrErrors`** :span[boolean]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsCompleted`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`PendingInterruptionTypes`** :span[array of enum]{.type-label} + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. + - **`PendingPreconditionTypes`** :span[array of string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + Format `date-time`. + - **`RunBy`** :span[string]{.type-label} + - **`RunName`** :span[string]{.type-label} + - **`RunbookId`** :span[string]{.type-label} + - **`RunbookSnapshotId`** :span[string]{.type-label} + - **`RunbookSnapshotName`** :span[string]{.type-label} + - **`RunbookSnapshotNotes`** :span[string]{.type-label} + - **`StartTime`** :span[string]{.type-label} + Format `date-time`. + - **`State`** :span[enum]{.type-label} + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. + - **`TaskId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Created": "2020-01-01T00:00:00.000Z", + "Duration": "string", + "EnvironmentId": "string", + "ErrorMessage": "string", + "GitReference": { + "GitCommit": "string", + "GitRef": "string" + }, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "RunBy": "string", + "RunName": "string", + "RunbookId": "string", + "RunbookSnapshotId": "string", + "RunbookSnapshotName": "string", + "RunbookSnapshotNotes": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued", + "TaskId": "string", + "TenantId": "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 +} +``` +::: + +## Get the progress of a runbook in the environment lifecycle + +:endpoint{method="GET" path="/api/\{spaceId\}/progression/runbooks/\{runbookId\}"} + +Also reachable at `/api/progression/runbooks/{runbookId}`, `/api/spaces/{spaceIdentifier}/progression/runbooks/{runbookId}`. + +**Path Parameters** + +- **`runbookId`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Runbook Progression information + +- **`Environments`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`RunbookRuns`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Environments": [ + { + "Id": "string", + "Name": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "RunbookRuns": { + "additionalProp1": [ + { + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Created": "2020-01-01T00:00:00.000Z", + "Duration": "string", + "EnvironmentId": "string", + "ErrorMessage": "string", + "GitReference": {}, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {}, + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "RunBy": "string", + "RunName": "string", + "RunbookId": "string", + "RunbookSnapshotId": "string", + "RunbookSnapshotName": "string", + "RunbookSnapshotNotes": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued", + "TaskId": "string", + "TenantId": "string" + } + ], + "additionalProp2": [ + { + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Created": "2020-01-01T00:00:00.000Z", + "Duration": "string", + "EnvironmentId": "string", + "ErrorMessage": "string", + "GitReference": {}, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {}, + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "RunBy": "string", + "RunName": "string", + "RunbookId": "string", + "RunbookSnapshotId": "string", + "RunbookSnapshotName": "string", + "RunbookSnapshotNotes": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued", + "TaskId": "string", + "TenantId": "string" + } + ], + "additionalProp3": [ + { + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Created": "2020-01-01T00:00:00.000Z", + "Duration": "string", + "EnvironmentId": "string", + "ErrorMessage": "string", + "GitReference": {}, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {}, + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "RunBy": "string", + "RunName": "string", + "RunbookId": "string", + "RunbookSnapshotId": "string", + "RunbookSnapshotName": "string", + "RunbookSnapshotNotes": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued", + "TaskId": "string", + "TenantId": "string" + } + ] + } +} +``` +::: + +## Get the progress of a runbook in the environment lifecycle + +:endpoint{method="GET" path="/api/\{spaceId\}/progression/runbooks/\{runbookId\}/v1"} + +Also reachable at `/api/progression/runbooks/{runbookId}/v1`, `/api/spaces/{spaceIdentifier}/progression/runbooks/{runbookId}/v1`. + +**Path Parameters** + +- **`runbookId`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Runbook Progression information + +- **`Progression`** :span[object]{.type-label} + - **`Environments`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`RunbookRuns`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Progression": { + "Environments": [ + { + "Id": "string", + "Name": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "RunbookRuns": { + "additionalProp1": [ + {} + ], + "additionalProp2": [ + {} + ], + "additionalProp3": [ + {} + ] + } + } +} +``` +::: + +## Get the progress of a release in the environment lifecycle + +:endpoint{method="GET" path="/api/\{spaceId\}/progression/\{projectId\}"} + +Also reachable at `/api/progression/{projectId}`, `/api/projects/{projectId}/progression`, `/api/spaces/{spaceIdentifier}/progression/{projectId}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/progression`, `/api/{spaceId}/projects/{projectId}/progression`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`releaseHistoryCount`** :span[integer]{.type-label} + Number of releases to include per environment/channel/tenant combination. Defaults to 3. Maximum allowed is 100. Minimum `1`. Maximum `100`. + +**Response** + +`200` — The requested Project Progression information + +- **`ChannelEnvironments`** :span[object]{.type-label} +- **`Environments`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LifecycleEnvironments`** :span[object]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Releases`** :span[array of object]{.type-label} + - **`Channel`** :span[object]{.type-label} + - **`Deployments`** :span[object]{.type-label} + - **`HasUnresolvedDefect`** :span[boolean]{.type-label} + - **`NextDeployments`** :span[array of string]{.type-label} + - **`Release`** :span[object]{.type-label} + - **`ReleaseRetentionPeriod`** :span[object]{.type-label} + - **`TentacleRetentionPeriod`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ChannelEnvironments": { + "additionalProp1": [ + { + "Id": "string", + "Name": "string" + } + ], + "additionalProp2": [ + { + "Id": "string", + "Name": "string" + } + ], + "additionalProp3": [ + { + "Id": "string", + "Name": "string" + } + ] + }, + "Environments": [ + { + "Id": "string", + "Name": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleEnvironments": { + "additionalProp1": [ + { + "Id": "string", + "Name": "string" + } + ], + "additionalProp2": [ + { + "Id": "string", + "Name": "string" + } + ], + "additionalProp3": [ + { + "Id": "string", + "Name": "string" + } + ] + }, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Releases": [ + { + "Channel": { + "AutomaticEphemeralEnvironmentDeployments": true, + "CustomFieldDefinitions": [ + {} + ], + "Description": "string", + "EphemeralEnvironmentNameTemplate": "string", + "GitReferenceRules": [ + "string" + ], + "GitResourceRules": [ + {} + ], + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": {}, + "Name": "string", + "ParentEnvironmentId": "string", + "ProjectId": "string", + "Rules": [ + {} + ], + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ], + "Type": "string" + }, + "Deployments": { + "additionalProp1": [ + {} + ], + "additionalProp2": [ + {} + ], + "additionalProp3": [ + {} + ] + }, + "HasUnresolvedDefect": true, + "NextDeployments": [ + "string" + ], + "Release": { + "Assembled": "2020-01-01T00:00:00.000Z", + "BuildInformation": [ + {} + ], + "ChannelId": "string", + "CustomFields": {}, + "Id": "string", + "IgnoreChannelRules": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": {}, + "ProjectDeploymentProcessSnapshotId": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "ReleaseNotes": "string", + "SelectedGitResources": [ + {} + ], + "SelectedPackages": [ + {} + ], + "SpaceId": "string", + "Version": "string", + "VersionControlReference": {} + }, + "ReleaseRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + } + } + ] +} +``` +::: + +## Get the progress of a release in the environment lifecycle + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/progression/v1"} + +Also reachable at `/api/projects/{projectId}/progression/v1`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/progression/v1`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`releaseHistoryCount`** :span[integer]{.type-label} + Number of releases to include per environment/channel/tenant combination. Defaults to 3. Maximum allowed is 100. Minimum `1`. Maximum `100`. + +**Response** + +`200` — The requested Project Progression information + +- **`Progression`** :span[object]{.type-label} + - **`ChannelEnvironments`** :span[object]{.type-label} + - **`Environments`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LifecycleEnvironments`** :span[object]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Releases`** :span[array of object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Progression": { + "ChannelEnvironments": { + "additionalProp1": [ + {} + ], + "additionalProp2": [ + {} + ], + "additionalProp3": [ + {} + ] + }, + "Environments": [ + { + "Id": "string", + "Name": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleEnvironments": { + "additionalProp1": [ + {} + ], + "additionalProp2": [ + {} + ], + "additionalProp3": [ + {} + ] + }, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Releases": [ + { + "Channel": {}, + "Deployments": {}, + "HasUnresolvedDefect": true, + "NextDeployments": [ + "string" + ], + "Release": {}, + "ReleaseRetentionPeriod": {}, + "TentacleRetentionPeriod": {} + } + ] + } +} +``` +::: diff --git a/src/pages/docs/api/project-groups.md b/src/pages/docs/api/project-groups.md new file mode 100644 index 0000000000..d9240eb651 --- /dev/null +++ b/src/pages/docs/api/project-groups.md @@ -0,0 +1,587 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Project Groups +--- + +## Get a paginated list of the Project Groups in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name + +:endpoint{method="GET" path="/api/\{spaceId\}/projectgroups"} + +Also reachable at `/api/projectgroups`, `/api/spaces/{spaceIdentifier}/projectgroups`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + A comma separated list of Project Group IDs to filter on. +- **`name`** :span[string]{.type-label} + The exact name of a Project Group to be matched. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to limit the set of retrieved Project Groups to. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — A paginated list of the Project Groups in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`EnvironmentIds`** :span[array of string]{.type-label} + Gets or sets a collection of environment ID's. If this collection is empty, projects in this group can be deployed to any environment. If the collection is non-empty, then projects in the group are limited to only deploying to the environments listed in this collection. Obsolete. Environments are now controlled by lifecycles as of Oct 2014, version 2.6.5. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this project group. + - **`RetentionPolicyId`** :span[string]{.type-label} + Gets or sets the ID of the retention policy that will apply to projects in this group. + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Description": "string", + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "RetentionPolicyId": "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 +} +``` +::: + +## Create a new project group + +:endpoint{method="POST" path="/api/\{spaceId\}/projectgroups"} + +Also reachable at `/api/projectgroups`, `/api/spaces/{spaceIdentifier}/projectgroups`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Description`** :span[string]{.type-label} + The description of the project group. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the project group. Minimum length 1. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Name": "string", + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Description`** :span[string]{.type-label} +- **`EnvironmentIds`** :span[array of string]{.type-label} + Gets or sets a collection of environment ID's. If this collection is empty, projects in this group can be deployed to any environment. If the collection is non-empty, then projects in the group are limited to only deploying to the environments listed in this collection. Obsolete. Environments are now controlled by lifecycles as of Oct 2014, version 2.6.5. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this project group. +- **`RetentionPolicyId`** :span[string]{.type-label} + Gets or sets the ID of the retention policy that will apply to projects in this group. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "RetentionPolicyId": "string", + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +## List the name and ID of all of the Project Groups in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name + +:endpoint{method="GET" path="/api/\{spaceId\}/projectgroups/all"} + +Also reachable at `/api/projectgroups/all`, `/api/spaces/{spaceIdentifier}/projectgroups/all`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The name and ID of all of the Project Groups in the supplied Octopus Deploy Space. The results are sorted alphabetically by name." + +- **`Description`** :span[string]{.type-label} +- **`EnvironmentIds`** :span[array of string]{.type-label} + Gets or sets a collection of environment ID's. If this collection is empty, projects in this group can be deployed to any environment. If the collection is non-empty, then projects in the group are limited to only deploying to the environments listed in this collection. Obsolete. Environments are now controlled by lifecycles as of Oct 2014, version 2.6.5. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this project group. +- **`RetentionPolicyId`** :span[string]{.type-label} + Gets or sets the ID of the retention policy that will apply to projects in this group. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Description": "string", + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "RetentionPolicyId": "string", + "Slug": "string", + "SpaceId": "string" + } +] +``` +::: + +## Get a Project Group by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/projectgroups/\{id\}"} + +Also reachable at `/api/projectgroups/{id}`, `/api/spaces/{spaceIdentifier}/projectgroups/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the ProjectGroup to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested project group + +- **`Description`** :span[string]{.type-label} +- **`EnvironmentIds`** :span[array of string]{.type-label} + Gets or sets a collection of environment ID's. If this collection is empty, projects in this group can be deployed to any environment. If the collection is non-empty, then projects in the group are limited to only deploying to the environments listed in this collection. Obsolete. Environments are now controlled by lifecycles as of Oct 2014, version 2.6.5. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this project group. +- **`RetentionPolicyId`** :span[string]{.type-label} + Gets or sets the ID of the retention policy that will apply to projects in this group. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "RetentionPolicyId": "string", + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +## Modify an existing project group + +:endpoint{method="PUT" path="/api/\{spaceId\}/projectgroups/\{id\}"} + +Also reachable at `/api/projectgroups/{id}`, `/api/spaces/{spaceIdentifier}/projectgroups/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the project group. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Description`** :span[string]{.type-label} + The description of the project group. +- **`Id`** :span[string]{.type-label} *(required)* + The ID of the project group. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the project group. Minimum length 1. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Id": "string", + "Name": "string", + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — The modified project group + +- **`Description`** :span[string]{.type-label} +- **`EnvironmentIds`** :span[array of string]{.type-label} + Gets or sets a collection of environment ID's. If this collection is empty, projects in this group can be deployed to any environment. If the collection is non-empty, then projects in the group are limited to only deploying to the environments listed in this collection. Obsolete. Environments are now controlled by lifecycles as of Oct 2014, version 2.6.5. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this project group. +- **`RetentionPolicyId`** :span[string]{.type-label} + Gets or sets the ID of the retention policy that will apply to projects in this group. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "RetentionPolicyId": "string", + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +## Delete an existing Project Group + +:endpoint{method="DELETE" path="/api/\{spaceId\}/projectgroups/\{id\}"} + +Also reachable at `/api/projectgroups/{id}`, `/api/spaces/{spaceIdentifier}/projectgroups/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the project group to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Get a paginated list of the Projects that belong to the given Project Group + +:endpoint{method="GET" path="/api/\{spaceId\}/projectgroups/\{id\}/projects"} + +Also reachable at `/api/projectgroups/{id}/projects`, `/api/spaces/{spaceIdentifier}/projectgroups/{id}/projects`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the project group. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — A paginated list of the Projects that belong to the given Project Group + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`AllowIgnoreChannelRules`** :span[boolean]{.type-label} + - **`AutoCreateRelease`** :span[boolean]{.type-label} + - **`AutoDeployReleaseOverrides`** :span[array of object]{.type-label} + - **`ClonedFromProjectId`** :span[string]{.type-label} + - **`CombineHealthAndSyncStatusInDashboardLiveStatus`** :span[boolean]{.type-label} + - **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. + - **`DefaultPowerShellEdition`** :span[string]{.type-label} + - **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} + - **`DeploymentChangesTemplate`** :span[string]{.type-label} + - **`DeploymentProcessId`** :span[string]{.type-label} + - **`DeprovisioningRunbookId`** :span[string]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`DiscreteChannelRelease`** :span[boolean]{.type-label} + Treats releases of different channels to the same environment as a seperate deployment dimension. 'False' indicates a "hotfix"-style usage of channels (single release active per environment ignoring channels), whereas `True` indicates "microservice"-style usage (single release per environment per channel). + - **`ExecuteDeploymentsOnEventBasedPipeline`** :span[boolean]{.type-label} + - **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`Icon`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IncludedLibraryVariableSetIds`** :span[array of string]{.type-label} + Library variable sets included in the project. Sets are listed in order of precedence, with earlier items in the list overriding any variables with the same name and scope definition appearing later in the list. + - **`IsBadgesEnabled`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`IsVersionControlled`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LifecycleId`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`PersistenceSettings`** :span[object]{.type-label} + - **`ProjectConnectivityPolicy`** :span[object]{.type-label} + - **`ProjectGroupId`** :span[string]{.type-label} + - **`ProjectTags`** :span[array of string]{.type-label} + List of tags assigned to this project. + - **`ProjectTemplateDetails`** :span[object]{.type-label} + - **`ProvisioningRunbookId`** :span[string]{.type-label} + - **`ReleaseCreationStrategy`** :span[object]{.type-label} + - **`ReleaseNotesTemplate`** :span[string]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Templates`** :span[array of object]{.type-label} + - **`TenantedDeploymentMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + - **`VariableSetId`** :span[string]{.type-label} + - **`VersioningStrategy`** :span[object]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "AllowIgnoreChannelRules": true, + "AutoCreateRelease": true, + "AutoDeployReleaseOverrides": [ + {} + ], + "ClonedFromProjectId": "string", + "CombineHealthAndSyncStatusInDashboardLiveStatus": true, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultPowerShellEdition": "string", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "DeploymentProcessId": "string", + "DeprovisioningRunbookId": "string", + "Description": "string", + "DiscreteChannelRelease": true, + "ExecuteDeploymentsOnEventBasedPipeline": true, + "ExtensionSettings": [ + {} + ], + "ForcePackageDownload": true, + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IncludedLibraryVariableSetIds": [ + "string" + ], + "IsBadgesEnabled": true, + "IsDisabled": true, + "IsVersionControlled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PersistenceSettings": { + "Type": "Database" + }, + "ProjectConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "ProjectGroupId": "string", + "ProjectTags": [ + "string" + ], + "ProjectTemplateDetails": { + "IsShared": true, + "Slug": "string", + "VersionMask": "string" + }, + "ProvisioningRunbookId": "string", + "ReleaseCreationStrategy": { + "ChannelId": "string", + "ReleaseCreationPackage": {} + }, + "ReleaseNotesTemplate": "string", + "Slug": "string", + "SpaceId": "string", + "Templates": [ + {} + ], + "TenantedDeploymentMode": "Untenanted", + "VariableSetId": "string", + "VersioningStrategy": { + "DonorPackage": {}, + "Template": "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 +} +``` +::: diff --git a/src/pages/docs/api/project-templates.md b/src/pages/docs/api/project-templates.md new file mode 100644 index 0000000000..1b5624eaf2 --- /dev/null +++ b/src/pages/docs/api/project-templates.md @@ -0,0 +1,58 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Project Templates +--- + +## Share a project template to spaces + +:endpoint{method="POST" path="/api/platformhub/\{gitRef\}/projecttemplates/\{slug\}/share"} + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`slug`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`IndividuallySharedSpaceIds`** :span[array of string]{.type-label} *(required)* +- **`ShareToAllSpaces`** :span[boolean]{.type-label} *(required)* +- **`Slug`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "GitRef": "string", + "IndividuallySharedSpaceIds": [ + "string" + ], + "ShareToAllSpaces": true, + "Slug": "string" +} +``` +::: + +**Response** + +`200` — Response containing the results of the share project template command + +- **`IndividuallySharedSpaceIds`** :span[array of string]{.type-label} +- **`IndividuallyUnsharedSpaceIds`** :span[array of string]{.type-label} +- **`SharedToAllSpaces`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "IndividuallySharedSpaceIds": [ + "string" + ], + "IndividuallyUnsharedSpaceIds": [ + "string" + ], + "SharedToAllSpaces": true +} +``` +::: diff --git a/src/pages/docs/api/project-triggers.md b/src/pages/docs/api/project-triggers.md new file mode 100644 index 0000000000..4dbe5adf38 --- /dev/null +++ b/src/pages/docs/api/project-triggers.md @@ -0,0 +1,1136 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Project Triggers +--- + +## Get Project Triggers within a given Project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/triggers"} + +Also reachable at `/api/projects/{projectId}/triggers`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/triggers`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project to get Project Triggers for. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`runbookTags`** :span[array of string]{.type-label} + A list of Runbook Tags to filter tag based triggers. Tag based triggers matching any of these tags will be included. +- **`runbooks`** :span[array of string]{.type-label} + A list of Runbook IDs, to limit the matching of Project Triggers to those with a particular Runbook ID. Example: ["Runbooks-1", "Runbooks-2"]. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`triggerActionCategory`** :span[enum]{.type-label} + Filters the Project Triggers using the specified Trigger Action Category. + Allowed values: `Deployment`, `Runbook`. +- **`triggerActionType`** :span[enum]{.type-label} + Filters the Project Triggers using the specified Trigger Action Type. + Allowed values: `AutoDeploy`, `DeployLatestRelease`, `DeployNewRelease`, `DeployLatestReleaseToEnvironment`, `RunRunbook`, `CreateRelease`. + +**Response** + +`200` — The requested list of Project Triggers + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Action`** :span[object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Filter`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Action": { + "ActionType": "AutoDeploy", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {} + }, + "Description": "string", + "Filter": { + "FilterType": "MachineFilter", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {} + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectId": "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 +} +``` +::: + +## Create a new project trigger + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/triggers"} + +Also reachable at `/api/projects/{projectId}/triggers`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/triggers`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + Id of the project to create a trigger in. +- **`spaceId`** :span[string]{.type-label} *(required)* + Id of the space where the project is located. + +**Request Body** + +- **`Action`** :span[object]{.type-label} *(required)* + - **`ActionType`** :span[enum]{.type-label} + Allowed values: `AutoDeploy`, `DeployLatestRelease`, `DeployNewRelease`, `DeployLatestReleaseToEnvironment`, `RunRunbook`, `CreateRelease`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Description`** :span[string]{.type-label} + Description for the project trigger. +- **`Filter`** :span[object]{.type-label} *(required)* + - **`FilterType`** :span[enum]{.type-label} + Allowed values: `MachineFilter`, `DailySchedule`, `DaysPerWeekSchedule`, `DaysPerMonthSchedule`, `CronExpressionSchedule`, `OnceDailySchedule`, `ContinuousDailySchedule`, `FeedFilter`, `ArcFeedFilter`, `GitFilter`, `WebhookFilter`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`IsDisabled`** :span[boolean]{.type-label} + Disables the trigger from being run when set. +- **`Name`** :span[string]{.type-label} *(required)* + Name of the project trigger. Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} *(required)* + Id of the project to create a trigger in. +- **`SpaceId`** :span[string]{.type-label} *(required)* + Id of the space where the project is located. + +:::api-example{label="Request"} +```json +{ + "Action": { + "ActionType": "AutoDeploy", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Description": "string", + "Filter": { + "FilterType": "MachineFilter", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "IsDisabled": true, + "Name": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Action`** :span[object]{.type-label} + - **`ActionType`** :span[enum]{.type-label} + Allowed values: `AutoDeploy`, `DeployLatestRelease`, `DeployNewRelease`, `DeployLatestReleaseToEnvironment`, `RunRunbook`, `CreateRelease`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Description`** :span[string]{.type-label} +- **`Filter`** :span[object]{.type-label} + - **`FilterType`** :span[enum]{.type-label} + Allowed values: `MachineFilter`, `DailySchedule`, `DaysPerWeekSchedule`, `DaysPerMonthSchedule`, `CronExpressionSchedule`, `OnceDailySchedule`, `ContinuousDailySchedule`, `FeedFilter`, `ArcFeedFilter`, `GitFilter`, `WebhookFilter`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Action": { + "ActionType": "AutoDeploy", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Description": "string", + "Filter": { + "FilterType": "MachineFilter", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +## Get project trigger by project id and trigger id + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/triggers/\{id\}"} + +Also reachable at `/api/projects/{projectId}/triggers/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/triggers/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Project Trigger to load. +- **`projectId`** :span[string]{.type-label} *(required)* + Id of the project that trigger is in. +- **`spaceId`** :span[string]{.type-label} *(required)* + Id of the space where the project is located. + +**Response** + +`200` — The requested Project Trigger + +- **`Action`** :span[object]{.type-label} + - **`ActionType`** :span[enum]{.type-label} + Allowed values: `AutoDeploy`, `DeployLatestRelease`, `DeployNewRelease`, `DeployLatestReleaseToEnvironment`, `RunRunbook`, `CreateRelease`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Description`** :span[string]{.type-label} +- **`Filter`** :span[object]{.type-label} + - **`FilterType`** :span[enum]{.type-label} + Allowed values: `MachineFilter`, `DailySchedule`, `DaysPerWeekSchedule`, `DaysPerMonthSchedule`, `CronExpressionSchedule`, `OnceDailySchedule`, `ContinuousDailySchedule`, `FeedFilter`, `ArcFeedFilter`, `GitFilter`, `WebhookFilter`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Action": { + "ActionType": "AutoDeploy", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Description": "string", + "Filter": { + "FilterType": "MachineFilter", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +## Modify a ProjectTriggerResource by ID + +:endpoint{method="PUT" path="/api/\{spaceId\}/projects/\{projectId\}/triggers/\{id\}"} + +Also reachable at `/api/projects/{projectId}/triggers/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/triggers/{id}`. + +Updates an existing project trigger + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the project trigger. +- **`projectId`** :span[string]{.type-label} *(required)* + ProjectId of the project trigger. +- **`spaceId`** :span[string]{.type-label} *(required)* + Id of the space where the project is located. + +**Request Body** + +- **`Action`** :span[object]{.type-label} + - **`ActionType`** :span[enum]{.type-label} + Allowed values: `AutoDeploy`, `DeployLatestRelease`, `DeployNewRelease`, `DeployLatestReleaseToEnvironment`, `RunRunbook`, `CreateRelease`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Description`** :span[string]{.type-label} + Description for the project trigger. +- **`Filter`** :span[object]{.type-label} + - **`FilterType`** :span[enum]{.type-label} + Allowed values: `MachineFilter`, `DailySchedule`, `DaysPerWeekSchedule`, `DaysPerMonthSchedule`, `CronExpressionSchedule`, `OnceDailySchedule`, `ContinuousDailySchedule`, `FeedFilter`, `ArcFeedFilter`, `GitFilter`, `WebhookFilter`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Id`** :span[string]{.type-label} *(required)* + Id of the project trigger. +- **`IsDisabled`** :span[boolean]{.type-label} + Disables the trigger from being run when set. +- **`Name`** :span[string]{.type-label} + Name of the project trigger. +- **`ProjectId`** :span[string]{.type-label} *(required)* + ProjectId of the project trigger. +- **`SpaceId`** :span[string]{.type-label} *(required)* + Id of the space where the project is located. + +:::api-example{label="Request"} +```json +{ + "Action": { + "ActionType": "AutoDeploy", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Description": "string", + "Filter": { + "FilterType": "MachineFilter", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Id": "string", + "IsDisabled": true, + "Name": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Modified project trigger resource response + +- **`Action`** :span[object]{.type-label} + - **`ActionType`** :span[enum]{.type-label} + Allowed values: `AutoDeploy`, `DeployLatestRelease`, `DeployNewRelease`, `DeployLatestReleaseToEnvironment`, `RunRunbook`, `CreateRelease`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Description`** :span[string]{.type-label} +- **`Filter`** :span[object]{.type-label} + - **`FilterType`** :span[enum]{.type-label} + Allowed values: `MachineFilter`, `DailySchedule`, `DaysPerWeekSchedule`, `DaysPerMonthSchedule`, `CronExpressionSchedule`, `OnceDailySchedule`, `ContinuousDailySchedule`, `FeedFilter`, `ArcFeedFilter`, `GitFilter`, `WebhookFilter`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Action": { + "ActionType": "AutoDeploy", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Description": "string", + "Filter": { + "FilterType": "MachineFilter", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +## Delete an existing Project Trigger + +:endpoint{method="DELETE" path="/api/\{spaceId\}/projects/\{projectId\}/triggers/\{id\}"} + +Also reachable at `/api/projects/{projectId}/triggers/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/triggers/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the project trigger to delete. +- **`projectId`** :span[string]{.type-label} *(required)* + Id of the project to create a trigger in. +- **`spaceId`** :span[string]{.type-label} *(required)* + Id of the space where the project is located. + +**Response** + +`200` — Confirmation that the Project Trigger was deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get a list of Project Triggers + +:endpoint{method="GET" path="/api/\{spaceId\}/projecttriggers"} + +Also reachable at `/api/projecttriggers`, `/api/spaces/{spaceIdentifier}/projecttriggers`. + +Gets all the Project Triggers in the supplied Octopus Deploy Space, sorted by Id + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`runbooks`** :span[array of string]{.type-label} + A list of Runbook IDs, to limit the matching of Project Triggers to those with a particular Runbook ID. Example: ["Runbooks-1", "Runbooks-2"]. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested list of Project Triggers + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Action`** :span[object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Filter`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Action": { + "ActionType": "AutoDeploy", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {} + }, + "Description": "string", + "Filter": { + "FilterType": "MachineFilter", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {} + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectId": "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 +} +``` +::: + +## Create a new project trigger + +:endpoint{method="POST" path="/api/\{spaceId\}/projecttriggers"} + +Also reachable at `/api/projecttriggers`, `/api/spaces/{spaceIdentifier}/projecttriggers`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + Id of the space where the project is located. + +**Request Body** + +- **`Action`** :span[object]{.type-label} *(required)* + - **`ActionType`** :span[enum]{.type-label} + Allowed values: `AutoDeploy`, `DeployLatestRelease`, `DeployNewRelease`, `DeployLatestReleaseToEnvironment`, `RunRunbook`, `CreateRelease`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Description`** :span[string]{.type-label} + Description for the project trigger. +- **`Filter`** :span[object]{.type-label} *(required)* + - **`FilterType`** :span[enum]{.type-label} + Allowed values: `MachineFilter`, `DailySchedule`, `DaysPerWeekSchedule`, `DaysPerMonthSchedule`, `CronExpressionSchedule`, `OnceDailySchedule`, `ContinuousDailySchedule`, `FeedFilter`, `ArcFeedFilter`, `GitFilter`, `WebhookFilter`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`IsDisabled`** :span[boolean]{.type-label} + Disables the trigger from being run when set. +- **`Name`** :span[string]{.type-label} *(required)* + Name of the project trigger. Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} *(required)* + Id of the project to create a trigger in. +- **`SpaceId`** :span[string]{.type-label} *(required)* + Id of the space where the project is located. + +:::api-example{label="Request"} +```json +{ + "Action": { + "ActionType": "AutoDeploy", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Description": "string", + "Filter": { + "FilterType": "MachineFilter", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "IsDisabled": true, + "Name": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Action`** :span[object]{.type-label} + - **`ActionType`** :span[enum]{.type-label} + Allowed values: `AutoDeploy`, `DeployLatestRelease`, `DeployNewRelease`, `DeployLatestReleaseToEnvironment`, `RunRunbook`, `CreateRelease`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Description`** :span[string]{.type-label} +- **`Filter`** :span[object]{.type-label} + - **`FilterType`** :span[enum]{.type-label} + Allowed values: `MachineFilter`, `DailySchedule`, `DaysPerWeekSchedule`, `DaysPerMonthSchedule`, `CronExpressionSchedule`, `OnceDailySchedule`, `ContinuousDailySchedule`, `FeedFilter`, `ArcFeedFilter`, `GitFilter`, `WebhookFilter`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Action": { + "ActionType": "AutoDeploy", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Description": "string", + "Filter": { + "FilterType": "MachineFilter", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +## Get a Project Trigger by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/projecttriggers/\{id\}"} + +Also reachable at `/api/projecttriggers/{id}`, `/api/spaces/{spaceIdentifier}/projecttriggers/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Project Trigger to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + Id of the space where the project is located. + +**Response** + +`200` — The requested Project Trigger + +- **`Action`** :span[object]{.type-label} + - **`ActionType`** :span[enum]{.type-label} + Allowed values: `AutoDeploy`, `DeployLatestRelease`, `DeployNewRelease`, `DeployLatestReleaseToEnvironment`, `RunRunbook`, `CreateRelease`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Description`** :span[string]{.type-label} +- **`Filter`** :span[object]{.type-label} + - **`FilterType`** :span[enum]{.type-label} + Allowed values: `MachineFilter`, `DailySchedule`, `DaysPerWeekSchedule`, `DaysPerMonthSchedule`, `CronExpressionSchedule`, `OnceDailySchedule`, `ContinuousDailySchedule`, `FeedFilter`, `ArcFeedFilter`, `GitFilter`, `WebhookFilter`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Action": { + "ActionType": "AutoDeploy", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Description": "string", + "Filter": { + "FilterType": "MachineFilter", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +## Modify a ProjectTriggerResource by ID + +:endpoint{method="PUT" path="/api/\{spaceId\}/projecttriggers/\{id\}"} + +Also reachable at `/api/projecttriggers/{id}`, `/api/spaces/{spaceIdentifier}/projecttriggers/{id}`. + +Updates an existing project trigger + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the project trigger. +- **`spaceId`** :span[string]{.type-label} *(required)* + Id of the space where the project is located. + +**Request Body** + +- **`Action`** :span[object]{.type-label} + - **`ActionType`** :span[enum]{.type-label} + Allowed values: `AutoDeploy`, `DeployLatestRelease`, `DeployNewRelease`, `DeployLatestReleaseToEnvironment`, `RunRunbook`, `CreateRelease`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Description`** :span[string]{.type-label} + Description for the project trigger. +- **`Filter`** :span[object]{.type-label} + - **`FilterType`** :span[enum]{.type-label} + Allowed values: `MachineFilter`, `DailySchedule`, `DaysPerWeekSchedule`, `DaysPerMonthSchedule`, `CronExpressionSchedule`, `OnceDailySchedule`, `ContinuousDailySchedule`, `FeedFilter`, `ArcFeedFilter`, `GitFilter`, `WebhookFilter`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Id`** :span[string]{.type-label} *(required)* + Id of the project trigger. +- **`IsDisabled`** :span[boolean]{.type-label} + Disables the trigger from being run when set. +- **`Name`** :span[string]{.type-label} + Name of the project trigger. +- **`ProjectId`** :span[string]{.type-label} *(required)* + ProjectId of the project trigger. +- **`SpaceId`** :span[string]{.type-label} *(required)* + Id of the space where the project is located. + +:::api-example{label="Request"} +```json +{ + "Action": { + "ActionType": "AutoDeploy", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Description": "string", + "Filter": { + "FilterType": "MachineFilter", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Id": "string", + "IsDisabled": true, + "Name": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Modified project trigger resource response + +- **`Action`** :span[object]{.type-label} + - **`ActionType`** :span[enum]{.type-label} + Allowed values: `AutoDeploy`, `DeployLatestRelease`, `DeployNewRelease`, `DeployLatestReleaseToEnvironment`, `RunRunbook`, `CreateRelease`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Description`** :span[string]{.type-label} +- **`Filter`** :span[object]{.type-label} + - **`FilterType`** :span[enum]{.type-label} + Allowed values: `MachineFilter`, `DailySchedule`, `DaysPerWeekSchedule`, `DaysPerMonthSchedule`, `CronExpressionSchedule`, `OnceDailySchedule`, `ContinuousDailySchedule`, `FeedFilter`, `ArcFeedFilter`, `GitFilter`, `WebhookFilter`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Action": { + "ActionType": "AutoDeploy", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Description": "string", + "Filter": { + "FilterType": "MachineFilter", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +## Delete an existing Project Trigger + +:endpoint{method="DELETE" path="/api/\{spaceId\}/projecttriggers/\{id\}"} + +Also reachable at `/api/projecttriggers/{id}`, `/api/spaces/{spaceIdentifier}/projecttriggers/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the project trigger to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + Id of the space where the project is located. + +**Response** + +`200` — Confirmation that the Project Trigger was deleted + +:::api-example{label="Response"} +```json +{} +``` +::: diff --git a/src/pages/docs/api/projects.md b/src/pages/docs/api/projects.md new file mode 100644 index 0000000000..9018d802f8 --- /dev/null +++ b/src/pages/docs/api/projects.md @@ -0,0 +1,1873 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Projects +--- + +## List all of the projects in the supplied Octopus Deploy Space, from all project groups. The results will be sorted alphabetically by name + +:endpoint{method="GET" path="/api/\{spaceId\}/projects"} + +Also reachable at `/api/projects`, `/api/spaces/{spaceIdentifier}/projects`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`clonedFromProjectId`** :span[string]{.type-label} +- **`ids`** :span[array of string]{.type-label} +- **`name`** :span[string]{.type-label} + (Obsolete) A partial or complete name to limit the set of retrieved Projects to. This will perform a "contains" style match against the supplied name or name-fragment. Left for backwards compatibility. +- **`partialName`** :span[string]{.type-label} + A partial name, to limit the set of Projects to those with a name that includes the partial name. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — List all of the projects in the supplied Octopus Deploy Space, from all project groups. The results will be sorted alphabetically by name. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`AllowIgnoreChannelRules`** :span[boolean]{.type-label} + - **`AutoCreateRelease`** :span[boolean]{.type-label} + - **`AutoDeployReleaseOverrides`** :span[array of object]{.type-label} + - **`ClonedFromProjectId`** :span[string]{.type-label} + - **`CombineHealthAndSyncStatusInDashboardLiveStatus`** :span[boolean]{.type-label} + - **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. + - **`DefaultPowerShellEdition`** :span[string]{.type-label} + - **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} + - **`DeploymentChangesTemplate`** :span[string]{.type-label} + - **`DeploymentProcessId`** :span[string]{.type-label} + - **`DeprovisioningRunbookId`** :span[string]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`DiscreteChannelRelease`** :span[boolean]{.type-label} + Treats releases of different channels to the same environment as a seperate deployment dimension. 'False' indicates a "hotfix"-style usage of channels (single release active per environment ignoring channels), whereas `True` indicates "microservice"-style usage (single release per environment per channel). + - **`ExecuteDeploymentsOnEventBasedPipeline`** :span[boolean]{.type-label} + - **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`Icon`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IncludedLibraryVariableSetIds`** :span[array of string]{.type-label} + Library variable sets included in the project. Sets are listed in order of precedence, with earlier items in the list overriding any variables with the same name and scope definition appearing later in the list. + - **`IsBadgesEnabled`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`IsVersionControlled`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LifecycleId`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`PersistenceSettings`** :span[object]{.type-label} + - **`ProjectConnectivityPolicy`** :span[object]{.type-label} + - **`ProjectGroupId`** :span[string]{.type-label} + - **`ProjectTags`** :span[array of string]{.type-label} + List of tags assigned to this project. + - **`ProjectTemplateDetails`** :span[object]{.type-label} + - **`ProvisioningRunbookId`** :span[string]{.type-label} + - **`ReleaseCreationStrategy`** :span[object]{.type-label} + - **`ReleaseNotesTemplate`** :span[string]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Templates`** :span[array of object]{.type-label} + - **`TenantedDeploymentMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + - **`VariableSetId`** :span[string]{.type-label} + - **`VersioningStrategy`** :span[object]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "AllowIgnoreChannelRules": true, + "AutoCreateRelease": true, + "AutoDeployReleaseOverrides": [ + {} + ], + "ClonedFromProjectId": "string", + "CombineHealthAndSyncStatusInDashboardLiveStatus": true, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultPowerShellEdition": "string", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "DeploymentProcessId": "string", + "DeprovisioningRunbookId": "string", + "Description": "string", + "DiscreteChannelRelease": true, + "ExecuteDeploymentsOnEventBasedPipeline": true, + "ExtensionSettings": [ + {} + ], + "ForcePackageDownload": true, + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IncludedLibraryVariableSetIds": [ + "string" + ], + "IsBadgesEnabled": true, + "IsDisabled": true, + "IsVersionControlled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PersistenceSettings": { + "Type": "Database" + }, + "ProjectConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "ProjectGroupId": "string", + "ProjectTags": [ + "string" + ], + "ProjectTemplateDetails": { + "IsShared": true, + "Slug": "string", + "VersionMask": "string" + }, + "ProvisioningRunbookId": "string", + "ReleaseCreationStrategy": { + "ChannelId": "string", + "ReleaseCreationPackage": {} + }, + "ReleaseNotesTemplate": "string", + "Slug": "string", + "SpaceId": "string", + "Templates": [ + {} + ], + "TenantedDeploymentMode": "Untenanted", + "VariableSetId": "string", + "VersioningStrategy": { + "DonorPackage": {}, + "Template": "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 +} +``` +::: + +## Create a new project + +:endpoint{method="POST" path="/api/\{spaceId\}/projects"} + +Also reachable at `/api/projects`, `/api/spaces/{spaceIdentifier}/projects`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`AllowIgnoreChannelRules`** :span[boolean]{.type-label} +- **`AutoCreateRelease`** :span[boolean]{.type-label} +- **`AutoDeployReleaseOverrides`** :span[array of object]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ReleaseId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`Clone`** :span[string]{.type-label} + ID of an existing project in the same space whose configuration (deployment process, variables, channels, runbooks, triggers) is copied into the new project. The source project must store its configuration in the database, not Git. +- **`CombineHealthAndSyncStatusInDashboardLiveStatus`** :span[boolean]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} +- **`DeploymentChangesTemplate`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`DiscreteChannelRelease`** :span[boolean]{.type-label} + Treats releases of different channels to the same environment as a seperate deployment dimension. 'False' indicates a "hotfix"-style usage of channels (single release active per environment ignoring channels), whereas `True` indicates "microservice"-style usage (single release per environment per channel). +- **`ExecuteDeploymentsOnEventBasedPipeline`** :span[boolean]{.type-label} +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`IncludedLibraryVariableSetIds`** :span[array of string]{.type-label} + Library variable sets included in the project. Sets are listed in order of precedence, with earlier items in the list overriding any variables with the same name and scope definition appearing later in the list. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LifecycleId`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`PersistenceSettings`** :span[object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `Database`, `VersionControlled`. +- **`ProjectConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`ProjectGroupId`** :span[string]{.type-label} *(required)* +- **`ProjectTags`** :span[array of string]{.type-label} + Tags to apply to the project, each written as "TagSet/Tag" using either the names or the IDs of the tag set and tag (for example "Regions/us-east"). Call find_tag_sets to discover which tag sets apply to projects and what tags they contain. +- **`ReleaseCreationStrategy`** :span[object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`ReleaseCreationPackage`** :span[object]{.type-label} +- **`ReleaseNotesTemplate`** :span[string]{.type-label} +- **`RetainTenantConnections`** :span[boolean]{.type-label} + When cloning, copy the source project's tenant connections to the new project. Only honoured when Clone is set. Defaults to false. +- **`Slug`** :span[string]{.type-label} + URL-friendly short identifier for the project, unique within the space (for example "web-store"). Leave unset to have one generated from the name. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`Templates`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`TenantedDeploymentMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`VersioningStrategy`** :span[object]{.type-label} + - **`DonorPackage`** :span[object]{.type-label} + - **`Template`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "AllowIgnoreChannelRules": true, + "AutoCreateRelease": true, + "AutoDeployReleaseOverrides": [ + { + "EnvironmentId": "string", + "ReleaseId": "string", + "TenantId": "string" + } + ], + "Clone": "string", + "CombineHealthAndSyncStatusInDashboardLiveStatus": true, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "Description": "string", + "DiscreteChannelRelease": true, + "ExecuteDeploymentsOnEventBasedPipeline": true, + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "ForcePackageDownload": true, + "IncludedLibraryVariableSetIds": [ + "string" + ], + "IsDisabled": true, + "LifecycleId": "string", + "Name": "string", + "PersistenceSettings": { + "Type": "Database" + }, + "ProjectConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "ProjectGroupId": "string", + "ProjectTags": [ + "string" + ], + "ReleaseCreationStrategy": { + "ChannelId": "string", + "ReleaseCreationPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + } + }, + "ReleaseNotesTemplate": "string", + "RetainTenantConnections": true, + "Slug": "string", + "SpaceId": "string", + "Templates": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "TenantedDeploymentMode": "Untenanted", + "VersioningStrategy": { + "DonorPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + }, + "Template": "string" + } +} +``` +::: + +**Response** + +`201` — Created + +- **`AllowIgnoreChannelRules`** :span[boolean]{.type-label} +- **`AutoCreateRelease`** :span[boolean]{.type-label} +- **`AutoDeployReleaseOverrides`** :span[array of object]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ReleaseId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`ClonedFromProjectId`** :span[string]{.type-label} +- **`CombineHealthAndSyncStatusInDashboardLiveStatus`** :span[boolean]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`DefaultPowerShellEdition`** :span[string]{.type-label} +- **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} +- **`DeploymentChangesTemplate`** :span[string]{.type-label} +- **`DeploymentProcessId`** :span[string]{.type-label} +- **`DeprovisioningRunbookId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`DiscreteChannelRelease`** :span[boolean]{.type-label} + Treats releases of different channels to the same environment as a seperate deployment dimension. 'False' indicates a "hotfix"-style usage of channels (single release active per environment ignoring channels), whereas `True` indicates "microservice"-style usage (single release per environment per channel). +- **`ExecuteDeploymentsOnEventBasedPipeline`** :span[boolean]{.type-label} +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IncludedLibraryVariableSetIds`** :span[array of string]{.type-label} + Library variable sets included in the project. Sets are listed in order of precedence, with earlier items in the list overriding any variables with the same name and scope definition appearing later in the list. +- **`IsBadgesEnabled`** :span[boolean]{.type-label} +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsVersionControlled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LifecycleId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`PersistenceSettings`** :span[object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `Database`, `VersionControlled`. +- **`ProjectConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`ProjectGroupId`** :span[string]{.type-label} +- **`ProjectTags`** :span[array of string]{.type-label} + List of tags assigned to this project. +- **`ProjectTemplateDetails`** :span[object]{.type-label} + - **`IsShared`** :span[boolean]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`VersionMask`** :span[string]{.type-label} + Minimum length 1. +- **`ProvisioningRunbookId`** :span[string]{.type-label} +- **`ReleaseCreationStrategy`** :span[object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`ReleaseCreationPackage`** :span[object]{.type-label} +- **`ReleaseNotesTemplate`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Templates`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`TenantedDeploymentMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`VariableSetId`** :span[string]{.type-label} +- **`VersioningStrategy`** :span[object]{.type-label} + - **`DonorPackage`** :span[object]{.type-label} + - **`Template`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AllowIgnoreChannelRules": true, + "AutoCreateRelease": true, + "AutoDeployReleaseOverrides": [ + { + "EnvironmentId": "string", + "ReleaseId": "string", + "TenantId": "string" + } + ], + "ClonedFromProjectId": "string", + "CombineHealthAndSyncStatusInDashboardLiveStatus": true, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultPowerShellEdition": "string", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "DeploymentProcessId": "string", + "DeprovisioningRunbookId": "string", + "Description": "string", + "DiscreteChannelRelease": true, + "ExecuteDeploymentsOnEventBasedPipeline": true, + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "ForcePackageDownload": true, + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IncludedLibraryVariableSetIds": [ + "string" + ], + "IsBadgesEnabled": true, + "IsDisabled": true, + "IsVersionControlled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PersistenceSettings": { + "Type": "Database" + }, + "ProjectConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "ProjectGroupId": "string", + "ProjectTags": [ + "string" + ], + "ProjectTemplateDetails": { + "IsShared": true, + "Slug": "string", + "VersionMask": "string" + }, + "ProvisioningRunbookId": "string", + "ReleaseCreationStrategy": { + "ChannelId": "string", + "ReleaseCreationPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + } + }, + "ReleaseNotesTemplate": "string", + "Slug": "string", + "SpaceId": "string", + "Templates": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "TenantedDeploymentMode": "Untenanted", + "VariableSetId": "string", + "VersioningStrategy": { + "DonorPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + }, + "Template": "string" + } +} +``` +::: + +## List all of the projects in the supplied Octopus Deploy Space + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/all"} + +Also reachable at `/api/projects/all`, `/api/spaces/{spaceIdentifier}/projects/all`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the space. + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + Project Ids of Projects to filter results to. + +**Response** + +`200` — All of the project resources in the supplied Octopus Deploy Space. + +- **`AllowIgnoreChannelRules`** :span[boolean]{.type-label} +- **`AutoCreateRelease`** :span[boolean]{.type-label} +- **`AutoDeployReleaseOverrides`** :span[array of object]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ReleaseId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`ClonedFromProjectId`** :span[string]{.type-label} +- **`CombineHealthAndSyncStatusInDashboardLiveStatus`** :span[boolean]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`DefaultPowerShellEdition`** :span[string]{.type-label} +- **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} +- **`DeploymentChangesTemplate`** :span[string]{.type-label} +- **`DeploymentProcessId`** :span[string]{.type-label} +- **`DeprovisioningRunbookId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`DiscreteChannelRelease`** :span[boolean]{.type-label} + Treats releases of different channels to the same environment as a seperate deployment dimension. 'False' indicates a "hotfix"-style usage of channels (single release active per environment ignoring channels), whereas `True` indicates "microservice"-style usage (single release per environment per channel). +- **`ExecuteDeploymentsOnEventBasedPipeline`** :span[boolean]{.type-label} +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IncludedLibraryVariableSetIds`** :span[array of string]{.type-label} + Library variable sets included in the project. Sets are listed in order of precedence, with earlier items in the list overriding any variables with the same name and scope definition appearing later in the list. +- **`IsBadgesEnabled`** :span[boolean]{.type-label} +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsVersionControlled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LifecycleId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`PersistenceSettings`** :span[object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `Database`, `VersionControlled`. +- **`ProjectConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`ProjectGroupId`** :span[string]{.type-label} +- **`ProjectTags`** :span[array of string]{.type-label} + List of tags assigned to this project. +- **`ProjectTemplateDetails`** :span[object]{.type-label} + - **`IsShared`** :span[boolean]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`VersionMask`** :span[string]{.type-label} + Minimum length 1. +- **`ProvisioningRunbookId`** :span[string]{.type-label} +- **`ReleaseCreationStrategy`** :span[object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`ReleaseCreationPackage`** :span[object]{.type-label} +- **`ReleaseNotesTemplate`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Templates`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`TenantedDeploymentMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`VariableSetId`** :span[string]{.type-label} +- **`VersioningStrategy`** :span[object]{.type-label} + - **`DonorPackage`** :span[object]{.type-label} + - **`Template`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "AllowIgnoreChannelRules": true, + "AutoCreateRelease": true, + "AutoDeployReleaseOverrides": [ + { + "EnvironmentId": "string", + "ReleaseId": "string", + "TenantId": "string" + } + ], + "ClonedFromProjectId": "string", + "CombineHealthAndSyncStatusInDashboardLiveStatus": true, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultPowerShellEdition": "string", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "DeploymentProcessId": "string", + "DeprovisioningRunbookId": "string", + "Description": "string", + "DiscreteChannelRelease": true, + "ExecuteDeploymentsOnEventBasedPipeline": true, + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "ForcePackageDownload": true, + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IncludedLibraryVariableSetIds": [ + "string" + ], + "IsBadgesEnabled": true, + "IsDisabled": true, + "IsVersionControlled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PersistenceSettings": { + "Type": "Database" + }, + "ProjectConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "ProjectGroupId": "string", + "ProjectTags": [ + "string" + ], + "ProjectTemplateDetails": { + "IsShared": true, + "Slug": "string", + "VersionMask": "string" + }, + "ProvisioningRunbookId": "string", + "ReleaseCreationStrategy": { + "ChannelId": "string", + "ReleaseCreationPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + } + }, + "ReleaseNotesTemplate": "string", + "Slug": "string", + "SpaceId": "string", + "Templates": [ + { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "TenantedDeploymentMode": "Untenanted", + "VariableSetId": "string", + "VersioningStrategy": { + "DonorPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + }, + "Template": "string" + } + } +] +``` +::: + +## Get the logo associated with the project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{id\}/logo"} + +Also reachable at `/api/projects/{id}/logo`, `/api/spaces/{spaceIdentifier}/projects/{id}/logo`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the resource. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the space. + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Get a Project by ID or slug + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}"} + +Also reachable at `/api/projects/{projectId}`, `/api/projects/{projectId}/{unusedGitRef}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{unusedGitRef}`, `/api/{spaceId}/projects/{projectId}/{unusedGitRef}`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project to return. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested Project. + +- **`AllowIgnoreChannelRules`** :span[boolean]{.type-label} +- **`AutoCreateRelease`** :span[boolean]{.type-label} +- **`AutoDeployReleaseOverrides`** :span[array of object]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ReleaseId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`ClonedFromProjectId`** :span[string]{.type-label} +- **`CombineHealthAndSyncStatusInDashboardLiveStatus`** :span[boolean]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`DefaultPowerShellEdition`** :span[string]{.type-label} +- **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} +- **`DeploymentChangesTemplate`** :span[string]{.type-label} +- **`DeploymentProcessId`** :span[string]{.type-label} +- **`DeprovisioningRunbookId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`DiscreteChannelRelease`** :span[boolean]{.type-label} + Treats releases of different channels to the same environment as a seperate deployment dimension. 'False' indicates a "hotfix"-style usage of channels (single release active per environment ignoring channels), whereas `True` indicates "microservice"-style usage (single release per environment per channel). +- **`ExecuteDeploymentsOnEventBasedPipeline`** :span[boolean]{.type-label} +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IncludedLibraryVariableSetIds`** :span[array of string]{.type-label} + Library variable sets included in the project. Sets are listed in order of precedence, with earlier items in the list overriding any variables with the same name and scope definition appearing later in the list. +- **`IsBadgesEnabled`** :span[boolean]{.type-label} +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsVersionControlled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LifecycleId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`PersistenceSettings`** :span[object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `Database`, `VersionControlled`. +- **`ProjectConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`ProjectGroupId`** :span[string]{.type-label} +- **`ProjectTags`** :span[array of string]{.type-label} + List of tags assigned to this project. +- **`ProjectTemplateDetails`** :span[object]{.type-label} + - **`IsShared`** :span[boolean]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`VersionMask`** :span[string]{.type-label} + Minimum length 1. +- **`ProvisioningRunbookId`** :span[string]{.type-label} +- **`ReleaseCreationStrategy`** :span[object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`ReleaseCreationPackage`** :span[object]{.type-label} +- **`ReleaseNotesTemplate`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Templates`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`TenantedDeploymentMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`VariableSetId`** :span[string]{.type-label} +- **`VersioningStrategy`** :span[object]{.type-label} + - **`DonorPackage`** :span[object]{.type-label} + - **`Template`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AllowIgnoreChannelRules": true, + "AutoCreateRelease": true, + "AutoDeployReleaseOverrides": [ + { + "EnvironmentId": "string", + "ReleaseId": "string", + "TenantId": "string" + } + ], + "ClonedFromProjectId": "string", + "CombineHealthAndSyncStatusInDashboardLiveStatus": true, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultPowerShellEdition": "string", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "DeploymentProcessId": "string", + "DeprovisioningRunbookId": "string", + "Description": "string", + "DiscreteChannelRelease": true, + "ExecuteDeploymentsOnEventBasedPipeline": true, + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "ForcePackageDownload": true, + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IncludedLibraryVariableSetIds": [ + "string" + ], + "IsBadgesEnabled": true, + "IsDisabled": true, + "IsVersionControlled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PersistenceSettings": { + "Type": "Database" + }, + "ProjectConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "ProjectGroupId": "string", + "ProjectTags": [ + "string" + ], + "ProjectTemplateDetails": { + "IsShared": true, + "Slug": "string", + "VersionMask": "string" + }, + "ProvisioningRunbookId": "string", + "ReleaseCreationStrategy": { + "ChannelId": "string", + "ReleaseCreationPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + } + }, + "ReleaseNotesTemplate": "string", + "Slug": "string", + "SpaceId": "string", + "Templates": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "TenantedDeploymentMode": "Untenanted", + "VariableSetId": "string", + "VersioningStrategy": { + "DonorPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + }, + "Template": "string" + } +} +``` +::: + +## Modify an existing Project + +:endpoint{method="PUT" path="/api/\{spaceId\}/projects/\{projectId\}"} + +Also reachable at `/api/projects/{projectId}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the project to modify. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`AllowIgnoreChannelRules`** :span[boolean]{.type-label} +- **`AutoCreateRelease`** :span[boolean]{.type-label} +- **`AutoDeployReleaseOverrides`** :span[array of object]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ReleaseId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`ChangeDescription`** :span[string]{.type-label} + The change description. +- **`ClonedFromProjectId`** :span[string]{.type-label} +- **`CombineHealthAndSyncStatusInDashboardLiveStatus`** :span[boolean]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`DefaultPowerShellEdition`** :span[string]{.type-label} + Which edition of PowerShell the project's script steps run under: "Desktop" (Windows PowerShell) or "Core" (cross-platform PowerShell). Leave unset to inherit the server default. +- **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} +- **`DeploymentChangesTemplate`** :span[string]{.type-label} +- **`DeprovisioningRunbookId`** :span[string]{.type-label} + ID of a runbook in this project that tears down an ephemeral environment. Must be an existing runbook of this project; call find_runbooks to look one up. Only relevant to projects using ephemeral environments. +- **`Description`** :span[string]{.type-label} +- **`DiscreteChannelRelease`** :span[boolean]{.type-label} + Treats releases of different channels to the same environment as a separate deployment dimension. 'False' indicates a "hotfix"-style usage of channels (single release active per environment ignoring channels), whereas `True` indicates "microservice"-style usage (single release per environment per channel). +- **`ExecuteDeploymentsOnEventBasedPipeline`** :span[boolean]{.type-label} +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`IncludedLibraryVariableSetIds`** :span[array of string]{.type-label} + Library variable sets included in the project. Sets are listed in order of precedence, with earlier items in the list overriding any variables with the same name and scope definition appearing later in the list. +- **`IsBadgesEnabled`** :span[boolean]{.type-label} +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LifecycleId`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`PersistenceSettings`** :span[object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `Database`, `VersionControlled`. +- **`ProjectConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`ProjectGroupId`** :span[string]{.type-label} *(required)* +- **`ProjectId`** :span[string]{.type-label} *(required)* + ID of the project to modify. +- **`ProjectTags`** :span[array of string]{.type-label} + The project'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 "Regions/us-east"). This replaces the project's current tags, so resubmit the existing ones you want to keep. Call find_tag_sets to discover which tag sets apply to projects. +- **`ProvisioningRunbookId`** :span[string]{.type-label} + ID of a runbook in this project that provisions an ephemeral environment. Must be an existing runbook of this project; call find_runbooks to look one up. Only relevant to projects using ephemeral environments. +- **`ReleaseCreationStrategy`** :span[object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`ReleaseCreationPackage`** :span[object]{.type-label} +- **`ReleaseNotesTemplate`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} + URL-friendly short identifier for the project, unique within the space. Leave unset to keep the project's current slug. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`Templates`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`TenantedDeploymentMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`VersioningStrategy`** :span[object]{.type-label} + - **`DonorPackage`** :span[object]{.type-label} + - **`Template`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "AllowIgnoreChannelRules": true, + "AutoCreateRelease": true, + "AutoDeployReleaseOverrides": [ + { + "EnvironmentId": "string", + "ReleaseId": "string", + "TenantId": "string" + } + ], + "ChangeDescription": "string", + "ClonedFromProjectId": "string", + "CombineHealthAndSyncStatusInDashboardLiveStatus": true, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultPowerShellEdition": "string", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "DeprovisioningRunbookId": "string", + "Description": "string", + "DiscreteChannelRelease": true, + "ExecuteDeploymentsOnEventBasedPipeline": true, + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "ForcePackageDownload": true, + "IncludedLibraryVariableSetIds": [ + "string" + ], + "IsBadgesEnabled": true, + "IsDisabled": true, + "LifecycleId": "string", + "Name": "string", + "PersistenceSettings": { + "Type": "Database" + }, + "ProjectConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "ProjectGroupId": "string", + "ProjectId": "string", + "ProjectTags": [ + "string" + ], + "ProvisioningRunbookId": "string", + "ReleaseCreationStrategy": { + "ChannelId": "string", + "ReleaseCreationPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + } + }, + "ReleaseNotesTemplate": "string", + "Slug": "string", + "SpaceId": "string", + "Templates": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "TenantedDeploymentMode": "Untenanted", + "VersioningStrategy": { + "DonorPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + }, + "Template": "string" + } +} +``` +::: + +**Response** + +`200` — Confirms that the Project has been modified, containing the updated Project + +- **`AllowIgnoreChannelRules`** :span[boolean]{.type-label} +- **`AutoCreateRelease`** :span[boolean]{.type-label} +- **`AutoDeployReleaseOverrides`** :span[array of object]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ReleaseId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`ClonedFromProjectId`** :span[string]{.type-label} +- **`CombineHealthAndSyncStatusInDashboardLiveStatus`** :span[boolean]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`DefaultPowerShellEdition`** :span[string]{.type-label} +- **`DefaultToSkipIfAlreadyInstalled`** :span[boolean]{.type-label} +- **`DeploymentChangesTemplate`** :span[string]{.type-label} +- **`DeploymentProcessId`** :span[string]{.type-label} +- **`DeprovisioningRunbookId`** :span[string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`DiscreteChannelRelease`** :span[boolean]{.type-label} + Treats releases of different channels to the same environment as a seperate deployment dimension. 'False' indicates a "hotfix"-style usage of channels (single release active per environment ignoring channels), whereas `True` indicates "microservice"-style usage (single release per environment per channel). +- **`ExecuteDeploymentsOnEventBasedPipeline`** :span[boolean]{.type-label} +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IncludedLibraryVariableSetIds`** :span[array of string]{.type-label} + Library variable sets included in the project. Sets are listed in order of precedence, with earlier items in the list overriding any variables with the same name and scope definition appearing later in the list. +- **`IsBadgesEnabled`** :span[boolean]{.type-label} +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsVersionControlled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LifecycleId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`PersistenceSettings`** :span[object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `Database`, `VersionControlled`. +- **`ProjectConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`ProjectGroupId`** :span[string]{.type-label} +- **`ProjectTags`** :span[array of string]{.type-label} + List of tags assigned to this project. +- **`ProjectTemplateDetails`** :span[object]{.type-label} + - **`IsShared`** :span[boolean]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`VersionMask`** :span[string]{.type-label} + Minimum length 1. +- **`ProvisioningRunbookId`** :span[string]{.type-label} +- **`ReleaseCreationStrategy`** :span[object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`ReleaseCreationPackage`** :span[object]{.type-label} +- **`ReleaseNotesTemplate`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Templates`** :span[array of object]{.type-label} + - **`DefaultValue`** :span[object]{.type-label} + - **`DisplaySettings`** :span[object]{.type-label} + - **`HelpText`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Label`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`TenantedDeploymentMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`VariableSetId`** :span[string]{.type-label} +- **`VersioningStrategy`** :span[object]{.type-label} + - **`DonorPackage`** :span[object]{.type-label} + - **`Template`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AllowIgnoreChannelRules": true, + "AutoCreateRelease": true, + "AutoDeployReleaseOverrides": [ + { + "EnvironmentId": "string", + "ReleaseId": "string", + "TenantId": "string" + } + ], + "ClonedFromProjectId": "string", + "CombineHealthAndSyncStatusInDashboardLiveStatus": true, + "DefaultGuidedFailureMode": "EnvironmentDefault", + "DefaultPowerShellEdition": "string", + "DefaultToSkipIfAlreadyInstalled": true, + "DeploymentChangesTemplate": "string", + "DeploymentProcessId": "string", + "DeprovisioningRunbookId": "string", + "Description": "string", + "DiscreteChannelRelease": true, + "ExecuteDeploymentsOnEventBasedPipeline": true, + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "ForcePackageDownload": true, + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IncludedLibraryVariableSetIds": [ + "string" + ], + "IsBadgesEnabled": true, + "IsDisabled": true, + "IsVersionControlled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LifecycleId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PersistenceSettings": { + "Type": "Database" + }, + "ProjectConnectivityPolicy": { + "AllowDeploymentsToNoTargets": true, + "ExcludeUnhealthyTargets": true, + "SkipMachineBehavior": "None", + "TargetRoles": [ + "string" + ] + }, + "ProjectGroupId": "string", + "ProjectTags": [ + "string" + ], + "ProjectTemplateDetails": { + "IsShared": true, + "Slug": "string", + "VersionMask": "string" + }, + "ProvisioningRunbookId": "string", + "ReleaseCreationStrategy": { + "ChannelId": "string", + "ReleaseCreationPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + } + }, + "ReleaseNotesTemplate": "string", + "Slug": "string", + "SpaceId": "string", + "Templates": [ + { + "DefaultValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "DisplaySettings": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + } + ], + "TenantedDeploymentMode": "Untenanted", + "VariableSetId": "string", + "VersioningStrategy": { + "DonorPackage": { + "DeploymentAction": "string", + "PackageReference": "string" + }, + "Template": "string" + } +} +``` +::: + +## Delete an existing Project + +:endpoint{method="DELETE" path="/api/\{spaceId\}/projects/\{projectId\}"} + +Also reachable at `/api/projects/{projectId}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +## Test the Git settings to make sure we can connect + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/git/connectivity-test"} + +Also reachable at `/api/projects/{projectId}/git/connectivity-test`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/connectivity-test`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`BasePath`** :span[string]{.type-label} *(required)* +- **`Credentials`** :span[object]{.type-label} *(required)* + - **`Type`** :span[enum]{.type-label} + Allowed values: `Anonymous`, `UsernamePassword`, `Reference`, `GitHub`, `SshKey`. +- **`DefaultBranch`** :span[string]{.type-label} *(required)* +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`Url`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "BasePath": "string", + "Credentials": { + "Type": "Anonymous" + }, + "DefaultBranch": "string", + "ProjectId": "string", + "SpaceId": "string", + "Url": "string" +} +``` +::: + +**Response** + +`200` — The results from testing git settings. + +- **`Messages`** :span[array of object]{.type-label} + - **`Category`** :span[enum]{.type-label} + Allowed values: `Info`, `Error`. + - **`Message`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Messages": [ + { + "Category": "Info", + "Message": "string" + } + ] +} +``` +::: + +## Convert an existing project to store its configuration in version control + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/git/convert"} + +Also reachable at `/api/projects/{projectId}/git/convert`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/convert`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`ChangeDescription`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`CommitMessage`** :span[string]{.type-label} +- **`InitialCommitBranchName`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`VersionControlSettings`** :span[object]{.type-label} *(required)* + - **`BasePath`** :span[string]{.type-label} *(required)* + - **`ConversionState`** :span[object]{.type-label} + - **`Credentials`** :span[object]{.type-label} *(required)* + - **`DefaultBranch`** :span[string]{.type-label} *(required)* + - **`ProtectedBranchNamePatterns`** :span[array of string]{.type-label} + - **`ProtectedDefaultBranch`** :span[boolean]{.type-label} + - **`SerializationFormat`** :span[enum]{.type-label} + Allowed values: `Ocl`, `Yaml`. + - **`Type`** :span[enum]{.type-label} *(required)* + Defaults to `VersionControlled`. + Allowed values: `Database`, `VersionControlled`. + - **`Url`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "ChangeDescription": "string", + "CommitMessage": "string", + "InitialCommitBranchName": "string", + "ProjectId": "string", + "SpaceId": "string", + "VersionControlSettings": { + "BasePath": "string", + "ConversionState": { + "RunbooksAreInGit": true, + "VariablesAreInGit": true + }, + "Credentials": { + "Type": "Anonymous" + }, + "DefaultBranch": "string", + "ProtectedBranchNamePatterns": [ + "string" + ], + "ProtectedDefaultBranch": true, + "SerializationFormat": "Ocl", + "Type": "Database", + "Url": "string" + } +} +``` +::: + +**Response** + +`200` — Empty response indicating the Project was converted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Convert all Runbooks to be stored in Git rather than the database + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/git/migrate-runbooks"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/migrate-runbooks`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Branch`** :span[string]{.type-label} + Branch to commit the migrated Runbooks to. Required if there are Runbooks to migrate. +- **`CommitMessage`** :span[string]{.type-label} + Commit message to use when committing the migrated Runbooks to Git. Required if there are Runbooks to migrate. +- **`CreateBranch`** :span[boolean]{.type-label} +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Branch": "string", + "CommitMessage": "string", + "CreateBranch": true, + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Indicates that the project runbooks were converted to Git + +- **`DraftRunbooks`** :span[array of object]{.type-label} + - **`RunbookId`** :span[string]{.type-label} + - **`RunbookName`** :span[string]{.type-label} +- **`PublishedRunbooks`** :span[array of object]{.type-label} + - **`RunbookId`** :span[string]{.type-label} + - **`RunbookName`** :span[string]{.type-label} +- **`ServerTaskId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DraftRunbooks": [ + { + "RunbookId": "string", + "RunbookName": "string" + } + ], + "PublishedRunbooks": [ + { + "RunbookId": "string", + "RunbookName": "string" + } + ], + "ServerTaskId": "string" +} +``` +::: + +## Update the logo associated with the project + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/logo"} + +Also reachable at `/api/projects/{projectId}/logo`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/logo`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project to change logo for. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +## Update the logo associated with the project + +:endpoint{method="PUT" path="/api/\{spaceId\}/projects/\{projectId\}/logo"} + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project to change logo for. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +## Update the logo associated with the project + +:endpoint{method="PUT" path="/api/spaces/\{spaceIdentifier\}/projects/\{projectId\}/logo"} + +Also reachable at `/api/projects/{projectId}/logo`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project to change logo for. +- **`spaceIdentifier`** :span[string]{.type-label} *(required)* + Identifier (ID or slug) of the space. + +**Response** + +`200` — Success + +## Get the custom settings metadata from the extensions + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/metadata"} + +Also reachable at `/api/projects/{projectId}/metadata`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/metadata`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The custom settings metadata from the extensions. + +- **`ExtensionId`** :span[string]{.type-label} + Minimum length 1. +- **`Metadata`** :span[object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Types`** :span[array of object]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "ExtensionId": "string", + "Metadata": { + "Description": "string", + "Types": [ + {} + ] + } + } +] +``` +::: + +## Get a summary of project-specific information + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/summary"} + +Also reachable at `/api/projects/{projectId}/summary`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/summary`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Project Summary + +- **`HasBeenSuccessfullyDeployed`** :span[boolean]{.type-label} +- **`HasDeploymentProcess`** :span[boolean]{.type-label} +- **`HasRunbooks`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "HasBeenSuccessfullyDeployed": true, + "HasDeploymentProcess": true, + "HasRunbooks": true +} +``` +::: + +## Get a summary of project-specific information + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/summary/v1"} + +Also reachable at `/api/projects/{projectId}/summary/v1`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/summary/v1`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Project Summary + +- **`HasBeenSuccessfullyDeployed`** :span[boolean]{.type-label} +- **`HasDeploymentProcess`** :span[boolean]{.type-label} +- **`HasRunbooks`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "HasBeenSuccessfullyDeployed": true, + "HasDeploymentProcess": true, + "HasRunbooks": true +} +``` +::: + +## Get a summary of project-specific information + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/summary"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/summary`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/summary`. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Project Summary + +- **`HasBeenSuccessfullyDeployed`** :span[boolean]{.type-label} +- **`HasDeploymentProcess`** :span[boolean]{.type-label} +- **`HasRunbooks`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "HasBeenSuccessfullyDeployed": true, + "HasDeploymentProcess": true, + "HasRunbooks": true +} +``` +::: + +## Get a summary of project-specific information + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/summary/v1"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/summary/v1`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/summary/v1`. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Project Summary + +- **`HasBeenSuccessfullyDeployed`** :span[boolean]{.type-label} +- **`HasDeploymentProcess`** :span[boolean]{.type-label} +- **`HasRunbooks`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "HasBeenSuccessfullyDeployed": true, + "HasDeploymentProcess": true, + "HasRunbooks": true +} +``` +::: + +## Validate the provided git ref + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/git/validate" deprecated=true} + +Also reachable at `/api/projects/{projectId}/git/validate`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/validate`. + +:::div{.warning} +**Deprecated.** This endpoint may be removed in a future release. +::: + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`ProjectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "GitRef": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Validated Git ref or error message + +- **`Error`** :span[string]{.type-label} +- **`ValidatedGitRef`** :span[object]{.type-label} + - **`CanonicalName`** :span[string]{.type-label} + Minimum length 1. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Error": "string", + "ValidatedGitRef": { + "CanonicalName": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } +} +``` +::: diff --git a/src/pages/docs/api/proxies.md b/src/pages/docs/api/proxies.md new file mode 100644 index 0000000000..c37a97c12f --- /dev/null +++ b/src/pages/docs/api/proxies.md @@ -0,0 +1,446 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Proxies +--- + +## Get a list of Proxies + +:endpoint{method="GET" path="/api/\{spaceId\}/proxies"} + +Also reachable at `/api/proxies`, `/api/spaces/{spaceIdentifier}/proxies`. + +Lists all of the Proxies in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested list of Proxies, sorted alphabetically by name. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Host`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`Password`** :span[sensitive value]{.type-label} + - **`Port`** :span[integer]{.type-label} + - **`ProxyType`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Username`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Host": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Port": 0, + "ProxyType": "string", + "SpaceId": "string", + "Username": "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 +} +``` +::: + +## Create a Proxy in the specified Space + +:endpoint{method="POST" path="/api/\{spaceId\}/proxies"} + +Also reachable at `/api/proxies`, `/api/spaces/{spaceIdentifier}/proxies`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. + +**Request Body** + +- **`Host`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`Port`** :span[integer]{.type-label} *(required)* + Minimum `0`. Maximum `65535`. +- **`ProxyType`** :span[string]{.type-label} + The type of proxy. Currently only HTTP is supported. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. +- **`Username`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Host": "string", + "Name": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Port": 0, + "ProxyType": "string", + "SpaceId": "string", + "Username": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Host`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`Port`** :span[integer]{.type-label} +- **`ProxyType`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Username`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Host": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Port": 0, + "ProxyType": "string", + "SpaceId": "string", + "Username": "string" +} +``` +::: + +## Get a list of Proxies + +:endpoint{method="GET" path="/api/\{spaceId\}/proxies/all"} + +Also reachable at `/api/proxies/all`, `/api/spaces/{spaceIdentifier}/proxies/all`. + +Lists the name and ID of all of the Proxies in the supplied Octopus Deploy Space. The results will be sorted by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. + +**Response** + +`200` — The name and ID of all Proxies in the supplied Octopus Deploy Space, sorted by name. + +- **`Host`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`Port`** :span[integer]{.type-label} +- **`ProxyType`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Username`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Host": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Port": 0, + "ProxyType": "string", + "SpaceId": "string", + "Username": "string" + } +] +``` +::: + +## Get a Proxy by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/proxies/\{id\}"} + +Also reachable at `/api/proxies/{id}`, `/api/spaces/{spaceIdentifier}/proxies/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Proxy to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. + +**Response** + +`200` — The requested Proxy + +- **`Host`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`Port`** :span[integer]{.type-label} +- **`ProxyType`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Username`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Host": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Port": 0, + "ProxyType": "string", + "SpaceId": "string", + "Username": "string" +} +``` +::: + +## Modify the specified Proxy in the specified Space + +:endpoint{method="PUT" path="/api/\{spaceId\}/proxies/\{id\}"} + +Also reachable at `/api/proxies/{id}`, `/api/spaces/{spaceIdentifier}/proxies/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Proxy to modify. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the Space containing the Proxy to modify. + +**Request Body** + +- **`Host`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Id`** :span[string]{.type-label} *(required)* + ID of the Proxy to modify. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`Port`** :span[integer]{.type-label} *(required)* + Minimum `0`. Maximum `65535`. +- **`ProxyType`** :span[string]{.type-label} + The type of proxy. Currently only HTTP is supported. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the Space containing the Proxy to modify. +- **`Username`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Host": "string", + "Id": "string", + "Name": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Port": 0, + "ProxyType": "string", + "SpaceId": "string", + "Username": "string" +} +``` +::: + +**Response** + +`200` — The modified Proxy + +- **`Host`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Password`** :span[sensitive value]{.type-label} + - **`HasValue`** :span[boolean]{.type-label} + - **`Hint`** :span[string]{.type-label} + - **`NewValue`** :span[string]{.type-label} +- **`Port`** :span[integer]{.type-label} +- **`ProxyType`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Username`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Host": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Port": 0, + "ProxyType": "string", + "SpaceId": "string", + "Username": "string" +} +``` +::: + +## Delete an existing Proxy by Id + +:endpoint{method="DELETE" path="/api/\{spaceId\}/proxies/\{id\}"} + +Also reachable at `/api/proxies/{id}`, `/api/spaces/{spaceIdentifier}/proxies/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Proxy to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. + +**Response** + +`200` — Success diff --git a/src/pages/docs/api/rate-limiting.md b/src/pages/docs/api/rate-limiting.md new file mode 100644 index 0000000000..4243e8cf6c --- /dev/null +++ b/src/pages/docs/api/rate-limiting.md @@ -0,0 +1,195 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Rate Limiting +--- + +Rate Limiting policies can be configured via the API. + +See https://octopus.com/docs/administration/managing-infrastructure/rate-limiting to understand the feature and what the settings mean. + +## List all rate limiting policies + +:endpoint{method="GET" path="/api/ratelimitingpolicies"} + +There are three builtin policies, so while this returns a paginated response, there is only ever a single page. - Unauthenticated requests - Authenticated requests - AI Agent requests + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Minimum `0`. + +**Response** + +`200` — Success + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`AuditMode`** :span[boolean]{.type-label} + When enabled, the policy logs requests that would be rate limited without rejecting them (no 429 response). + - **`BurstLimit`** :span[integer]{.type-label} + Maximum capacity of the token bucket. + - **`Id`** :span[string]{.type-label} + The ID of this policy. + - **`IsBuiltIn`** :span[boolean]{.type-label} + Whether this is a built-in policy that cannot be deleted or have its name or scope changed. + - **`IsEnabled`** :span[boolean]{.type-label} + Whether this policy is actively enforced. + - **`Name`** :span[string]{.type-label} + The display name of this policy. Minimum length 1. + - **`RequestsPerMinute`** :span[integer]{.type-label} + Number of requests permitted per minute. + - **`ScopeType`** :span[string]{.type-label} + The scope this policy applies to. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "AuditMode": true, + "BurstLimit": 200, + "Id": "RateLimitingPolicies-1", + "IsBuiltIn": true, + "IsEnabled": true, + "Name": "Authenticated requests", + "RequestsPerMinute": 600, + "ScopeType": "string" + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get a rate limiting policy by ID + +:endpoint{method="GET" path="/api/ratelimitingpolicies/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the rate limiting policy. + +**Response** + +`200` — A Rate Limiting Policy + +- **`AuditMode`** :span[boolean]{.type-label} + When enabled, the policy logs requests that would be rate limited without rejecting them (no 429 response). +- **`BurstLimit`** :span[integer]{.type-label} + Maximum capacity of the token bucket. +- **`Id`** :span[string]{.type-label} + The ID of this policy. +- **`IsBuiltIn`** :span[boolean]{.type-label} + Whether this is a built-in policy that cannot be deleted or have its name or scope changed. +- **`IsEnabled`** :span[boolean]{.type-label} + Whether this policy is actively enforced. +- **`Name`** :span[string]{.type-label} + The display name of this policy. Minimum length 1. +- **`RequestsPerMinute`** :span[integer]{.type-label} + Number of requests permitted per minute. +- **`ScopeType`** :span[string]{.type-label} + The scope this policy applies to. + +:::api-example{label="Response"} +```json +{ + "AuditMode": true, + "BurstLimit": 200, + "Id": "RateLimitingPolicies-1", + "IsBuiltIn": true, + "IsEnabled": true, + "Name": "Authenticated requests", + "RequestsPerMinute": 600, + "ScopeType": "string" +} +``` +::: + +## Modify an existing rate limiting policy + +:endpoint{method="PUT" path="/api/ratelimitingpolicies/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the policy to modify. + +**Request Body** + +- **`AuditMode`** :span[boolean]{.type-label} *(required)* + When enabled, the policy logs requests that would be rate limited without rejecting them (no 429 response). +- **`BurstLimit`** :span[integer]{.type-label} *(required)* + Maximum capacity of the token bucket. +- **`Id`** :span[string]{.type-label} *(required)* + ID of the policy to modify. +- **`IsEnabled`** :span[boolean]{.type-label} *(required)* + Whether this policy is actively enforced. +- **`Name`** :span[string]{.type-label} *(required)* + The display name of the policy. Minimum length 1. +- **`RequestsPerMinute`** :span[integer]{.type-label} *(required)* + Number of requests permitted per minute. +- **`ScopeType`** :span[string]{.type-label} *(required)* + The scope this policy applies to. + +:::api-example{label="Request"} +```json +{ + "AuditMode": true, + "BurstLimit": 200, + "Id": "RateLimitingPolicies-1", + "IsEnabled": true, + "Name": "Authenticated requests", + "RequestsPerMinute": 600, + "ScopeType": "string" +} +``` +::: + +**Response** + +`200` — A Rate Limiting Policy + +- **`AuditMode`** :span[boolean]{.type-label} + When enabled, the policy logs requests that would be rate limited without rejecting them (no 429 response). +- **`BurstLimit`** :span[integer]{.type-label} + Maximum capacity of the token bucket. +- **`Id`** :span[string]{.type-label} + The ID of this policy. +- **`IsBuiltIn`** :span[boolean]{.type-label} + Whether this is a built-in policy that cannot be deleted or have its name or scope changed. +- **`IsEnabled`** :span[boolean]{.type-label} + Whether this policy is actively enforced. +- **`Name`** :span[string]{.type-label} + The display name of this policy. Minimum length 1. +- **`RequestsPerMinute`** :span[integer]{.type-label} + Number of requests permitted per minute. +- **`ScopeType`** :span[string]{.type-label} + The scope this policy applies to. + +:::api-example{label="Response"} +```json +{ + "AuditMode": true, + "BurstLimit": 200, + "Id": "RateLimitingPolicies-1", + "IsBuiltIn": true, + "IsEnabled": true, + "Name": "Authenticated requests", + "RequestsPerMinute": 600, + "ScopeType": "string" +} +``` +::: diff --git a/src/pages/docs/api/releases.md b/src/pages/docs/api/releases.md new file mode 100644 index 0000000000..920464002d --- /dev/null +++ b/src/pages/docs/api/releases.md @@ -0,0 +1,2654 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Releases +--- + +## List all of the releases that belong to the given Channel + +:endpoint{method="GET" path="/api/\{spaceId\}/channels/\{id\}/releases"} + +Also reachable at `/api/channels/{id}/releases`, `/api/spaces/{spaceIdentifier}/channels/{id}/releases`. + +Releases will be ordered from most recent to least recent, + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Channel to get Releases for. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space to which the given Channel belongs. + +**Query Parameters** + +- **`projectId`** :span[string]{.type-label} + ID of the Project to which the given Channel belongs. +- **`searchByVersion`** :span[string]{.type-label} + A partial version, to limit the set of Releases to those with a version that includes the partial version. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — List of Releases on the given Channel. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Assembled`** :span[string]{.type-label} + Format `date-time`. + - **`BuildInformation`** :span[array of object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`CustomFields`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IgnoreChannelRules`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ProjectDeploymentProcessSnapshotId`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + - **`ReleaseNotes`** :span[string]{.type-label} + - **`SelectedGitResources`** :span[array of object]{.type-label} + - **`SelectedPackages`** :span[array of object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + Maximum length 349. + - **`VersionControlReference`** :span[object]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Assembled": "2020-01-01T00:00:00.000Z", + "BuildInformation": [ + {} + ], + "ChannelId": "string", + "CustomFields": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "IgnoreChannelRules": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectDeploymentProcessSnapshotId": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "ReleaseNotes": "string", + "SelectedGitResources": [ + {} + ], + "SelectedPackages": [ + {} + ], + "SpaceId": "string", + "Version": "string", + "VersionControlReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "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 +} +``` +::: + +## List all of the releases that belong to the given Channel + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/channels/\{id\}/releases"} + +Also reachable at `/api/projects/{projectId}/channels/{id}/releases`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/channels/{id}/releases`. + +Releases will be ordered from most recent to least recent, + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Channel to get Releases for. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project to which the given Channel belongs. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space to which the given Channel belongs. + +**Query Parameters** + +- **`searchByVersion`** :span[string]{.type-label} + A partial version, to limit the set of Releases to those with a version that includes the partial version. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — List of Releases on the given Channel. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Assembled`** :span[string]{.type-label} + Format `date-time`. + - **`BuildInformation`** :span[array of object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`CustomFields`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IgnoreChannelRules`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ProjectDeploymentProcessSnapshotId`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + - **`ReleaseNotes`** :span[string]{.type-label} + - **`SelectedGitResources`** :span[array of object]{.type-label} + - **`SelectedPackages`** :span[array of object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + Maximum length 349. + - **`VersionControlReference`** :span[object]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Assembled": "2020-01-01T00:00:00.000Z", + "BuildInformation": [ + {} + ], + "ChannelId": "string", + "CustomFields": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "IgnoreChannelRules": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectDeploymentProcessSnapshotId": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "ReleaseNotes": "string", + "SelectedGitResources": [ + {} + ], + "SelectedPackages": [ + {} + ], + "SpaceId": "string", + "Version": "string", + "VersionControlReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "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 +} +``` +::: + +## List all of the releases that belong to the given Project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/releases"} + +Also reachable at `/api/projects/{projectId}/releases`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/releases`. + +Releases will be ordered from most recent to least recent + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project to get Releases for. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space to which the given Project belongs. + +**Query Parameters** + +- **`searchByVersion`** :span[string]{.type-label} + A partial version, to limit the set of Releases to those with a version that includes the partial version. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The list of Releases + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Assembled`** :span[string]{.type-label} + Format `date-time`. + - **`BuildInformation`** :span[array of object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`CustomFields`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IgnoreChannelRules`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ProjectDeploymentProcessSnapshotId`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + - **`ReleaseNotes`** :span[string]{.type-label} + - **`SelectedGitResources`** :span[array of object]{.type-label} + - **`SelectedPackages`** :span[array of object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + Maximum length 349. + - **`VersionControlReference`** :span[object]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Assembled": "2020-01-01T00:00:00.000Z", + "BuildInformation": [ + {} + ], + "ChannelId": "string", + "CustomFields": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "IgnoreChannelRules": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectDeploymentProcessSnapshotId": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "ReleaseNotes": "string", + "SelectedGitResources": [ + {} + ], + "SelectedPackages": [ + {} + ], + "SpaceId": "string", + "Version": "string", + "VersionControlReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "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 +} +``` +::: + +## Get a list of Variable Sets included in the Release's current Variable Snapshot + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/releases/\{id\}/variables"} + +Also reachable at `/api/projects/{projectId}/releases/{id}/variables`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/releases/{id}/variables`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Release to get variables for. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project the Release is in. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested list of Variables + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`OwnerId`** :span[string]{.type-label} + Gets or sets the ID of the document that owns these variables. +- **`ScopeValues`** :span[object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Channels`** :span[array of object]{.type-label} + - **`EnvironmentParameters`** :span[array of object]{.type-label} + - **`Environments`** :span[array of object]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`ProcessTemplateSteps`** :span[array of object]{.type-label} + - **`Processes`** :span[array of object]{.type-label} + - **`Roles`** :span[array of object]{.type-label} + - **`TargetTagParameters`** :span[array of object]{.type-label} + - **`TenantTagParameters`** :span[array of object]{.type-label} + - **`TenantTags`** :span[array of object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + Gets the collection of variables. + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsEditable`** :span[boolean]{.type-label} + - **`IsSensitive`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Prompt`** :span[object]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Type`** :span[string]{.type-label} + - **`Value`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +[ + { + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "OwnerId": "string", + "ScopeValues": { + "Actions": [ + {} + ], + "Channels": [ + {} + ], + "EnvironmentParameters": [ + {} + ], + "Environments": [ + {} + ], + "Machines": [ + {} + ], + "ProcessTemplateSteps": [ + {} + ], + "Processes": [ + {} + ], + "Roles": [ + {} + ], + "TargetTagParameters": [ + {} + ], + "TenantTagParameters": [ + {} + ], + "TenantTags": [ + {} + ] + }, + "SpaceId": "string", + "Variables": [ + { + "Description": "string", + "Id": "string", + "IsEditable": true, + "IsSensitive": true, + "Name": "string", + "Prompt": {}, + "Scope": {}, + "Type": "string", + "Value": "string" + } + ], + "Version": 0 + } +] +``` +::: + +## Get a single release by project ID and version number + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/releases/\{version\}"} + +Also reachable at `/api/projects/{projectId}/releases/{version}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/releases/{version}`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project containing the release. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the release. +- **`version`** :span[string]{.type-label} *(required)* + The version of the requested release. + +**Response** + +`200` — Success + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`BuildInformation`** :span[array of object]{.type-label} + - **`Branch`** :span[string]{.type-label} + - **`BuildEnvironment`** :span[string]{.type-label} + - **`BuildNumber`** :span[string]{.type-label} + - **`BuildUrl`** :span[string]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + - **`IssueTrackerName`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`VcsCommitNumber`** :span[string]{.type-label} + - **`VcsCommitUrl`** :span[string]{.type-label} + - **`VcsRoot`** :span[string]{.type-label} + - **`VcsType`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} +- **`ChannelId`** :span[string]{.type-label} +- **`CustomFields`** :span[object]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IgnoreChannelRules`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectDeploymentProcessSnapshotId`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} +- **`ReleaseNotes`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} + Maximum length 349. +- **`VersionControlReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "BuildInformation": [ + { + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + {} + ], + "IssueTrackerName": "string", + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChannelId": "string", + "CustomFields": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "IgnoreChannelRules": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectDeploymentProcessSnapshotId": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "ReleaseNotes": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string", + "Version": "string", + "VersionControlReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + } +} +``` +::: + +## Get a list of Releases for the given Space + +:endpoint{method="GET" path="/api/\{spaceId\}/releases"} + +Also reachable at `/api/releases`, `/api/spaces/{spaceIdentifier}/releases`. + +Lists all of the Releases in the supplied Octopus Deploy Space, from all projects. The results will be sorted from most recent to least recent release. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space to which the Releases belong. + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The list of Releases for the requested Space. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Assembled`** :span[string]{.type-label} + Format `date-time`. + - **`BuildInformation`** :span[array of object]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`CustomFields`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IgnoreChannelRules`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ProjectDeploymentProcessSnapshotId`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + - **`ReleaseNotes`** :span[string]{.type-label} + - **`SelectedGitResources`** :span[array of object]{.type-label} + - **`SelectedPackages`** :span[array of object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + Maximum length 349. + - **`VersionControlReference`** :span[object]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Assembled": "2020-01-01T00:00:00.000Z", + "BuildInformation": [ + {} + ], + "ChannelId": "string", + "CustomFields": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "IgnoreChannelRules": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectDeploymentProcessSnapshotId": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "ReleaseNotes": "string", + "SelectedGitResources": [ + {} + ], + "SelectedPackages": [ + {} + ], + "SpaceId": "string", + "Version": "string", + "VersionControlReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "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 +} +``` +::: + +## Create a Release + +:endpoint{method="POST" path="/api/\{spaceId\}/releases"} + +Also reachable at `/api/releases`, `/api/spaces/{spaceIdentifier}/releases`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`ChannelId`** :span[string]{.type-label} +- **`CustomFields`** :span[object]{.type-label} +- **`IgnoreChannelRules`** :span[boolean]{.type-label} + Ignore channel rules. +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`ReleaseNotes`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} *(required)* + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`Version`** :span[string]{.type-label} *(required)* + Maximum length 349. +- **`VersionControlReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "ChannelId": "string", + "CustomFields": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "IgnoreChannelRules": true, + "ProjectId": "string", + "ReleaseNotes": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string", + "Version": "string", + "VersionControlReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + } +} +``` +::: + +**Response** + +`201` — Created + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`BuildInformation`** :span[array of object]{.type-label} + - **`Branch`** :span[string]{.type-label} + - **`BuildEnvironment`** :span[string]{.type-label} + - **`BuildNumber`** :span[string]{.type-label} + - **`BuildUrl`** :span[string]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + - **`IssueTrackerName`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`VcsCommitNumber`** :span[string]{.type-label} + - **`VcsCommitUrl`** :span[string]{.type-label} + - **`VcsRoot`** :span[string]{.type-label} + - **`VcsType`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} +- **`ChannelId`** :span[string]{.type-label} +- **`CustomFields`** :span[object]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IgnoreChannelRules`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectDeploymentProcessSnapshotId`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} +- **`ReleaseNotes`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} + Maximum length 349. +- **`VersionControlReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "BuildInformation": [ + { + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + {} + ], + "IssueTrackerName": "string", + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChannelId": "string", + "CustomFields": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "IgnoreChannelRules": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectDeploymentProcessSnapshotId": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "ReleaseNotes": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string", + "Version": "string", + "VersionControlReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + } +} +``` +::: + +## Create a Release + +:endpoint{method="POST" path="/api/\{spaceId\}/releases/create/v1"} + +Also reachable at `/api/releases/create/v1`, `/api/spaces/{spaceIdentifier}/releases/create/v1`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChannelName`** :span[string]{.type-label} + Name of the channel to use for the new release. Omit this argument to automatically select the best channel. +- **`CustomFields`** :span[object]{.type-label} + Values for the project's custom release fields, if it defines any, keyed by field name. +- **`GitCommit`** :span[string]{.type-label} + Only set alongside GitRef, when a specific commit is needed; GitRef alone uses the tip of that ref. +- **`GitRef`** :span[string]{.type-label} + The Git branch, tag or commit to snapshot the deployment process from. Required for a project that stores its configuration in Git, and must be left unset for one stored in the database — the command fails either way round. List a project's branches with get_branches. +- **`GitResources`** :span[array of string]{.type-label} + Git ref to use for a git resource in the release. Format: StepName:GitRef or StepName:GitResourceName:GitRef. If the GitResourceName is omitted, it's assumed to be the primary git resource for the step. The GitRef can be replaced with an asterisk. An asterisk will use the tip ref of the step-defined default branch. +- **`IgnoreChannelRules`** :span[boolean]{.type-label} + Create the release even when a package version, or the Git reference, violates the channel's version rules. This overrides a deliberate guardrail, so prefer correcting the versions or letting Octopus select the channel; only set it when explicitly asked to. +- **`IgnoreIfAlreadyExists`** :span[boolean]{.type-label} + If a release with the same version number already exists, return that one instead of failing — so the returned ReleaseId may be an existing release rather than a newly created one. +- **`PackagePrerelease`** :span[string]{.type-label} + Restrict automatic version selection to pre-release versions carrying this tag, for example "beta". Ignored for steps whose version is pinned by PackageVersion or Packages. +- **`PackageVersion`** :span[string]{.type-label} + One version to use for every package step. Leave unset to take the latest version of each package; use Packages instead to pin versions per step. +- **`Packages`** :span[array of string]{.type-label} + Version number to use for a package in the release. Format: StepName:Version or PackageID:Version or StepName:PackageName:Version. StepName, PackageID, and PackageName can be replaced with an asterisk. An asterisk will be assumed for StepName, PackageID, or PackageName if they are omitted. +- **`ProjectName`** :span[string]{.type-label} *(required)* +- **`ReleaseNotes`** :span[string]{.type-label} + Release Notes for the new release. Styling with Markdown is supported. +- **`ReleaseVersion`** :span[string]{.type-label} + Leave unset to let Octopus pick the next version from the project's versioning strategy, which is usually what you want. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`SpaceIdOrName`** :span[string]{.type-label} *(required)* + Both this and SpaceId are required, and normally hold the same space ID; set both. + +:::api-example{label="Request"} +```json +{ + "ChannelName": "string", + "CustomFields": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "GitCommit": "string", + "GitRef": "string", + "GitResources": [ + "string" + ], + "IgnoreChannelRules": true, + "IgnoreIfAlreadyExists": true, + "PackagePrerelease": "string", + "PackageVersion": "string", + "Packages": [ + "string" + ], + "ProjectName": "string", + "ReleaseNotes": "string", + "ReleaseVersion": "string", + "SpaceId": "string", + "SpaceIdOrName": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`ReleaseId`** :span[string]{.type-label} +- **`ReleaseVersion`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "ReleaseId": "string", + "ReleaseVersion": "string" +} +``` +::: + +## Get a Release by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/releases/\{id\}"} + +Also reachable at `/api/releases/{id}`, `/api/spaces/{spaceIdentifier}/releases/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Release to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space that owns the Release. + +**Response** + +`200` — The requested Release + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`BuildInformation`** :span[array of object]{.type-label} + - **`Branch`** :span[string]{.type-label} + - **`BuildEnvironment`** :span[string]{.type-label} + - **`BuildNumber`** :span[string]{.type-label} + - **`BuildUrl`** :span[string]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + - **`IssueTrackerName`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`VcsCommitNumber`** :span[string]{.type-label} + - **`VcsCommitUrl`** :span[string]{.type-label} + - **`VcsRoot`** :span[string]{.type-label} + - **`VcsType`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} +- **`ChannelId`** :span[string]{.type-label} +- **`CustomFields`** :span[object]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IgnoreChannelRules`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectDeploymentProcessSnapshotId`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} +- **`ReleaseNotes`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} + Maximum length 349. +- **`VersionControlReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "BuildInformation": [ + { + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + {} + ], + "IssueTrackerName": "string", + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChannelId": "string", + "CustomFields": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "IgnoreChannelRules": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectDeploymentProcessSnapshotId": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "ReleaseNotes": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string", + "Version": "string", + "VersionControlReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + } +} +``` +::: + +## Update an existing Release + +:endpoint{method="PUT" path="/api/\{spaceId\}/releases/\{id\}"} + +Also reachable at `/api/releases/{id}`, `/api/spaces/{spaceIdentifier}/releases/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Release. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChannelId`** :span[string]{.type-label} *(required)* +- **`CustomFields`** :span[object]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* + ID of the Release. +- **`IgnoreChannelRules`** :span[boolean]{.type-label} + If altering the Channel of an existing Release, its rules may be violated. This ignores those violations. If not altering the Release Channel, this parameter is ignored. +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`ReleaseNotes`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} *(required)* + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`Version`** :span[string]{.type-label} *(required)* + Maximum length 349. + +:::api-example{label="Request"} +```json +{ + "ChannelId": "string", + "CustomFields": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "IgnoreChannelRules": true, + "ProjectId": "string", + "ReleaseNotes": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string", + "Version": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Release was modified, containing the updated Release + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`BuildInformation`** :span[array of object]{.type-label} + - **`Branch`** :span[string]{.type-label} + - **`BuildEnvironment`** :span[string]{.type-label} + - **`BuildNumber`** :span[string]{.type-label} + - **`BuildUrl`** :span[string]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + - **`IssueTrackerName`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`VcsCommitNumber`** :span[string]{.type-label} + - **`VcsCommitUrl`** :span[string]{.type-label} + - **`VcsRoot`** :span[string]{.type-label} + - **`VcsType`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} +- **`ChannelId`** :span[string]{.type-label} +- **`CustomFields`** :span[object]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IgnoreChannelRules`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectDeploymentProcessSnapshotId`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} +- **`ReleaseNotes`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} + Maximum length 349. +- **`VersionControlReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "BuildInformation": [ + { + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + {} + ], + "IssueTrackerName": "string", + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChannelId": "string", + "CustomFields": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "IgnoreChannelRules": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectDeploymentProcessSnapshotId": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "ReleaseNotes": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string", + "Version": "string", + "VersionControlReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + } +} +``` +::: + +## Delete an existing release, along with all of the deployments, tasks and other associated resources belonging to the release + +:endpoint{method="DELETE" path="/api/\{spaceId\}/releases/\{id\}"} + +Also reachable at `/api/releases/{id}`, `/api/spaces/{spaceIdentifier}/releases/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Release to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Get all of the information necessary for creating or editing a deployment for this release + +:endpoint{method="GET" path="/api/\{spaceId\}/releases/\{id\}/deployments/template"} + +Also reachable at `/api/releases/{id}/deployments/template`, `/api/spaces/{spaceIdentifier}/releases/{id}/deployments/template`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Release. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space. + +**Response** + +`200` — The requested Deployment Template for the release. + +- **`DeploymentNotes`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDeploymentProcessModified`** :span[boolean]{.type-label} +- **`IsGitResourceModified`** :span[boolean]{.type-label} +- **`IsLibraryVariableSetModified`** :span[boolean]{.type-label} +- **`IsVariableSetModified`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`PromoteTo`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`TenantPromotions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`PromoteTo`** :span[array of object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DeploymentNotes": "string", + "Id": "string", + "IsDeploymentProcessModified": true, + "IsGitResourceModified": true, + "IsLibraryVariableSetModified": 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 all defects for a release + +:endpoint{method="GET" path="/api/\{spaceId\}/releases/\{releaseId\}/defects"} + +Also reachable at `/api/releases/{releaseId}/defects`, `/api/spaces/{spaceIdentifier}/releases/{releaseId}/defects`. + +**Path Parameters** + +- **`releaseId`** :span[string]{.type-label} *(required)* + Id of the release. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Get all defects for a release. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + Minimum length 1. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Status`** :span[enum]{.type-label} + Allowed values: `Unresolved`, `Resolved`. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Status": "Unresolved" + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Record defect in a release + +:endpoint{method="POST" path="/api/\{spaceId\}/releases/\{releaseId\}/defects"} + +Also reachable at `/api/releases/{releaseId}/defects`, `/api/spaces/{spaceIdentifier}/releases/{releaseId}/defects`. + +**Path Parameters** + +- **`releaseId`** :span[string]{.type-label} *(required)* + Id of the release. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Description`** :span[string]{.type-label} *(required)* + Defect in the release. Minimum length 1. +- **`ReleaseId`** :span[string]{.type-label} *(required)* + Id of the release. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`Status`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "ReleaseId": "string", + "SpaceId": "string", + "Status": "string" +} +``` +::: + +**Response** + +`200` — The defect resource that was recorded against a release + +- **`Description`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Status`** :span[enum]{.type-label} + Allowed values: `Unresolved`, `Resolved`. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Status": "Unresolved" +} +``` +::: + +## Resolve defect in a release + +:endpoint{method="POST" path="/api/\{spaceId\}/releases/\{releaseId\}/defects/resolve"} + +Also reachable at `/api/releases/{releaseId}/defects/resolve`, `/api/spaces/{spaceIdentifier}/releases/{releaseId}/defects/resolve`. + +**Path Parameters** + +- **`releaseId`** :span[string]{.type-label} *(required)* + Id of the release. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the release. + +**Response** + +`200` — Resolved defect + +- **`Description`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Status`** :span[enum]{.type-label} + Allowed values: `Unresolved`, `Resolved`. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Status": "Unresolved" +} +``` +::: + +## List all of the Deployments that belong to the given Release + +:endpoint{method="GET" path="/api/\{spaceId\}/releases/\{releaseId\}/deployments"} + +Also reachable at `/api/releases/{releaseId}/deployments`, `/api/spaces/{spaceIdentifier}/releases/{releaseId}/deployments`. + +Deployments will be ordered from most recent to least recent. + +**Path Parameters** + +- **`releaseId`** :span[string]{.type-label} *(required)* + ID of the Release to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space to which the Release belongs. + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The list of Deployments for the given Release. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Changes`** :span[array of object]{.type-label} + - **`ChangesMarkdown`** :span[string]{.type-label} + - **`ChannelId`** :span[string]{.type-label} + - **`Comments`** :span[string]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`DebugMode`** :span[string]{.type-label} + - **`DeployedBy`** :span[string]{.type-label} + - **`DeployedById`** :span[string]{.type-label} + - **`DeployedToMachineIds`** :span[array of string]{.type-label} + - **`DeploymentProcessId`** :span[string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. + - **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`FailureEncountered`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`ForcePackageRedeployment`** :span[boolean]{.type-label} + - **`FormValues`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ManifestVariableSetId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Priority`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. + - **`ReleaseId`** :span[string]{.type-label} + - **`SkipActions`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. + - **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`TaskId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + - **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "ChangeRequestSettings": [ + {} + ], + "Changes": [ + {} + ], + "ChangesMarkdown": "string", + "ChannelId": "string", + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "DeploymentProcessId": "string", + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + {} + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "ForcePackageRedeployment": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ReleaseId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get a document that describes what steps will/won't be run during a deployment to a given environment (and tenant if supplied) + +:endpoint{method="GET" path="/api/\{spaceId\}/releases/\{releaseId\}/deployments/preview/\{environmentId\}"} + +Also reachable at `/api/releases/{releaseId}/deployments/preview/{environmentId}`, `/api/releases/{releaseId}/deployments/preview/{environmentId}/{tenantId}`, `/api/spaces/{spaceIdentifier}/releases/{releaseId}/deployments/preview/{environmentId}`, `/api/spaces/{spaceIdentifier}/releases/{releaseId}/deployments/preview/{environmentId}/{tenantId}`, `/api/{spaceId}/releases/{releaseId}/deployments/preview/{environmentId}/{tenantId}`. + +**Path Parameters** + +- **`environmentId`** :span[string]{.type-label} *(required)* + ID of the environment. +- **`releaseId`** :span[string]{.type-label} *(required)* + ID of the release. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the space containing the resources. + +**Query Parameters** + +- **`includeDisabledSteps`** :span[boolean]{.type-label} + Whether to include Disabled Steps in the preview. +- **`tenantId`** :span[string]{.type-label} + ID of the tenant. + +**Response** + +`200` — The requested Release Deployment Preview + +- **`Changes`** :span[array of object]{.type-label} + - **`BuildInformation`** :span[array of object]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + Aggregate of distinct commits from all VersionMetadata. + - **`ReleaseNotes`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} + Aggregate of distinct work items from all VersionMetadata. +- **`ChangesMarkdown`** :span[string]{.type-label} +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StepsToExecute`** :span[array of object]{.type-label} + - **`ActionId`** :span[string]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`ActionNumber`** :span[string]{.type-label} + - **`AvailableTagSets`** :span[array of object]{.type-label} + - **`CanBeSkipped`** :span[boolean]{.type-label} + - **`ExcludedMachines`** :span[array of object]{.type-label} + - **`HasNoApplicableMachines`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`MachineNames`** :span[array of string]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`UnavailableMachines`** :span[array of object]{.type-label} +- **`UseGuidedFailureModeByDefault`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Changes": [ + { + "BuildInformation": [ + {} + ], + "Commits": [ + {} + ], + "ReleaseNotes": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChangesMarkdown": "string", + "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 +} +``` +::: + +## Return an array of documents that describes what steps will/won't be run during deployments to a given set of environments and tenants + +:endpoint{method="POST" path="/api/\{spaceId\}/releases/\{releaseId\}/deployments/previews"} + +Also reachable at `/api/releases/{releaseId}/deployments/previews`, `/api/spaces/{spaceIdentifier}/releases/{releaseId}/deployments/previews`. + +**Path Parameters** + +- **`releaseId`** :span[string]{.type-label} *(required)* + ID of the release. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the space containing the resources. + +**Request Body** + +- **`DeploymentPreviews`** :span[array of object]{.type-label} *(required)* + The array of requests you would like to make. + - **`EnvironmentId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`IncludeDisabledSteps`** :span[boolean]{.type-label} + Whether to include Disabled Steps in the preview. +- **`ReleaseId`** :span[string]{.type-label} *(required)* + ID of the release. +- **`SpaceId`** :span[string]{.type-label} *(required)* + ID of the space containing the resources. + +:::api-example{label="Request"} +```json +{ + "DeploymentPreviews": [ + { + "EnvironmentId": "string", + "TenantId": "string" + } + ], + "IncludeDisabledSteps": true, + "ReleaseId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — The requested array of Release Deployment Previews + +- **`Changes`** :span[array of object]{.type-label} + - **`BuildInformation`** :span[array of object]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + Aggregate of distinct commits from all VersionMetadata. + - **`ReleaseNotes`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} + Aggregate of distinct work items from all VersionMetadata. +- **`ChangesMarkdown`** :span[string]{.type-label} +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StepsToExecute`** :span[array of object]{.type-label} + - **`ActionId`** :span[string]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`ActionNumber`** :span[string]{.type-label} + - **`AvailableTagSets`** :span[array of object]{.type-label} + - **`CanBeSkipped`** :span[boolean]{.type-label} + - **`ExcludedMachines`** :span[array of object]{.type-label} + - **`HasNoApplicableMachines`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`MachineNames`** :span[array of string]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`UnavailableMachines`** :span[array of object]{.type-label} +- **`UseGuidedFailureModeByDefault`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Changes": [ + { + "BuildInformation": [ + {} + ], + "Commits": [ + {} + ], + "ReleaseNotes": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChangesMarkdown": "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 the list of Packages that are missing from the built-in feed for a release + +:endpoint{method="GET" path="/api/\{spaceId\}/releases/\{releaseId\}/missingPackages"} + +Also reachable at `/api/spaces/{spaceIdentifier}/releases/{releaseId}/missingPackages`. + +**Path Parameters** + +- **`releaseId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The list of Packages from the built-in feed missing for a Release. + +- **`Packages`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`Version`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Packages": [ + { + "Id": "string", + "Version": "string" + } + ] +} +``` +::: + +## Get all of the information necessary for creating or editing a deployment for this release + +:endpoint{method="GET" path="/api/\{spaceId\}/releases/\{releaseId\}/progression"} + +Also reachable at `/api/releases/{releaseId}/progression`, `/api/spaces/{spaceIdentifier}/releases/{releaseId}/progression`. + +**Path Parameters** + +- **`releaseId`** :span[string]{.type-label} *(required)* + Id of the release. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Lifecycle progression information necessary for creating or editing a deployment for a release + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NextDeployments`** :span[array of string]{.type-label} +- **`NextDeploymentsMinimumRequired`** :span[integer]{.type-label} +- **`Phases`** :span[array of object]{.type-label} + - **`AutomaticDeploymentTargets`** :span[array of string]{.type-label} + - **`Blocked`** :span[boolean]{.type-label} + - **`Deployments`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsOptionalPhase`** :span[boolean]{.type-label} + - **`IsPriorityPhase`** :span[boolean]{.type-label} + - **`MinimumEnvironmentsBeforePromotion`** :span[integer]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OptionalDeploymentTargets`** :span[array of string]{.type-label} + - **`Progress`** :span[enum]{.type-label} + Allowed values: `Pending`, `Current`, `Complete`. + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NextDeployments": [ + "string" + ], + "NextDeploymentsMinimumRequired": 0, + "Phases": [ + { + "AutomaticDeploymentTargets": [ + "string" + ], + "Blocked": true, + "Deployments": [ + {} + ], + "Id": "string", + "IsOptionalPhase": true, + "IsPriorityPhase": true, + "MinimumEnvironmentsBeforePromotion": 0, + "Name": "string", + "OptionalDeploymentTargets": [ + "string" + ], + "Progress": "Pending" + } + ] +} +``` +::: + +## Update the release notes on an existing Release + +:endpoint{method="POST" path="/api/\{spaceId\}/releases/\{releaseId\}/release-notes"} + +Also reachable at `/api/releases/{releaseId}/release-notes`, `/api/spaces/{spaceIdentifier}/releases/{releaseId}/release-notes`. + +Only the release notes are changed and everything else about the Release is left alone. Variable expressions in the notes are evaluated before they are stored, so the saved text is the resolved one. + +**Path Parameters** + +- **`releaseId`** :span[string]{.type-label} *(required)* + Id of the release. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`ReleaseId`** :span[string]{.type-label} *(required)* + The ID of the release, for example 'Releases-123'. +- **`ReleaseNotes`** :span[string]{.type-label} *(required)* + The notes to store, replacing whatever the release currently has. Markdown is supported. Build information is in scope, so expressions such as #{Octopus.Release.WorkItems} and #{Octopus.Release.Number} are resolved before the notes are saved. Send an empty string to clear them. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "ReleaseId": "string", + "ReleaseNotes": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the release notes were updated, containing the updated Release + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`BuildInformation`** :span[array of object]{.type-label} + - **`Branch`** :span[string]{.type-label} + - **`BuildEnvironment`** :span[string]{.type-label} + - **`BuildNumber`** :span[string]{.type-label} + - **`BuildUrl`** :span[string]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + - **`IssueTrackerName`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`VcsCommitNumber`** :span[string]{.type-label} + - **`VcsCommitUrl`** :span[string]{.type-label} + - **`VcsRoot`** :span[string]{.type-label} + - **`VcsType`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} +- **`ChannelId`** :span[string]{.type-label} +- **`CustomFields`** :span[object]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IgnoreChannelRules`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectDeploymentProcessSnapshotId`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} +- **`ReleaseNotes`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} + Maximum length 349. +- **`VersionControlReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "BuildInformation": [ + { + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + {} + ], + "IssueTrackerName": "string", + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChannelId": "string", + "CustomFields": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "IgnoreChannelRules": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectDeploymentProcessSnapshotId": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "ReleaseNotes": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string", + "Version": "string", + "VersionControlReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + } +} +``` +::: + +## Update the Variable Snapshot for a Release + +:endpoint{method="POST" path="/api/\{spaceId\}/releases/\{releaseId\}/snapshot-variables"} + +Also reachable at `/api/releases/{releaseId}/snapshot-variables`, `/api/spaces/{spaceIdentifier}/releases/{releaseId}/snapshot-variables`. + +**Path Parameters** + +- **`releaseId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Confirmation that the Variable Snapshot for a Release was updated, containing the updated Release + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`BuildInformation`** :span[array of object]{.type-label} + - **`Branch`** :span[string]{.type-label} + - **`BuildEnvironment`** :span[string]{.type-label} + - **`BuildNumber`** :span[string]{.type-label} + - **`BuildUrl`** :span[string]{.type-label} + - **`Commits`** :span[array of object]{.type-label} + - **`IssueTrackerName`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`VcsCommitNumber`** :span[string]{.type-label} + - **`VcsCommitUrl`** :span[string]{.type-label} + - **`VcsRoot`** :span[string]{.type-label} + - **`VcsType`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} + - **`WorkItems`** :span[array of object]{.type-label} +- **`ChannelId`** :span[string]{.type-label} +- **`CustomFields`** :span[object]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IgnoreChannelRules`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectDeploymentProcessSnapshotId`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} +- **`ReleaseNotes`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Version`** :span[string]{.type-label} + Maximum length 349. +- **`VersionControlReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "BuildInformation": [ + { + "Branch": "string", + "BuildEnvironment": "string", + "BuildNumber": "string", + "BuildUrl": "string", + "Commits": [ + {} + ], + "IssueTrackerName": "string", + "PackageId": "string", + "VcsCommitNumber": "string", + "VcsCommitUrl": "string", + "VcsRoot": "string", + "VcsType": "string", + "Version": "string", + "WorkItems": [ + {} + ] + } + ], + "ChannelId": "string", + "CustomFields": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Id": "string", + "IgnoreChannelRules": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectDeploymentProcessSnapshotId": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "ReleaseNotes": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string", + "Version": "string", + "VersionControlReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + } +} +``` +::: diff --git a/src/pages/docs/api/reporting.md b/src/pages/docs/api/reporting.md new file mode 100644 index 0000000000..5e6148630d --- /dev/null +++ b/src/pages/docs/api/reporting.md @@ -0,0 +1,42 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Reporting +--- + +## Get an XML report of deployments + +:endpoint{method="GET" path="/api/\{spaceId\}/reporting/deployments/xml"} + +Also reachable at `/api/reporting/deployments/xml`, `/api/spaces/{spaceIdentifier}/reporting/deployments/xml`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`environmentId`** :span[string]{.type-label} + An Environment ID, to limit the set of Deployments to deployed to a particular Environment. Example: Environments-1. +- **`fromCompletedTime`** :span[string]{.type-label} + A date/time, to limit the set of Deployments to those which completed after a given moment. Example: 2000-01-01T01:23. Format `date-time`. +- **`fromStartTime`** :span[string]{.type-label} + A date/time, to limit the set of Deployments to those which started after a given moment. Example: 2000-01-01T01:23. Format `date-time`. +- **`projectId`** :span[string]{.type-label} + A Project ID, to limit the set of Deployments to those from a particular Project. Example: Projects-1. +- **`toCompletedTime`** :span[string]{.type-label} + A date/time, to limit the set of Deployments to those which completed before a given moment. Example: 2000-01-01T01:23. Format `date-time`. +- **`toStartTime`** :span[string]{.type-label} + A date/time, to limit the set of Deployments to those which started before a given moment. Example: 2000-01-01T01:23. Format `date-time`. + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: diff --git a/src/pages/docs/api/retention.md b/src/pages/docs/api/retention.md new file mode 100644 index 0000000000..6b78bca299 --- /dev/null +++ b/src/pages/docs/api/retention.md @@ -0,0 +1,146 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Retention +--- + +## Get the default retention configuration + +:endpoint{method="GET" path="/api/configuration/retention-default"} + +**Response** + +`200` — The default retention configuration + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`RetentionDays`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "RetentionDays": 0 +} +``` +::: + +## Update the default retention configuration + +:endpoint{method="PUT" path="/api/configuration/retention-default"} + +**Request Body** + +- **`RetentionDays`** :span[integer]{.type-label} + +:::api-example{label="Request"} +```json +{ + "RetentionDays": 0 +} +``` +::: + +**Response** + +`200` — Success + +## Get the configured default retention policies for the given retention type + +:endpoint{method="GET" path="/api/\{spaceId\}/retentionpolicies"} + +Also reachable at `/api/retentionpolicies`, `/api/spaces/{spaceIdentifier}/retentionpolicies`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`retentionType`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Returns the configured default retention policy values + +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`RetentionType`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "Name": "string", + "RetentionType": "string", + "SpaceId": "string" +} +``` +::: + +## Modify a default retention policy + +:endpoint{method="PUT" path="/api/\{spaceId\}/retentionpolicies/\{id\}"} + +Also reachable at `/api/retentionpolicies/{id}`, `/api/spaces/{spaceIdentifier}/retentionpolicies/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the default retention policy. +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the space that contains the default retention policy. + +**Request Body** + +- **`Id`** :span[string]{.type-label} *(required)* + The id of the default retention policy. +- **`RetentionType`** :span[string]{.type-label} *(required)* + The type of the default retention policy. ["MachinePackageCache", "LifecycleRetention", "TentacleRetention", "RunbookRetention"]. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The id of the space that contains the default retention policy. + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "RetentionType": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — The response returned from the request to modify a default retention policy. + +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`RetentionType`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "Name": "string", + "RetentionType": "string", + "SpaceId": "string" +} +``` +::: diff --git a/src/pages/docs/api/runbook-processes.md b/src/pages/docs/api/runbook-processes.md new file mode 100644 index 0000000000..fe15070c51 --- /dev/null +++ b/src/pages/docs/api/runbook-processes.md @@ -0,0 +1,1150 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Runbook Processes +--- + +## Get a list of Runbook Processes + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbookProcesses"} + +Also reachable at `/api/projects/{projectId}/runbookProcesses`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookProcesses`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project containing the Runbook Processes. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Returns the Runbook Processes + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastSnapshotId`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ProjectId`** :span[string]{.type-label} + - **`RunbookId`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Steps`** :span[array of object]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "RunbookId": "string", + "SpaceId": "string", + "Steps": [ + {} + ], + "Version": 0 + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get the runbook process for the given ID + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbookProcesses/\{id\}"} + +Also reachable at `/api/projects/{projectId}/runbookProcesses/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookProcesses/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the runbook process to retrieve. +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Returns the Runbook Process + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "RunbookId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +## Modify a Runbook Process + +:endpoint{method="PUT" path="/api/\{spaceId\}/projects/\{projectId\}/runbookProcesses/\{id\}"} + +Also reachable at `/api/projects/{projectId}/runbookProcesses/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookProcesses/{id}`. + +Only allowed for Runbook Processes owned by a project. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Gets or sets a unique identifier for this resource. +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "RunbookId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +**Response** + +`200` — Confirmation that the Runbook Process has been modified, containing the updated Process + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "RunbookId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +## Get all of the information necessary for creating or editing a Runbook Snapshot using this Runbook Process + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbookProcesses/\{id\}/runbookSnapshotTemplate"} + +Also reachable at `/api/projects/{projectId}/runbookProcesses/{id}/runbookSnapshotTemplate`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookProcesses/{id}/runbookSnapshotTemplate`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Runbook Process. +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project containing this resource. Will be inferred if not provided. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Runbook Process Snapshot Template + +- **`GitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`GitResourceSelectedLastRelease`** :span[object]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NextNameIncrement`** :span[string]{.type-label} +- **`Packages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`FeedId`** :span[string]{.type-label} + - **`FeedName`** :span[string]{.type-label} + - **`FixedVersion`** :span[string]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + - **`NuGetFeedName`** :span[string]{.type-label} + - **`NuGetPackageId`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`VersionSelectedLastRelease`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`RunbookProcessId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 the runbook process for the given ID + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/runbookProcesses/\{id\}"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/runbookProcesses/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/runbookProcesses/{id}`. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* + The Git ref to read the runbook process from. +- **`id`** :span[string]{.type-label} *(required)* + The ID of the runbook process to retrieve. +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project the runbook process belongs to. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Returns the Runbook Process + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "RunbookId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +## Modify a Runbook Process + +:endpoint{method="PUT" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/runbookProcesses/\{id\}"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/runbookProcesses/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/runbookProcesses/{id}`. + +Only allowed for Runbook Processes owned by a project. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* + The GitRef containing the resource(s). +- **`id`** :span[string]{.type-label} *(required)* + Gets or sets a unique identifier for this resource. +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChangeDescription`** :span[string]{.type-label} + The commit message for updating the Git repository. +- **`GitRef`** :span[string]{.type-label} *(required)* + The GitRef containing the resource(s). +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "ChangeDescription": "string", + "GitRef": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "RunbookId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +**Response** + +`200` — Confirmation that the Runbook Process has been modified, containing the updated Process + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "RunbookId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +## Get a list of Runbook Processes + +:endpoint{method="GET" path="/api/\{spaceId\}/runbookProcesses"} + +Also reachable at `/api/runbookProcesses`, `/api/spaces/{spaceIdentifier}/runbookProcesses`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Returns the Runbook Processes + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastSnapshotId`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ProjectId`** :span[string]{.type-label} + - **`RunbookId`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Steps`** :span[array of object]{.type-label} + - **`Version`** :span[integer]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "RunbookId": "string", + "SpaceId": "string", + "Steps": [ + {} + ], + "Version": 0 + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get the runbook process for the given ID + +:endpoint{method="GET" path="/api/\{spaceId\}/runbookProcesses/\{id\}"} + +Also reachable at `/api/runbookProcesses/{id}`, `/api/spaces/{spaceIdentifier}/runbookProcesses/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the runbook process to retrieve. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Returns the Runbook Process + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "RunbookId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +## Modify a Runbook Process + +:endpoint{method="PUT" path="/api/\{spaceId\}/runbookProcesses/\{id\}"} + +Also reachable at `/api/runbookProcesses/{id}`, `/api/spaces/{spaceIdentifier}/runbookProcesses/{id}`. + +Only allowed for Runbook Processes owned by a project. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Gets or sets a unique identifier for this resource. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "RunbookId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +**Response** + +`200` — Confirmation that the Runbook Process has been modified, containing the updated Process + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastSnapshotId`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectId`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Steps`** :span[array of object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Condition`** :span[enum]{.type-label} + Allowed values: `Success`, `Failure`, `Always`, `Variable`. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`PackageRequirement`** :span[enum]{.type-label} + Allowed values: `LetOctopusDecide`, `BeforePackageAcquisition`, `AfterPackageAcquisition`. + - **`Properties`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`StartTrigger`** :span[enum]{.type-label} + Allowed values: `StartAfterPrevious`, `StartWithPrevious`. + - **`Type`** :span[string]{.type-label} + Either "Step" or "ProcessTemplateUsage". Defaults to "Step" if no type is provided. +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastSnapshotId": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "RunbookId": "string", + "SpaceId": "string", + "Steps": [ + { + "Actions": [ + {} + ], + "Condition": "Success", + "Id": "string", + "Name": "string", + "PackageRequirement": "LetOctopusDecide", + "Properties": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "Slug": "string", + "StartTrigger": "StartAfterPrevious", + "Type": "string" + } + ], + "Version": 0 +} +``` +::: + +## Get all of the information necessary for creating or editing a Runbook Snapshot using this Runbook Process + +:endpoint{method="GET" path="/api/\{spaceId\}/runbookProcesses/\{id\}/runbookSnapshotTemplate"} + +Also reachable at `/api/runbookProcesses/{id}/runbookSnapshotTemplate`, `/api/spaces/{spaceIdentifier}/runbookProcesses/{id}/runbookSnapshotTemplate`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Runbook Process. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`projectId`** :span[string]{.type-label} + The ID of the project containing this resource. Will be inferred if not provided. + +**Response** + +`200` — The requested Runbook Process Snapshot Template + +- **`GitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`GitResourceSelectedLastRelease`** :span[object]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NextNameIncrement`** :span[string]{.type-label} +- **`Packages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`FeedId`** :span[string]{.type-label} + - **`FeedName`** :span[string]{.type-label} + - **`FixedVersion`** :span[string]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + - **`NuGetFeedName`** :span[string]{.type-label} + - **`NuGetPackageId`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`VersionSelectedLastRelease`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`RunbookProcessId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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" +} +``` +::: diff --git a/src/pages/docs/api/runbook-runs.md b/src/pages/docs/api/runbook-runs.md new file mode 100644 index 0000000000..0d3d856097 --- /dev/null +++ b/src/pages/docs/api/runbook-runs.md @@ -0,0 +1,1742 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Runbook Runs +--- + +## Get a list of Runbook Runs + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbookRuns"} + +Also reachable at `/api/projects/{projectId}/runbookRuns`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookRuns`. + +Lists all of the runbookRuns in the supplied Octopus Deploy Space, from projects, snapshots and environments accessible by the current user. The results will be sorted from most recent to least recent runbookRun. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`environments`** :span[array of string]{.type-label} + Environment Ids to filter results to only Runbook Runs with the given Environment Ids. +- **`ids`** :span[array of string]{.type-label} + Runbook Run Ids to filter results to only Runbook Runs with the given Ids. +- **`partialName`** :span[string]{.type-label} + A partial name, to limit the set of Runbook Runs to those with a name that includes the partial name. +- **`projects`** :span[array of string]{.type-label} + Project Ids to filter results to only Runbook Runs with the given Project Ids. +- **`runbooks`** :span[array of string]{.type-label} + Runbook Ids to filter results to only Runbooks with the given Ids. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`taskState`** :span[enum]{.type-label} + Task State to filter results to only Deployments with the given Task State. + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. +- **`tenants`** :span[array of string]{.type-label} + Tenant Ids to filter results to only Runbook Runs with the given Tenant Ids. + +**Response** + +`200` — The requested list of Runbook Runs + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Comments`** :span[string]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`DebugMode`** :span[string]{.type-label} + - **`DeployedBy`** :span[string]{.type-label} + - **`DeployedById`** :span[string]{.type-label} + - **`DeployedToMachineIds`** :span[array of string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. + - **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`FailureEncountered`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`FormValues`** :span[object]{.type-label} + - **`FrozenRunbookProcessId`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ManifestVariableSetId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Priority`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. + - **`RunbookId`** :span[string]{.type-label} + Minimum length 1. + - **`RunbookName`** :span[string]{.type-label} + - **`RunbookSnapshotId`** :span[string]{.type-label} + Minimum length 1. + - **`SkipActions`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. + - **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`TaskId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + - **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "ChangeRequestSettings": [ + {} + ], + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + {} + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "FrozenRunbookProcessId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "RunbookId": "string", + "RunbookName": "string", + "RunbookSnapshotId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new Runbook Run + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/runbookRuns"} + +Also reachable at `/api/projects/{projectId}/runbookRuns`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookRuns`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `ServiceNow`, `JiraServiceManagement`. +- **`Comments`** :span[string]{.type-label} +- **`DebugMode`** :span[string]{.type-label} +- **`EnvironmentId`** :span[string]{.type-label} *(required)* +- **`ExcludedMachineIds`** :span[array of string]{.type-label} +- **`ExcludedTargetTagIds`** :span[array of string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`FormValues`** :span[object]{.type-label} +- **`Priority`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`QueueTime`** :span[string]{.type-label} + Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. +- **`RunbookId`** :span[string]{.type-label} *(required)* +- **`RunbookSnapshotId`** :span[string]{.type-label} *(required)* +- **`SkipActions`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`SpecificMachineIds`** :span[array of string]{.type-label} +- **`SpecificTargetTagIds`** :span[array of string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`UseGuidedFailure`** :span[boolean]{.type-label} + +:::api-example{label="Request"} +```json +{ + "ChangeRequestSettings": [ + { + "Type": "ServiceNow" + } + ], + "Comments": "string", + "DebugMode": "string", + "EnvironmentId": "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", + "RunbookSnapshotId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TenantId": "string", + "UseGuidedFailure": true +} +``` +::: + +**Response** + +`201` — Created + +- **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `ServiceNow`, `JiraServiceManagement`. +- **`Comments`** :span[string]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DebugMode`** :span[string]{.type-label} +- **`DeployedBy`** :span[string]{.type-label} +- **`DeployedById`** :span[string]{.type-label} +- **`DeployedToMachineIds`** :span[array of string]{.type-label} +- **`EnvironmentId`** :span[string]{.type-label} +- **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. +- **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`Steps`** :span[array of object]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`FailureEncountered`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`FormValues`** :span[object]{.type-label} +- **`FrozenRunbookProcessId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ManifestVariableSetId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`Priority`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. +- **`RunbookId`** :span[string]{.type-label} + Minimum length 1. +- **`RunbookName`** :span[string]{.type-label} +- **`RunbookSnapshotId`** :span[string]{.type-label} + Minimum length 1. +- **`SkipActions`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. +- **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`TaskId`** :span[string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. + +:::api-example{label="Response"} +```json +{ + "ChangeRequestSettings": [ + { + "Type": "ServiceNow" + } + ], + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + { + "CorrelationId": "string", + "Slug": "string" + } + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "FrozenRunbookProcessId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "RunbookId": "string", + "RunbookName": "string", + "RunbookSnapshotId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true +} +``` +::: + +## Get a Runbook Run by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbookRuns/\{id\}"} + +Also reachable at `/api/projects/{projectId}/runbookRuns/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookRuns/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook Run to load. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project to which the Runbook Run belongs. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space to which the Runbook Run belongs. + +**Response** + +`200` — The requested Runbook Run + +- **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `ServiceNow`, `JiraServiceManagement`. +- **`Comments`** :span[string]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DebugMode`** :span[string]{.type-label} +- **`DeployedBy`** :span[string]{.type-label} +- **`DeployedById`** :span[string]{.type-label} +- **`DeployedToMachineIds`** :span[array of string]{.type-label} +- **`EnvironmentId`** :span[string]{.type-label} +- **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. +- **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`Steps`** :span[array of object]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`FailureEncountered`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`FormValues`** :span[object]{.type-label} +- **`FrozenRunbookProcessId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ManifestVariableSetId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`Priority`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. +- **`RunbookId`** :span[string]{.type-label} + Minimum length 1. +- **`RunbookName`** :span[string]{.type-label} +- **`RunbookSnapshotId`** :span[string]{.type-label} + Minimum length 1. +- **`SkipActions`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. +- **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`TaskId`** :span[string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. + +:::api-example{label="Response"} +```json +{ + "ChangeRequestSettings": [ + { + "Type": "ServiceNow" + } + ], + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + { + "CorrelationId": "string", + "Slug": "string" + } + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "FrozenRunbookProcessId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "RunbookId": "string", + "RunbookName": "string", + "RunbookSnapshotId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true +} +``` +::: + +## Delete an existing Runbook Run + +:endpoint{method="DELETE" path="/api/\{spaceId\}/projects/\{projectId\}/runbookruns/\{id\}"} + +Also reachable at `/api/projects/{projectId}/runbookruns/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookruns/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook Run to delete. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project to which the Runbook Run belongs. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space to which the Runbook Run belongs. + +**Response** + +`200` — Success + +## Create a new Runbook run based on an existing runbook run + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/runbookruns/\{runbookRunId\}/retry/v1"} + +Also reachable at `/api/projects/{projectId}/runbookruns/{runbookRunId}/retry/v1`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookruns/{runbookRunId}/retry/v1`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`runbookRunId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Runbook run that was retried + +- **`Resource`** :span[object]{.type-label} + - **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Comments`** :span[string]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`DebugMode`** :span[string]{.type-label} + - **`DeployedBy`** :span[string]{.type-label} + - **`DeployedById`** :span[string]{.type-label} + - **`DeployedToMachineIds`** :span[array of string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. + - **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`FailureEncountered`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`FormValues`** :span[object]{.type-label} + - **`FrozenRunbookProcessId`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ManifestVariableSetId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Priority`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. + - **`RunbookId`** :span[string]{.type-label} + Minimum length 1. + - **`RunbookName`** :span[string]{.type-label} + - **`RunbookSnapshotId`** :span[string]{.type-label} + Minimum length 1. + - **`SkipActions`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. + - **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`TaskId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + - **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. + +:::api-example{label="Response"} +```json +{ + "Resource": { + "ChangeRequestSettings": [ + { + "Type": "ServiceNow" + } + ], + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + {} + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "FrozenRunbookProcessId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "RunbookId": "string", + "RunbookName": "string", + "RunbookSnapshotId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true + } +} +``` +::: + +## Create a new Runbook Run + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/runbooks/\{runbookId\}/run/v1"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/runbooks/{runbookId}/run/v1`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/runbooks/{runbookId}/run/v1`. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`runbookId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`Notes`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`RunbookId`** :span[string]{.type-label} *(required)* +- **`Runs`** :span[array of object]{.type-label} *(required)* + - **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Comments`** :span[string]{.type-label} + - **`DebugMode`** :span[string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} *(required)* + - **`ExcludedMachineIds`** :span[array of string]{.type-label} + - **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`FormValues`** :span[object]{.type-label} + - **`Priority`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. + - **`SkipActions`** :span[array of string]{.type-label} + - **`SpecificMachineIds`** :span[array of string]{.type-label} + - **`SpecificTargetTagIds`** :span[array of string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + - **`UseGuidedFailure`** :span[boolean]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} *(required)* + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "GitRef": "string", + "Notes": "string", + "ProjectId": "string", + "RunbookId": "string", + "Runs": [ + { + "ChangeRequestSettings": [ + {} + ], + "Comments": "string", + "DebugMode": "string", + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "FailTargetDiscovery": true, + "ForcePackageDownload": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Priority": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "SkipActions": [ + "string" + ], + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TenantId": "string", + "UseGuidedFailure": true + } + ], + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — The newly-created Runbook run + +- **`Resources`** :span[array of object]{.type-label} + - **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Comments`** :span[string]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`DebugMode`** :span[string]{.type-label} + - **`DeployedBy`** :span[string]{.type-label} + - **`DeployedById`** :span[string]{.type-label} + - **`DeployedToMachineIds`** :span[array of string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. + - **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`FailureEncountered`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`FormValues`** :span[object]{.type-label} + - **`FrozenRunbookProcessId`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ManifestVariableSetId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Priority`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. + - **`RunbookId`** :span[string]{.type-label} + Minimum length 1. + - **`RunbookName`** :span[string]{.type-label} + - **`RunbookSnapshotId`** :span[string]{.type-label} + Minimum length 1. + - **`SkipActions`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. + - **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`TaskId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + - **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. + +:::api-example{label="Response"} +```json +{ + "Resources": [ + { + "ChangeRequestSettings": [ + {} + ], + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + {} + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "FrozenRunbookProcessId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "RunbookId": "string", + "RunbookName": "string", + "RunbookSnapshotId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true + } + ] +} +``` +::: + +## Create a new runbook run + +:endpoint{method="POST" path="/api/\{spaceId\}/runbook-runs/create/v1"} + +Also reachable at `/api/runbook-runs/create/v1`, `/api/spaces/{spaceIdentifier}/runbook-runs/create/v1`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`DebugMode`** :span[string]{.type-label} + Contributes the OctopusPrintVariables and OctopusPrintEvaluatedVariables variables to the execution. One of "None", "Log" or "Debug"; leave unset for the default of "None". +- **`DeploymentFreezeNames`** :span[array of string]{.type-label} + Active deployment freezes to override so this execution can proceed despite them. Overriding a freeze bypasses a deliberate block on deploying, so only set this when explicitly asked to. Requires DeploymentFreezeOverrideReason. +- **`DeploymentFreezeOverrideReason`** :span[string]{.type-label} + Required, and must not be blank, whenever DeploymentFreezeNames is non-empty. Recorded against the override. +- **`EnvironmentNames`** :span[array of string]{.type-label} *(required)* +- **`ExcludedMachineNames`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. +- **`ExcludedTargetTagNames`** :span[array of string]{.type-label} + A collection of deployment target tags (canonical names in format TagSetName/TagName) that should be excluded from the deployment. +- **`ForcePackageDownload`** :span[boolean]{.type-label} + Whether to force downloading of already installed packages (flag, default false). +- **`NoRunAfter`** :span[string]{.type-label} + Time at which a scheduled execution should expire if it has not started, specified as any valid DateTimeOffset format, and assuming the time zone is the current local time zone. Only meaningful alongside RunAt. Format `date-time`. +- **`Priority`** :span[string]{.type-label} + Whether this execution jumps the task queue ahead of other queued tasks. One of "LifecycleDefault" (use the lifecycle's configured setting), "On" or "Off". +- **`ProjectName`** :span[string]{.type-label} *(required)* +- **`RunAt`** :span[string]{.type-label} + Time at which the execution should start (scheduling it for later), specified as any valid DateTimeOffset format, and assuming the time zone is the current local time zone. Format `date-time`. +- **`RunbookName`** :span[string]{.type-label} *(required)* +- **`SkipStepNames`** :span[array of string]{.type-label} + Steps that are to be skipped for this execution. A name that matches no step is logged as a warning rather than failing the command, so check the step name carefully. +- **`Snapshot`** :span[string]{.type-label} + Name or ID of the snapshot to run. If not supplied, the command will attempt to use the published snapshot. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`SpaceIdOrName`** :span[string]{.type-label} *(required)* + Both this and SpaceId are required, and normally hold the same space ID; set both. +- **`SpecificMachineNames`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. A name that matches no machine fails the command. +- **`SpecificTargetTagNames`** :span[array of string]{.type-label} + A collection of deployment target tags (canonical names in format TagSetName/TagName) that should be included in the deployment. +- **`TenantTags`** :span[array of string]{.type-label} + The tenant tags to filter tenants to deploy. +- **`Tenants`** :span[array of string]{.type-label} + The tenants to deploy. +- **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. +- **`Variables`** :span[object]{.type-label} + Name/value pairs for prompted variables. A prompted variable that is required and has no value supplied here fails the command, naming the variable. + +:::api-example{label="Request"} +```json +{ + "DebugMode": "string", + "DeploymentFreezeNames": [ + "string" + ], + "DeploymentFreezeOverrideReason": "string", + "EnvironmentNames": [ + "string" + ], + "ExcludedMachineNames": [ + "string" + ], + "ExcludedTargetTagNames": [ + "string" + ], + "ForcePackageDownload": true, + "NoRunAfter": "2020-01-01T00:00:00.000Z", + "Priority": "string", + "ProjectName": "string", + "RunAt": "2020-01-01T00:00:00.000Z", + "RunbookName": "string", + "SkipStepNames": [ + "string" + ], + "Snapshot": "string", + "SpaceId": "string", + "SpaceIdOrName": "string", + "SpecificMachineNames": [ + "string" + ], + "SpecificTargetTagNames": [ + "string" + ], + "TenantTags": [ + "string" + ], + "Tenants": [ + "string" + ], + "UseGuidedFailure": true, + "Variables": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +**Response** + +`200` — Server tasks associated with the newly-created Runbook Run + +- **`RunbookRunServerTasks`** :span[array of object]{.type-label} + - **`RunbookRunId`** :span[string]{.type-label} + - **`ServerTaskId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "RunbookRunServerTasks": [ + { + "RunbookRunId": "string", + "ServerTaskId": "string" + } + ] +} +``` +::: + +## Get a list of Runbook Runs + +:endpoint{method="GET" path="/api/\{spaceId\}/runbookRuns"} + +Also reachable at `/api/runbookRuns`, `/api/spaces/{spaceIdentifier}/runbookRuns`. + +Lists all of the runbookRuns in the supplied Octopus Deploy Space, from projects, snapshots and environments accessible by the current user. The results will be sorted from most recent to least recent runbookRun. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`environments`** :span[array of string]{.type-label} + Environment Ids to filter results to only Runbook Runs with the given Environment Ids. +- **`ids`** :span[array of string]{.type-label} + Runbook Run Ids to filter results to only Runbook Runs with the given Ids. +- **`partialName`** :span[string]{.type-label} + A partial name, to limit the set of Runbook Runs to those with a name that includes the partial name. +- **`projects`** :span[array of string]{.type-label} + Project Ids to filter results to only Runbook Runs with the given Project Ids. +- **`runbooks`** :span[array of string]{.type-label} + Runbook Ids to filter results to only Runbooks with the given Ids. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`taskState`** :span[enum]{.type-label} + Task State to filter results to only Deployments with the given Task State. + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. +- **`tenants`** :span[array of string]{.type-label} + Tenant Ids to filter results to only Runbook Runs with the given Tenant Ids. + +**Response** + +`200` — The requested list of Runbook Runs + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Comments`** :span[string]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`DebugMode`** :span[string]{.type-label} + - **`DeployedBy`** :span[string]{.type-label} + - **`DeployedById`** :span[string]{.type-label} + - **`DeployedToMachineIds`** :span[array of string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. + - **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`FailureEncountered`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`FormValues`** :span[object]{.type-label} + - **`FrozenRunbookProcessId`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ManifestVariableSetId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Priority`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. + - **`RunbookId`** :span[string]{.type-label} + Minimum length 1. + - **`RunbookName`** :span[string]{.type-label} + - **`RunbookSnapshotId`** :span[string]{.type-label} + Minimum length 1. + - **`SkipActions`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. + - **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`TaskId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + - **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "ChangeRequestSettings": [ + {} + ], + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + {} + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "FrozenRunbookProcessId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "RunbookId": "string", + "RunbookName": "string", + "RunbookSnapshotId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new Runbook Run + +:endpoint{method="POST" path="/api/\{spaceId\}/runbookRuns"} + +Also reachable at `/api/runbookRuns`, `/api/spaces/{spaceIdentifier}/runbookRuns`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `ServiceNow`, `JiraServiceManagement`. +- **`Comments`** :span[string]{.type-label} +- **`DebugMode`** :span[string]{.type-label} +- **`EnvironmentId`** :span[string]{.type-label} *(required)* +- **`ExcludedMachineIds`** :span[array of string]{.type-label} +- **`ExcludedTargetTagIds`** :span[array of string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`FormValues`** :span[object]{.type-label} +- **`Priority`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`QueueTime`** :span[string]{.type-label} + Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. +- **`RunbookId`** :span[string]{.type-label} *(required)* +- **`RunbookSnapshotId`** :span[string]{.type-label} *(required)* +- **`SkipActions`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`SpecificMachineIds`** :span[array of string]{.type-label} +- **`SpecificTargetTagIds`** :span[array of string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`UseGuidedFailure`** :span[boolean]{.type-label} + +:::api-example{label="Request"} +```json +{ + "ChangeRequestSettings": [ + { + "Type": "ServiceNow" + } + ], + "Comments": "string", + "DebugMode": "string", + "EnvironmentId": "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", + "RunbookSnapshotId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TenantId": "string", + "UseGuidedFailure": true +} +``` +::: + +**Response** + +`201` — Created + +- **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `ServiceNow`, `JiraServiceManagement`. +- **`Comments`** :span[string]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DebugMode`** :span[string]{.type-label} +- **`DeployedBy`** :span[string]{.type-label} +- **`DeployedById`** :span[string]{.type-label} +- **`DeployedToMachineIds`** :span[array of string]{.type-label} +- **`EnvironmentId`** :span[string]{.type-label} +- **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. +- **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`Steps`** :span[array of object]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`FailureEncountered`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`FormValues`** :span[object]{.type-label} +- **`FrozenRunbookProcessId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ManifestVariableSetId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`Priority`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. +- **`RunbookId`** :span[string]{.type-label} + Minimum length 1. +- **`RunbookName`** :span[string]{.type-label} +- **`RunbookSnapshotId`** :span[string]{.type-label} + Minimum length 1. +- **`SkipActions`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. +- **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`TaskId`** :span[string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. + +:::api-example{label="Response"} +```json +{ + "ChangeRequestSettings": [ + { + "Type": "ServiceNow" + } + ], + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + { + "CorrelationId": "string", + "Slug": "string" + } + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "FrozenRunbookProcessId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "RunbookId": "string", + "RunbookName": "string", + "RunbookSnapshotId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true +} +``` +::: + +## Get a Runbook Run by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/runbookRuns/\{id\}"} + +Also reachable at `/api/runbookRuns/{id}`, `/api/spaces/{spaceIdentifier}/runbookRuns/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook Run to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space to which the Runbook Run belongs. + +**Query Parameters** + +- **`projectId`** :span[string]{.type-label} + ID of the Project to which the Runbook Run belongs. + +**Response** + +`200` — The requested Runbook Run + +- **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `ServiceNow`, `JiraServiceManagement`. +- **`Comments`** :span[string]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DebugMode`** :span[string]{.type-label} +- **`DeployedBy`** :span[string]{.type-label} +- **`DeployedById`** :span[string]{.type-label} +- **`DeployedToMachineIds`** :span[array of string]{.type-label} +- **`EnvironmentId`** :span[string]{.type-label} +- **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. +- **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`Steps`** :span[array of object]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`FailureEncountered`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`FormValues`** :span[object]{.type-label} +- **`FrozenRunbookProcessId`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ManifestVariableSetId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`Priority`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. +- **`RunbookId`** :span[string]{.type-label} + Minimum length 1. +- **`RunbookName`** :span[string]{.type-label} +- **`RunbookSnapshotId`** :span[string]{.type-label} + Minimum length 1. +- **`SkipActions`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. +- **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". +- **`TaskId`** :span[string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. + +:::api-example{label="Response"} +```json +{ + "ChangeRequestSettings": [ + { + "Type": "ServiceNow" + } + ], + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + { + "CorrelationId": "string", + "Slug": "string" + } + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "FrozenRunbookProcessId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "RunbookId": "string", + "RunbookName": "string", + "RunbookSnapshotId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true +} +``` +::: + +## Delete an existing Runbook Run + +:endpoint{method="DELETE" path="/api/\{spaceId\}/runbookruns/\{id\}"} + +Also reachable at `/api/runbookruns/{id}`, `/api/spaces/{spaceIdentifier}/runbookruns/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook Run to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + ID of the Space to which the Runbook Run belongs. + +**Response** + +`200` — Success diff --git a/src/pages/docs/api/runbook-snapshots.md b/src/pages/docs/api/runbook-snapshots.md new file mode 100644 index 0000000000..bc9d65c55e --- /dev/null +++ b/src/pages/docs/api/runbook-snapshots.md @@ -0,0 +1,2859 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Runbook Snapshots +--- + +## Get the packages and Git references that were used in a Runbook run + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbookRuns/\{id\}/details/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookRuns/{id}/details/v1`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook run to load packages for. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project to get Runbook run packages for. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Packages and Git references that were used in a Runbook run + +- **`GitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`GitResourceSelectedLastRelease`** :span[object]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. +- **`Packages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`FeedId`** :span[string]{.type-label} + - **`FeedName`** :span[string]{.type-label} + - **`FixedVersion`** :span[string]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + - **`NuGetFeedName`** :span[string]{.type-label} + - **`NuGetPackageId`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`VersionSelectedLastRelease`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "GitResources": [ + { + "ActionName": "string", + "DefaultBranch": "string", + "FilePathFilters": [ + "string" + ], + "GitCredentialId": "string", + "GitHubConnectionId": "string", + "GitResourceSelectedLastRelease": { + "GitCommit": "string", + "GitRef": "string" + }, + "IsResolvable": true, + "Name": "string", + "RepositoryUri": "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" + } + ] +} +``` +::: + +## Get a paginated list of all of the Runbook Snapshots that belong to the given Project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbookSnapshots"} + +Also reachable at `/api/projects/{projectId}/runbookSnapshots`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookSnapshots`. + +Runbook Snapshots will be ordered from most recent to least recent. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project to get runbook snapshots for. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`searchByName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — A paginated list of all of the Runbook Snapshots that belong to the given Project. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Assembled`** :span[string]{.type-label} + Format `date-time`. + - **`FrozenProjectVariableSetId`** :span[string]{.type-label} + Minimum length 1. + - **`FrozenRunbookProcessId`** :span[string]{.type-label} + Minimum length 1. + - **`GitReference`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`Notes`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + Minimum length 1. + - **`RunbookId`** :span[string]{.type-label} + - **`SelectedGitResources`** :span[array of object]{.type-label} + - **`SelectedPackages`** :span[array of object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Assembled": "2020-01-01T00:00:00.000Z", + "FrozenProjectVariableSetId": "string", + "FrozenRunbookProcessId": "string", + "GitReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "RunbookId": "string", + "SelectedGitResources": [ + {} + ], + "SelectedPackages": [ + {} + ], + "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 +} +``` +::: + +## Create a Runbook Snapshot + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/runbookSnapshots"} + +Also reachable at `/api/projects/{projectId}/runbookSnapshots`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookSnapshots`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the project that owns the runbook to snapshot. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Name`** :span[string]{.type-label} *(required)* + The name of the runbook snapshot. Minimum length 1. +- **`Notes`** :span[string]{.type-label} + Any additional information about the runbook snapshot. +- **`ProjectId`** :span[string]{.type-label} *(required)* + ID of the project that owns the runbook to snapshot. +- **`Publish`** :span[string]{.type-label} + Publishes the snapshot when set to any non-blank value, making it the snapshot that runbook triggers and 'published' runs use. The value itself is not stored. Leave unset to create the snapshot without publishing it. +- **`RunbookId`** :span[string]{.type-label} *(required)* + ID of the runbook to snapshot. +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} *(required)* + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + The packages and versions used in the runbook snapshot. + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "Publish": "string", + "RunbookId": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`FrozenProjectVariableSetId`** :span[string]{.type-label} + Minimum length 1. +- **`FrozenRunbookProcessId`** :span[string]{.type-label} + Minimum length 1. +- **`GitReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Notes`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + Minimum length 1. +- **`RunbookId`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "FrozenProjectVariableSetId": "string", + "FrozenRunbookProcessId": "string", + "GitReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "RunbookId": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string" +} +``` +::: + +## Get a single Runbook Snapshot by project ID and name + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbookSnapshots/\{idOrName\}"} + +Also reachable at `/api/projects/{projectId}/runbookSnapshots/{idOrName}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookSnapshots/{idOrName}`. + +**Path Parameters** + +- **`idOrName`** :span[string]{.type-label} *(required)* + ID or Name of the RunbookSnapshot to load. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project to get Runbook Snapshot for. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`FrozenProjectVariableSetId`** :span[string]{.type-label} + Minimum length 1. +- **`FrozenRunbookProcessId`** :span[string]{.type-label} + Minimum length 1. +- **`GitReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Notes`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + Minimum length 1. +- **`RunbookId`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "FrozenProjectVariableSetId": "string", + "FrozenRunbookProcessId": "string", + "GitReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "RunbookId": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string" +} +``` +::: + +## Modify a Runbook Snapshot + +:endpoint{method="PUT" path="/api/\{spaceId\}/projects/\{projectId\}/runbookSnapshots/\{id\}"} + +Also reachable at `/api/projects/{projectId}/runbookSnapshots/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookSnapshots/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the runbook snapshot to modify. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the project that owns the runbook. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Id`** :span[string]{.type-label} *(required)* + ID of the runbook snapshot to modify. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the runbook snapshot. Minimum length 1. +- **`Notes`** :span[string]{.type-label} + Any additional information about the runbook snapshot. +- **`ProjectId`** :span[string]{.type-label} + Not used to locate the snapshot; the snapshot ID alone finds it. Safe to omit. +- **`SelectedGitResources`** :span[array of object]{.type-label} + The git resources and versions used in the runbook snapshot. + - **`ActionName`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} *(required)* + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + The packages and versions used in the runbook snapshot. + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Runbook Snapshot was modified, containing the updated snapshot + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`FrozenProjectVariableSetId`** :span[string]{.type-label} + Minimum length 1. +- **`FrozenRunbookProcessId`** :span[string]{.type-label} + Minimum length 1. +- **`GitReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Notes`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + Minimum length 1. +- **`RunbookId`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "FrozenProjectVariableSetId": "string", + "FrozenRunbookProcessId": "string", + "GitReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "RunbookId": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string" +} +``` +::: + +## Get the runbook runs for the given snapshot + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbookSnapshots/\{id\}/runbookRuns"} + +Also reachable at `/api/projects/{projectId}/runbookSnapshots/{id}/runbookRuns`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookSnapshots/{id}/runbookRuns`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Contains the Runbook Runs for the given Runbook Snapshot. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Comments`** :span[string]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`DebugMode`** :span[string]{.type-label} + - **`DeployedBy`** :span[string]{.type-label} + - **`DeployedById`** :span[string]{.type-label} + - **`DeployedToMachineIds`** :span[array of string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. + - **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`FailureEncountered`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`FormValues`** :span[object]{.type-label} + - **`FrozenRunbookProcessId`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ManifestVariableSetId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Priority`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. + - **`RunbookId`** :span[string]{.type-label} + Minimum length 1. + - **`RunbookName`** :span[string]{.type-label} + - **`RunbookSnapshotId`** :span[string]{.type-label} + Minimum length 1. + - **`SkipActions`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. + - **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`TaskId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + - **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "ChangeRequestSettings": [ + {} + ], + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + {} + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "FrozenRunbookProcessId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "RunbookId": "string", + "RunbookName": "string", + "RunbookSnapshotId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get a Runbook Run Preview for a Runbook Snapshot + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbookSnapshots/\{id\}/runbookRuns/preview/\{environmentId\}"} + +Also reachable at `/api/projects/{projectId}/runbookSnapshots/{id}/runbookRuns/preview/{environmentId}`, `/api/projects/{projectId}/runbookSnapshots/{id}/runbookRuns/preview/{environmentId}/{tenant}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookSnapshots/{id}/runbookRuns/preview/{environmentId}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookSnapshots/{id}/runbookRuns/preview/{environmentId}/{tenant}`, `/api/{spaceId}/projects/{projectId}/runbookSnapshots/{id}/runbookRuns/preview/{environmentId}/{tenant}`. + +Gets a document that describes what steps will/won't be run during a run to a given environment (and tenant if supplied) + +**Path Parameters** + +- **`environmentId`** :span[string]{.type-label} *(required)* + ID of the Environment. +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook Snapshot. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`includeDisabledSteps`** :span[boolean]{.type-label} + Boolean to include/exclude disabled steps from response. +- **`tenant`** :span[string]{.type-label} + ID of the Tenant. + +**Response** + +`200` — The requested Runbook Run preview + +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StepsToExecute`** :span[array of object]{.type-label} + - **`ActionId`** :span[string]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`ActionNumber`** :span[string]{.type-label} + - **`AvailableTagSets`** :span[array of object]{.type-label} + - **`CanBeSkipped`** :span[boolean]{.type-label} + - **`ExcludedMachines`** :span[array of object]{.type-label} + - **`HasNoApplicableMachines`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`MachineNames`** :span[array of string]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`UnavailableMachines`** :span[array of object]{.type-label} +- **`UseGuidedFailureModeByDefault`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 a Runbook Run Template for a Runbook Snapshot + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbookSnapshots/\{id\}/runbookRuns/template"} + +Also reachable at `/api/projects/{projectId}/runbookSnapshots/{id}/runbookRuns/template`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookSnapshots/{id}/runbookRuns/template`. + +Gets all of the information necessary for creating or editing a run for this snapshot. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook Snapshot to get a Runbook Run Template for. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project the Runbook Snapshot belongs to. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Runbook Run Template + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsGitResourceModified`** :span[boolean]{.type-label} +- **`IsLibraryVariableSetModified`** :span[boolean]{.type-label} +- **`IsRunbookProcessModified`** :span[boolean]{.type-label} +- **`IsVariableSetModified`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`PromoteTo`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`TenantPromotions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`PromoteTo`** :span[array of object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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": [ + {} + ] + } + ] +} +``` +::: + +## Update the variable snapshots for a Runbook Snapshot + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/runbookSnapshots/\{id\}/snapshot-variables"} + +Also reachable at `/api/projects/{projectId}/runbookSnapshots/{id}/snapshot-variables`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookSnapshots/{id}/snapshot-variables`. + +Update the variable snapshots associated with the runbook snapshot to the latest versions. The runbook's process must not have changed since the snapshot was created. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook Snapshot. +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project containing this resource. Will be inferred if not provided. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the Runbook Snapshot Variables were refreshed, containing the updated Snapshot + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`FrozenProjectVariableSetId`** :span[string]{.type-label} + Minimum length 1. +- **`FrozenRunbookProcessId`** :span[string]{.type-label} + Minimum length 1. +- **`GitReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Notes`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + Minimum length 1. +- **`RunbookId`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "FrozenProjectVariableSetId": "string", + "FrozenRunbookProcessId": "string", + "GitReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "RunbookId": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string" +} +``` +::: + +## Update the variable snapshots for a Runbook Snapshot + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/runbookSnapshots/\{id\}/snapshot-variables/v1"} + +Also reachable at `/api/projects/{projectId}/runbookSnapshots/{id}/snapshot-variables/v1`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookSnapshots/{id}/snapshot-variables/v1`. + +Update the variable snapshots associated with the runbook snapshot to the latest versions. The runbook's process must not have changed since the snapshot was created. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook Snapshot. +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project containing this resource. Will be inferred if not provided. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the Runbook Snapshot Variables were refreshed, containing the updated Snapshot + +- **`Resource`** :span[object]{.type-label} + - **`Assembled`** :span[string]{.type-label} + Format `date-time`. + - **`FrozenProjectVariableSetId`** :span[string]{.type-label} + Minimum length 1. + - **`FrozenRunbookProcessId`** :span[string]{.type-label} + Minimum length 1. + - **`GitReference`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`Notes`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + Minimum length 1. + - **`RunbookId`** :span[string]{.type-label} + - **`SelectedGitResources`** :span[array of object]{.type-label} + - **`SelectedPackages`** :span[array of object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Resource": { + "Assembled": "2020-01-01T00:00:00.000Z", + "FrozenProjectVariableSetId": "string", + "FrozenRunbookProcessId": "string", + "GitReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "RunbookId": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": {}, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string" + } +} +``` +::: + +## Get a list of Variable Sets included in the Runbook Snapshot's current Variable Snapshot + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbookSnapshots/\{id\}/variables"} + +Also reachable at `/api/projects/{projectId}/runbookSnapshots/{id}/variables`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookSnapshots/{id}/variables`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook Snapshot to get variables for. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project the Runbook Snapshot is in. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested list of Runbook Snapshot Variables + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`OwnerId`** :span[string]{.type-label} + Gets or sets the ID of the document that owns these variables. +- **`ScopeValues`** :span[object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Channels`** :span[array of object]{.type-label} + - **`EnvironmentParameters`** :span[array of object]{.type-label} + - **`Environments`** :span[array of object]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`ProcessTemplateSteps`** :span[array of object]{.type-label} + - **`Processes`** :span[array of object]{.type-label} + - **`Roles`** :span[array of object]{.type-label} + - **`TargetTagParameters`** :span[array of object]{.type-label} + - **`TenantTagParameters`** :span[array of object]{.type-label} + - **`TenantTags`** :span[array of object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + Gets the collection of variables. + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsEditable`** :span[boolean]{.type-label} + - **`IsSensitive`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Prompt`** :span[object]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Type`** :span[string]{.type-label} + - **`Value`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +[ + { + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "OwnerId": "string", + "ScopeValues": { + "Actions": [ + {} + ], + "Channels": [ + {} + ], + "EnvironmentParameters": [ + {} + ], + "Environments": [ + {} + ], + "Machines": [ + {} + ], + "ProcessTemplateSteps": [ + {} + ], + "Processes": [ + {} + ], + "Roles": [ + {} + ], + "TargetTagParameters": [ + {} + ], + "TenantTagParameters": [ + {} + ], + "TenantTags": [ + {} + ] + }, + "SpaceId": "string", + "Variables": [ + { + "Description": "string", + "Id": "string", + "IsEditable": true, + "IsSensitive": true, + "Name": "string", + "Prompt": {}, + "Scope": {}, + "Type": "string", + "Value": "string" + } + ], + "Version": 0 + } +] +``` +::: + +## Get a list of Runbook Run Previews for a Runbook Snapshot + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/runbookSnapshots/\{runbookSnapshotId\}/runbookRuns/previews"} + +Also reachable at `/api/projects/{projectId}/runbookSnapshots/{runbookSnapshotId}/runbookRuns/previews`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbookSnapshots/{runbookSnapshotId}/runbookRuns/previews`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`runbookSnapshotId`** :span[string]{.type-label} *(required)* + ID of the Runbook Snapshot. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`DeploymentPreviews`** :span[array of object]{.type-label} *(required)* + The environment/tenant combinations to preview, one entry per combination. Leave an entry's TenantId unset to preview an untenanted run in that environment. + - **`EnvironmentId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`IncludeDisabledSteps`** :span[boolean]{.type-label} + Boolean to include/exclude disabled steps from response. +- **`ProjectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`RunbookSnapshotId`** :span[string]{.type-label} *(required)* + ID of the Runbook Snapshot. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "DeploymentPreviews": [ + { + "EnvironmentId": "string", + "TenantId": "string" + } + ], + "IncludeDisabledSteps": true, + "ProjectId": "string", + "RunbookSnapshotId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — A preview for a Runbook run, representing the planned execution. + +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StepsToExecute`** :span[array of object]{.type-label} + - **`ActionId`** :span[string]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`ActionNumber`** :span[string]{.type-label} + - **`AvailableTagSets`** :span[array of object]{.type-label} + - **`CanBeSkipped`** :span[boolean]{.type-label} + - **`ExcludedMachines`** :span[array of object]{.type-label} + - **`HasNoApplicableMachines`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`MachineNames`** :span[array of string]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`UnavailableMachines`** :span[array of object]{.type-label} +- **`UseGuidedFailureModeByDefault`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "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 a paginated list of all of the Runbook Snapshots that belong to the given Runbook + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbooks/\{id\}/runbookSnapshots"} + +Also reachable at `/api/projects/{projectId}/runbooks/{id}/runbookSnapshots`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{id}/runbookSnapshots`. + +Runbook Snapshots will be ordered from most recent to least recent. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the runbook to get runbook Snapshots for. +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project the runbook belongs to. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`searchByName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — A paginated list of all of the Runbook Snapshots that belong to the given Runbook. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Assembled`** :span[string]{.type-label} + Format `date-time`. + - **`FrozenProjectVariableSetId`** :span[string]{.type-label} + Minimum length 1. + - **`FrozenRunbookProcessId`** :span[string]{.type-label} + Minimum length 1. + - **`GitReference`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`Notes`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + Minimum length 1. + - **`RunbookId`** :span[string]{.type-label} + - **`SelectedGitResources`** :span[array of object]{.type-label} + - **`SelectedPackages`** :span[array of object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Assembled": "2020-01-01T00:00:00.000Z", + "FrozenProjectVariableSetId": "string", + "FrozenRunbookProcessId": "string", + "GitReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "RunbookId": "string", + "SelectedGitResources": [ + {} + ], + "SelectedPackages": [ + {} + ], + "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 +} +``` +::: + +## Delete an existing Runbook Snapshot + +:endpoint{method="DELETE" path="/api/\{spaceId\}/projects/\{projectId\}/runbooksnapshots/\{id\}"} + +Also reachable at `/api/projects/{projectId}/runbooksnapshots/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbooksnapshots/{id}`. + +Also deletes all of the Runbook Runs, Tasks and other associated resources belonging to the Runbook Snapshot. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook Snapshot to delete. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project that the Runbook Snapshot belongs to. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Get a paginated list of Runbook Snapshots + +:endpoint{method="GET" path="/api/\{spaceId\}/runbookSnapshots"} + +Also reachable at `/api/runbookSnapshots`, `/api/spaces/{spaceIdentifier}/runbookSnapshots`. + +Gets a paginated list of the runbook snapshots in the supplied Octopus Deploy Space, from all projects. The results will be sorted from most recent to least recent snapshot. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — A paginated list of the runbook snapshots in the supplied Octopus Deploy Space, from all projects. The results will be sorted from most recent to least recent snapshot. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Assembled`** :span[string]{.type-label} + Format `date-time`. + - **`FrozenProjectVariableSetId`** :span[string]{.type-label} + Minimum length 1. + - **`FrozenRunbookProcessId`** :span[string]{.type-label} + Minimum length 1. + - **`GitReference`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`Notes`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + Minimum length 1. + - **`RunbookId`** :span[string]{.type-label} + - **`SelectedGitResources`** :span[array of object]{.type-label} + - **`SelectedPackages`** :span[array of object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Assembled": "2020-01-01T00:00:00.000Z", + "FrozenProjectVariableSetId": "string", + "FrozenRunbookProcessId": "string", + "GitReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "RunbookId": "string", + "SelectedGitResources": [ + {} + ], + "SelectedPackages": [ + {} + ], + "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 +} +``` +::: + +## Create a Runbook Snapshot + +:endpoint{method="POST" path="/api/\{spaceId\}/runbookSnapshots"} + +Also reachable at `/api/runbookSnapshots`, `/api/spaces/{spaceIdentifier}/runbookSnapshots`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Name`** :span[string]{.type-label} *(required)* + The name of the runbook snapshot. Minimum length 1. +- **`Notes`** :span[string]{.type-label} + Any additional information about the runbook snapshot. +- **`ProjectId`** :span[string]{.type-label} *(required)* + ID of the project that owns the runbook to snapshot. +- **`Publish`** :span[string]{.type-label} + Publishes the snapshot when set to any non-blank value, making it the snapshot that runbook triggers and 'published' runs use. The value itself is not stored. Leave unset to create the snapshot without publishing it. +- **`RunbookId`** :span[string]{.type-label} *(required)* + ID of the runbook to snapshot. +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} *(required)* + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + The packages and versions used in the runbook snapshot. + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "Publish": "string", + "RunbookId": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`FrozenProjectVariableSetId`** :span[string]{.type-label} + Minimum length 1. +- **`FrozenRunbookProcessId`** :span[string]{.type-label} + Minimum length 1. +- **`GitReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Notes`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + Minimum length 1. +- **`RunbookId`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "FrozenProjectVariableSetId": "string", + "FrozenRunbookProcessId": "string", + "GitReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "RunbookId": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string" +} +``` +::: + +## Get a Runbook Snapshot by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/runbookSnapshots/\{id\}"} + +Also reachable at `/api/runbookSnapshots/{id}`, `/api/spaces/{spaceIdentifier}/runbookSnapshots/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the RunbookSnapshot to retrieve. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested runbook snapshot + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`FrozenProjectVariableSetId`** :span[string]{.type-label} + Minimum length 1. +- **`FrozenRunbookProcessId`** :span[string]{.type-label} + Minimum length 1. +- **`GitReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Notes`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + Minimum length 1. +- **`RunbookId`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "FrozenProjectVariableSetId": "string", + "FrozenRunbookProcessId": "string", + "GitReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "RunbookId": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string" +} +``` +::: + +## Modify a Runbook Snapshot + +:endpoint{method="PUT" path="/api/\{spaceId\}/runbookSnapshots/\{id\}"} + +Also reachable at `/api/runbookSnapshots/{id}`, `/api/spaces/{spaceIdentifier}/runbookSnapshots/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the runbook snapshot to modify. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Id`** :span[string]{.type-label} *(required)* + ID of the runbook snapshot to modify. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the runbook snapshot. Minimum length 1. +- **`Notes`** :span[string]{.type-label} + Any additional information about the runbook snapshot. +- **`ProjectId`** :span[string]{.type-label} + Not used to locate the snapshot; the snapshot ID alone finds it. Safe to omit. +- **`SelectedGitResources`** :span[array of object]{.type-label} + The git resources and versions used in the runbook snapshot. + - **`ActionName`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} *(required)* + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + The packages and versions used in the runbook snapshot. + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Runbook Snapshot was modified, containing the updated snapshot + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`FrozenProjectVariableSetId`** :span[string]{.type-label} + Minimum length 1. +- **`FrozenRunbookProcessId`** :span[string]{.type-label} + Minimum length 1. +- **`GitReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Notes`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + Minimum length 1. +- **`RunbookId`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "FrozenProjectVariableSetId": "string", + "FrozenRunbookProcessId": "string", + "GitReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "RunbookId": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string" +} +``` +::: + +## Get the runbook runs for the given snapshot + +:endpoint{method="GET" path="/api/\{spaceId\}/runbookSnapshots/\{id\}/runbookRuns"} + +Also reachable at `/api/runbookSnapshots/{id}/runbookRuns`, `/api/spaces/{spaceIdentifier}/runbookSnapshots/{id}/runbookRuns`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Contains the Runbook Runs for the given Runbook Snapshot. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`ChangeRequestSettings`** :span[array of object]{.type-label} + - **`Comments`** :span[string]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`DebugMode`** :span[string]{.type-label} + - **`DeployedBy`** :span[string]{.type-label} + - **`DeployedById`** :span[string]{.type-label} + - **`DeployedToMachineIds`** :span[array of string]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`ExcludedMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the deployment. + - **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`ExecutionPlanLogContext`** :span[object]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`FailureEncountered`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`FormValues`** :span[object]{.type-label} + - **`FrozenRunbookProcessId`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ManifestVariableSetId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Priority`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`QueueTime`** :span[string]{.type-label} + If set this time will be the used to schedule the deployment to a later time, null is assumed to mean the time will be executed immediately. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. + - **`RunbookId`** :span[string]{.type-label} + Minimum length 1. + - **`RunbookName`** :span[string]{.type-label} + - **`RunbookSnapshotId`** :span[string]{.type-label} + Minimum length 1. + - **`SkipActions`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`SpecificMachineIds`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be deployed to. If the collection is empty, all enabled machines are deployed. + - **`SpecificTargetTagIds`** :span[array of string]{.type-label} + 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}". + - **`TaskId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} + - **`TentacleRetentionPeriod`** :span[object]{.type-label} + - **`UseGuidedFailure`** :span[boolean]{.type-label} + If set to true, the deployment 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. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "ChangeRequestSettings": [ + {} + ], + "Comments": "string", + "Created": "2020-01-01T00:00:00.000Z", + "DebugMode": "string", + "DeployedBy": "string", + "DeployedById": "string", + "DeployedToMachineIds": [ + "string" + ], + "EnvironmentId": "string", + "ExcludedMachineIds": [ + "string" + ], + "ExcludedTargetTagIds": [ + "string" + ], + "ExecutionPlanLogContext": { + "Steps": [ + {} + ] + }, + "FailTargetDiscovery": true, + "FailureEncountered": true, + "ForcePackageDownload": true, + "FormValues": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "FrozenRunbookProcessId": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ManifestVariableSetId": "string", + "Name": "string", + "Priority": "string", + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "RunbookId": "string", + "RunbookName": "string", + "RunbookSnapshotId": "string", + "SkipActions": [ + "string" + ], + "SpaceId": "string", + "SpecificMachineIds": [ + "string" + ], + "SpecificTargetTagIds": [ + "string" + ], + "TaskId": "string", + "TenantId": "string", + "TentacleRetentionPeriod": { + "QuantityToKeep": 0, + "ShouldKeepForever": true, + "Strategy": "string", + "Unit": "Days" + }, + "UseGuidedFailure": true + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get a Runbook Run Preview for a Runbook Snapshot + +:endpoint{method="GET" path="/api/\{spaceId\}/runbookSnapshots/\{id\}/runbookRuns/preview/\{environmentId\}"} + +Also reachable at `/api/runbookSnapshots/{id}/runbookRuns/preview/{environmentId}`, `/api/runbookSnapshots/{id}/runbookRuns/preview/{environmentId}/{tenant}`, `/api/spaces/{spaceIdentifier}/runbookSnapshots/{id}/runbookRuns/preview/{environmentId}`, `/api/spaces/{spaceIdentifier}/runbookSnapshots/{id}/runbookRuns/preview/{environmentId}/{tenant}`, `/api/{spaceId}/runbookSnapshots/{id}/runbookRuns/preview/{environmentId}/{tenant}`. + +Gets a document that describes what steps will/won't be run during a run to a given environment (and tenant if supplied) + +**Path Parameters** + +- **`environmentId`** :span[string]{.type-label} *(required)* + ID of the Environment. +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook Snapshot. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`includeDisabledSteps`** :span[boolean]{.type-label} + Boolean to include/exclude disabled steps from response. +- **`projectId`** :span[string]{.type-label} + ID of the Project. +- **`tenant`** :span[string]{.type-label} + ID of the Tenant. + +**Response** + +`200` — The requested Runbook Run preview + +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StepsToExecute`** :span[array of object]{.type-label} + - **`ActionId`** :span[string]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`ActionNumber`** :span[string]{.type-label} + - **`AvailableTagSets`** :span[array of object]{.type-label} + - **`CanBeSkipped`** :span[boolean]{.type-label} + - **`ExcludedMachines`** :span[array of object]{.type-label} + - **`HasNoApplicableMachines`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`MachineNames`** :span[array of string]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`UnavailableMachines`** :span[array of object]{.type-label} +- **`UseGuidedFailureModeByDefault`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 a Runbook Run Template for a Runbook Snapshot + +:endpoint{method="GET" path="/api/\{spaceId\}/runbookSnapshots/\{id\}/runbookRuns/template"} + +Also reachable at `/api/runbookSnapshots/{id}/runbookRuns/template`, `/api/spaces/{spaceIdentifier}/runbookSnapshots/{id}/runbookRuns/template`. + +Gets all of the information necessary for creating or editing a run for this snapshot. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook Snapshot to get a Runbook Run Template for. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`projectId`** :span[string]{.type-label} + ID of the Project the Runbook Snapshot belongs to. + +**Response** + +`200` — The requested Runbook Run Template + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsGitResourceModified`** :span[boolean]{.type-label} +- **`IsLibraryVariableSetModified`** :span[boolean]{.type-label} +- **`IsRunbookProcessModified`** :span[boolean]{.type-label} +- **`IsVariableSetModified`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`PromoteTo`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`TenantPromotions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`PromoteTo`** :span[array of object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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": [ + {} + ] + } + ] +} +``` +::: + +## Update the variable snapshots for a Runbook Snapshot + +:endpoint{method="POST" path="/api/\{spaceId\}/runbookSnapshots/\{id\}/snapshot-variables"} + +Also reachable at `/api/runbookSnapshots/{id}/snapshot-variables`, `/api/spaces/{spaceIdentifier}/runbookSnapshots/{id}/snapshot-variables`. + +Update the variable snapshots associated with the runbook snapshot to the latest versions. The runbook's process must not have changed since the snapshot was created. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook Snapshot. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the Runbook Snapshot Variables were refreshed, containing the updated Snapshot + +- **`Assembled`** :span[string]{.type-label} + Format `date-time`. +- **`FrozenProjectVariableSetId`** :span[string]{.type-label} + Minimum length 1. +- **`FrozenRunbookProcessId`** :span[string]{.type-label} + Minimum length 1. +- **`GitReference`** :span[object]{.type-label} + - **`GitCommit`** :span[string]{.type-label} + - **`GitRef`** :span[string]{.type-label} + - **`VariablesGitCommit`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Notes`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + Minimum length 1. +- **`RunbookId`** :span[string]{.type-label} +- **`SelectedGitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`GitReferenceResource`** :span[object]{.type-label} + - **`GitResourceReferenceName`** :span[string]{.type-label} +- **`SelectedPackages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`Version`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Assembled": "2020-01-01T00:00:00.000Z", + "FrozenProjectVariableSetId": "string", + "FrozenRunbookProcessId": "string", + "GitReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "RunbookId": "string", + "SelectedGitResources": [ + { + "ActionName": "string", + "GitReferenceResource": { + "GitCommit": "string", + "GitRef": "string" + }, + "GitResourceReferenceName": "string" + } + ], + "SelectedPackages": [ + { + "ActionName": "string", + "PackageReferenceName": "string", + "StepName": "string", + "Version": "string" + } + ], + "SpaceId": "string" +} +``` +::: + +## Get a paginated list of all of the Runbook Snapshots that belong to the given Runbook + +:endpoint{method="GET" path="/api/\{spaceId\}/runbooks/\{id\}/runbookSnapshots"} + +Also reachable at `/api/runbooks/{id}/runbookSnapshots`, `/api/spaces/{spaceIdentifier}/runbooks/{id}/runbookSnapshots`. + +Runbook Snapshots will be ordered from most recent to least recent. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the runbook to get runbook Snapshots for. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`projectId`** :span[string]{.type-label} + The ID of the project the runbook belongs to. +- **`searchByName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — A paginated list of all of the Runbook Snapshots that belong to the given Runbook. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Assembled`** :span[string]{.type-label} + Format `date-time`. + - **`FrozenProjectVariableSetId`** :span[string]{.type-label} + Minimum length 1. + - **`FrozenRunbookProcessId`** :span[string]{.type-label} + Minimum length 1. + - **`GitReference`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LibraryVariableSetSnapshotIds`** :span[array of string]{.type-label} + Snapshots of the project's included library variable sets. The snapshots are VariableSetResources, not LibraryVariableSetResources. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`Notes`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectVariableSetSnapshotId`** :span[string]{.type-label} + Minimum length 1. + - **`RunbookId`** :span[string]{.type-label} + - **`SelectedGitResources`** :span[array of object]{.type-label} + - **`SelectedPackages`** :span[array of object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Assembled": "2020-01-01T00:00:00.000Z", + "FrozenProjectVariableSetId": "string", + "FrozenRunbookProcessId": "string", + "GitReference": { + "GitCommit": "string", + "GitRef": "string", + "VariablesGitCommit": "string" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariableSetSnapshotIds": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Notes": "string", + "ProjectId": "string", + "ProjectVariableSetSnapshotId": "string", + "RunbookId": "string", + "SelectedGitResources": [ + {} + ], + "SelectedPackages": [ + {} + ], + "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 +} +``` +::: + +## Delete an existing Runbook Snapshot + +:endpoint{method="DELETE" path="/api/\{spaceId\}/runbooksnapshots/\{id\}"} + +Also reachable at `/api/runbooksnapshots/{id}`, `/api/spaces/{spaceIdentifier}/runbooksnapshots/{id}`. + +Also deletes all of the Runbook Runs, Tasks and other associated resources belonging to the Runbook Snapshot. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook Snapshot to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success diff --git a/src/pages/docs/api/runbooks.md b/src/pages/docs/api/runbooks.md new file mode 100644 index 0000000000..666dddbb2c --- /dev/null +++ b/src/pages/docs/api/runbooks.md @@ -0,0 +1,4488 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Runbooks +--- + +## Retrieve a list of Runbooks that will be converted to Git, along with how many RunbookRun History records will be updated + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/git/migrate-runbooks"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/migrate-runbooks`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Returns as summary of the runbooks that will be converted to Git + +- **`DraftRunbooks`** :span[array of object]{.type-label} + - **`RunbookId`** :span[string]{.type-label} + - **`RunbookName`** :span[string]{.type-label} +- **`PublishedRunbooks`** :span[array of object]{.type-label} + - **`RunbookId`** :span[string]{.type-label} + - **`RunbookName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "DraftRunbooks": [ + { + "RunbookId": "string", + "RunbookName": "string" + } + ], + "PublishedRunbooks": [ + { + "RunbookId": "string", + "RunbookName": "string" + } + ] +} +``` +::: + +## Get a paginated list of the Runbooks that belong to the given Project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbooks"} + +Also reachable at `/api/projects/{projectId}/runbooks`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`excludedRunbookTags`** :span[array of string]{.type-label} + A list of tag IDs to exclude runbooks by. Returns runbooks that have none of the specified tags. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`runbookTags`** :span[array of string]{.type-label} + A list of tag IDs to filter runbooks by. Returns runbooks that have any of the specified tags. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Success + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`CancelQueuedTasks`** :span[boolean]{.type-label} + - **`CancelRunningTasks`** :span[boolean]{.type-label} + - **`ConnectivityPolicy`** :span[object]{.type-label} + - **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. + - **`Description`** :span[string]{.type-label} + - **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. + - **`Environments`** :span[array of string]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + - **`Name`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`PublishedRunbookSnapshotId`** :span[string]{.type-label} + - **`RunRetentionPolicy`** :span[object]{.type-label} + - **`RunbookProcessId`** :span[string]{.type-label} + - **`RunbookTags`** :span[array of string]{.type-label} + List of tags assigned to this runbook. + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 +} +``` +::: + +## Create a new Runbook or clone an existing Runbook + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/runbooks"} + +Also reachable at `/api/projects/{projectId}/runbooks`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + The Project that contains the Runbook. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Clone`** :span[string]{.type-label} + 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`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + 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`** :span[string]{.type-label} + The description of the Runbook to create. +- **`EnvironmentScope`** :span[enum]{.type-label} + 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`** :span[array of string]{.type-label} + The environments the runbook may be run in. Only applies when EnvironmentScope is 'Specified'; ignored otherwise. +- **`ForcePackageDownload`** :span[boolean]{.type-label} + Re-download every package on each run instead of reusing the copy already cached on the deployment target. +- **`MultiTenancyMode`** :span[enum]{.type-label} + 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`** :span[string]{.type-label} *(required)* + The name of the Runbook to create. Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} *(required)* + The ID of the project to create the runbook in. Must be a project that stores its runbooks in the Octopus database. +- **`PublishedRunbookSnapshotId`** :span[string]{.type-label} + Leave unset. A snapshot can only be published after the runbook exists and has a process. +- **`RunRetentionPolicy`** :span[object]{.type-label} *(required)* + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookProcessId`** :span[string]{.type-label} + Leave unset. Octopus creates an empty runbook process for the new runbook and links it automatically. +- **`RunbookTags`** :span[array of string]{.type-label} + 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`** :span[string]{.type-label} + A short URL-friendly identifier for the runbook, unique within the project. Generated from the name when omitted. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "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" +} +``` +::: + +**Response** + +`201` — Created + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} +- **`CancelRunningTasks`** :span[boolean]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. +- **`Environments`** :span[array of string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`PublishedRunbookSnapshotId`** :span[string]{.type-label} +- **`RunRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookProcessId`** :span[string]{.type-label} +- **`RunbookTags`** :span[array of string]{.type-label} + List of tags assigned to this runbook. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 a list of Runbooks for a Project + +:endpoint{method="GET" path="/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`** :span[string]{.type-label} *(required)* + The ID of the project containing the resource(s). +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + A list of Runbook resource ids used to filter a query. + +**Response** + +`200` — Requested list of Runbooks + +- **`Runbooks`** :span[array of object]{.type-label} + - **`CancelQueuedTasks`** :span[boolean]{.type-label} + - **`CancelRunningTasks`** :span[boolean]{.type-label} + - **`ConnectivityPolicy`** :span[object]{.type-label} + - **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. + - **`Description`** :span[string]{.type-label} + - **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. + - **`Environments`** :span[array of string]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + - **`Name`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`PublishedRunbookSnapshotId`** :span[string]{.type-label} + - **`RunRetentionPolicy`** :span[object]{.type-label} + - **`RunbookProcessId`** :span[string]{.type-label} + - **`RunbookTags`** :span[array of string]{.type-label} + List of tags assigned to this runbook. + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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" + } + ] +} +``` +::: + +## Create a new Database Runbook + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/runbooks/v2"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/v2`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. +- **`Environments`** :span[array of string]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`RunRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookTags`** :span[array of string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "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" +} +``` +::: + +**Response** + +`201` — Created + +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "Name": "string", + "ProjectId": "string", + "Slug": "string" +} +``` +::: + +## Get a Runbook by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbooks/\{id\}"} + +Also reachable at `/api/projects/{projectId}/runbooks/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook to retrieve. +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Returns a runbook + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} +- **`CancelRunningTasks`** :span[boolean]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. +- **`Environments`** :span[array of string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`PublishedRunbookSnapshotId`** :span[string]{.type-label} +- **`RunRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookProcessId`** :span[string]{.type-label} +- **`RunbookTags`** :span[array of string]{.type-label} + List of tags assigned to this runbook. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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" +} +``` +::: + +## Update an existing Runbook + +:endpoint{method="PUT" path="/api/\{spaceId\}/projects/\{projectId\}/runbooks/\{id\}"} + +Also reachable at `/api/projects/{projectId}/runbooks/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the runbook to update, for example 'Runbooks-123'. +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project the runbook belongs to. Must be a project that stores its runbooks in the Octopus database. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} + 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`** :span[boolean]{.type-label} + 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`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + 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`** :span[string]{.type-label} +- **`EnvironmentScope`** :span[enum]{.type-label} + 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`** :span[array of string]{.type-label} + 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`** :span[boolean]{.type-label} + 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`** :span[boolean]{.type-label} + Re-download every package on each run instead of reusing the copy already cached on the deployment target. Resets to false when omitted. +- **`Id`** :span[string]{.type-label} *(required)* + The ID of the runbook to update, for example 'Runbooks-123'. +- **`MultiTenancyMode`** :span[enum]{.type-label} + 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`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} *(required)* + The ID of the project the runbook belongs to. Must be a project that stores its runbooks in the Octopus database. +- **`PublishedRunbookSnapshotId`** :span[string]{.type-label} + 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`** :span[object]{.type-label} *(required)* + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookProcessId`** :span[string]{.type-label} + Leave this as the value returned by get_runbook. Octopus manages the link between a runbook and its process. +- **`RunbookTags`** :span[array of string]{.type-label} + 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`** :span[string]{.type-label} + A short URL-friendly identifier for the runbook, unique within the project. The current slug is kept when omitted. +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "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" +} +``` +::: + +**Response** + +`200` — Confirmation that the Runbook has been modified, containing the updated Runbook + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} +- **`CancelRunningTasks`** :span[boolean]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. +- **`Environments`** :span[array of string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`PublishedRunbookSnapshotId`** :span[string]{.type-label} +- **`RunRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookProcessId`** :span[string]{.type-label} +- **`RunbookTags`** :span[array of string]{.type-label} + List of tags assigned to this runbook. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 an existing Runbook + +:endpoint{method="DELETE" path="/api/\{spaceId\}/projects/\{projectId\}/runbooks/\{id\}"} + +Also reachable at `/api/projects/{projectId}/runbooks/{id}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook to delete. +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +## Get a list of environments a Runbook can be run within, based on its EnvironmentScope + +:endpoint{method="GET" path="/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`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project containing this resource. Will be inferred if not provided. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested list of Runbook Environments + +- **`AllowDynamicInfrastructure`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + List of tags assigned to this environment. +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this environment. This should be short, preferably 5-20 characters. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} + 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`** :span[string]{.type-label} +- **`UseGuidedFailure`** :span[boolean]{.type-label} + 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. + +:::api-example{label="Response"} +```json +[ + { + "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 a list of environments a Runbook can be run within, based on its EnvironmentScope + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/runbooks/\{id\}/environments/v2"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/runbooks/{id}/environments/v2`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project containing this resource. Will be inferred if not provided. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested list of Runbook Environments + +- **`Environments`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + List of tags assigned to this environment. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this environment. This should be short, preferably 5-20 characters. Minimum length 1. + - **`Slug`** :span[string]{.type-label} + Minimum length 1. + - **`SpaceId`** :span[string]{.type-label} + - **`Type`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Environments": [ + { + "Description": "string", + "EnvironmentTags": [ + "string" + ], + "Id": "string", + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "Type": "string" + } + ] +} +``` +::: + +## Get all of the information necessary for creating or editing a Runbook Run for this Runbook (when you do not have a snapshot) + +:endpoint{method="GET" path="/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`** :span[string]{.type-label} *(required)* + ID of the Runbook to get a Runbook Run Template for. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the project the runbook belongs to. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Runbook Template + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsGitResourceModified`** :span[boolean]{.type-label} +- **`IsLibraryVariableSetModified`** :span[boolean]{.type-label} +- **`IsRunbookProcessModified`** :span[boolean]{.type-label} +- **`IsVariableSetModified`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`PromoteTo`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`TenantPromotions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`PromoteTo`** :span[array of object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 a Runbook Run Preview for a Runbook + +:endpoint{method="GET" path="/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`** :span[string]{.type-label} *(required)* + ID of the Environment. +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`includeDisabledSteps`** :span[boolean]{.type-label} + Boolean to include/exclude disabled steps from response. +- **`tenant`** :span[string]{.type-label} + ID of the Tenant. + +**Response** + +`200` — Success + +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StepsToExecute`** :span[array of object]{.type-label} + - **`ActionId`** :span[string]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`ActionNumber`** :span[string]{.type-label} + - **`AvailableTagSets`** :span[array of object]{.type-label} + - **`CanBeSkipped`** :span[boolean]{.type-label} + - **`ExcludedMachines`** :span[array of object]{.type-label} + - **`HasNoApplicableMachines`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`MachineNames`** :span[array of string]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`UnavailableMachines`** :span[array of object]{.type-label} +- **`UseGuidedFailureModeByDefault`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 a Runbook Run Preview for a Runbook + +:endpoint{method="GET" path="/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`** :span[string]{.type-label} *(required)* + ID of the Environment. +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`tenant`** :span[string]{.type-label} *(required)* + ID of the Tenant. + +**Query Parameters** + +- **`includeDisabledSteps`** :span[boolean]{.type-label} + Boolean to include/exclude disabled steps from response. + +**Response** + +`200` — Success + +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StepsToExecute`** :span[array of object]{.type-label} + - **`ActionId`** :span[string]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`ActionNumber`** :span[string]{.type-label} + - **`AvailableTagSets`** :span[array of object]{.type-label} + - **`CanBeSkipped`** :span[boolean]{.type-label} + - **`ExcludedMachines`** :span[array of object]{.type-label} + - **`HasNoApplicableMachines`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`MachineNames`** :span[array of string]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`UnavailableMachines`** :span[array of object]{.type-label} +- **`UseGuidedFailureModeByDefault`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 +} +``` +::: + +## Run the published version of this Runbook + +:endpoint{method="POST" path="/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`** :span[string]{.type-label} *(required)* + ID of the project that the runbook belongs to. +- **`runbookId`** :span[string]{.type-label} *(required)* + ID of the runbook to run. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`ChangeRequestSettings`** :span[array of object]{.type-label} + Change Request Settings. + - **`Type`** :span[enum]{.type-label} + Allowed values: `ServiceNow`, `JiraServiceManagement`. +- **`Comments`** :span[string]{.type-label} + Any additional information/context. +- **`DebugMode`** :span[string]{.type-label} + If set to true contributes the OctopusPrintVariables and OctopusPrintEvaluatedVariables variables to the runbook run. +- **`EnvironmentId`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + 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`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the runbook run. +- **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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`** :span[boolean]{.type-label} + Whether to skip or fail cloud discovery steps with no matching target (default false). +- **`ForcePackageDownload`** :span[boolean]{.type-label} + Whether to force downloading of already installed packages (flag, default false). +- **`FormValues`** :span[object]{.type-label} + Variables. +- **`Priority`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} + ID of the project that the runbook belongs to. +- **`QueueTime`** :span[string]{.type-label} + The time to execute the runbook run. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + The time at which the runbook run will timeout if it has not started executing. Format `date-time`. +- **`RunbookId`** :span[string]{.type-label} *(required)* + ID of the runbook to run. +- **`RunbookSnapshotNameOrId`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + Actions that are to be skipped for this runbook. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`SpecificMachineIds`** :span[array of string]{.type-label} + 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`** :span[array of string]{.type-label} + 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`** :span[string]{.type-label} + Legacy single-tenant field; prefer TenantIds. If set, this tenant is added to the ones the runbook runs for. +- **`TenantIds`** :span[array of string]{.type-label} + 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`** :span[array of string]{.type-label} + The tenant tags to filter tenants to run the runbook. +- **`UseDefaultSnapshot`** :span[boolean]{.type-label} + 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`** :span[boolean]{.type-label} + 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. + +:::api-example{label="Request"} +```json +{ + "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 +} +``` +::: + +**Response** + +`200` — OK + +## Get a list of Runbook Run Previews for a Runbook + +:endpoint{method="POST" path="/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`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`runbookId`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`DeploymentPreviews`** :span[array of object]{.type-label} *(required)* + A list of Tenant/Environment mappings to retrieve runbook run previews for. + - **`EnvironmentId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`IncludeDisabledSteps`** :span[boolean]{.type-label} + Boolean to include/exclude disabled steps from response. +- **`ProjectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`RunbookId`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "DeploymentPreviews": [ + { + "EnvironmentId": "string", + "TenantId": "string" + } + ], + "IncludeDisabledSteps": true, + "ProjectId": "string", + "RunbookId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — The requested list of Runbook Run previews + +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StepsToExecute`** :span[array of object]{.type-label} + - **`ActionId`** :span[string]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`ActionNumber`** :span[string]{.type-label} + - **`AvailableTagSets`** :span[array of object]{.type-label} + - **`CanBeSkipped`** :span[boolean]{.type-label} + - **`ExcludedMachines`** :span[array of object]{.type-label} + - **`HasNoApplicableMachines`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`MachineNames`** :span[array of string]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`UnavailableMachines`** :span[array of object]{.type-label} +- **`UseGuidedFailureModeByDefault`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "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 all of the information necessary for creating or editing a Snapshot for a Runbook + +:endpoint{method="GET" path="/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`** :span[string]{.type-label} *(required)* + Project Id of the project containing the runbook. +- **`runbookId`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Confirmation that a new Runbook Snapshot Template has been created, containing the template + +- **`GitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`GitResourceSelectedLastRelease`** :span[object]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NextNameIncrement`** :span[string]{.type-label} +- **`Packages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`FeedId`** :span[string]{.type-label} + - **`FeedName`** :span[string]{.type-label} + - **`FixedVersion`** :span[string]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + - **`NuGetFeedName`** :span[string]{.type-label} + - **`NuGetPackageId`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`VersionSelectedLastRelease`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`RunbookProcessId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 a paginated list of the Runbooks that belong to the given Project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/runbooks"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/runbooks`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/runbooks`. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* + The GitRef containing the resource(s). +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`excludedRunbookTags`** :span[array of string]{.type-label} + A list of tag IDs to exclude runbooks by. Returns runbooks that have none of the specified tags. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`runbookTags`** :span[array of string]{.type-label} + A list of tag IDs to filter runbooks by. Returns runbooks that have any of the specified tags. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Success + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`CancelQueuedTasks`** :span[boolean]{.type-label} + - **`CancelRunningTasks`** :span[boolean]{.type-label} + - **`ConnectivityPolicy`** :span[object]{.type-label} + - **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. + - **`Description`** :span[string]{.type-label} + - **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. + - **`Environments`** :span[array of string]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + - **`Name`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`PublishedRunbookSnapshotId`** :span[string]{.type-label} + - **`RunRetentionPolicy`** :span[object]{.type-label} + - **`RunbookProcessId`** :span[string]{.type-label} + - **`RunbookTags`** :span[array of string]{.type-label} + List of tags assigned to this runbook. + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 +} +``` +::: + +## Create a new Git runbook + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/runbooks/v2"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/runbooks/v2`. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ChangeDescription`** :span[string]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. +- **`Environments`** :span[array of string]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`RunRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookTags`** :span[array of string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "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" +} +``` +::: + +**Response** + +`201` — Created + +- **`GitRef`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "GitRef": "string", + "Id": "string", + "Name": "string", + "ProjectId": "string", + "Slug": "string" +} +``` +::: + +## Get a Runbook by ID + +:endpoint{method="GET" path="/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`** :span[string]{.type-label} *(required)* +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook to retrieve. +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Returns a runbook + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} +- **`CancelRunningTasks`** :span[boolean]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. +- **`Environments`** :span[array of string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`PublishedRunbookSnapshotId`** :span[string]{.type-label} +- **`RunRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookProcessId`** :span[string]{.type-label} +- **`RunbookTags`** :span[array of string]{.type-label} + List of tags assigned to this runbook. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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" +} +``` +::: + +## Update an existing Runbook + +:endpoint{method="PUT" path="/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`** :span[string]{.type-label} *(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`** :span[string]{.type-label} *(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`** :span[string]{.type-label} *(required)* + The ID of the project the runbook belongs to. Must be a version-controlled project that stores its runbooks in Git. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} + 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`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + The commit message for the change. Defaults to 'Update runbook' when omitted. +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + 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`** :span[string]{.type-label} +- **`EnvironmentScope`** :span[enum]{.type-label} + 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`** :span[array of string]{.type-label} + 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`** :span[boolean]{.type-label} + 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`** :span[boolean]{.type-label} + Re-download every package on each run instead of reusing the copy already cached on the deployment target. Resets to false when omitted. +- **`GitRef`** :span[string]{.type-label} *(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`** :span[string]{.type-label} *(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`** :span[enum]{.type-label} + 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`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} *(required)* + The ID of the project the runbook belongs to. Must be a version-controlled project that stores its runbooks in Git. +- **`PublishedRunbookSnapshotId`** :span[string]{.type-label} + The ID of the runbook snapshot to publish. Resubmit the current value to leave the published snapshot alone. +- **`RunRetentionPolicy`** :span[object]{.type-label} *(required)* + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookProcessId`** :span[string]{.type-label} + Leave this as the value returned by get_runbook. Octopus manages the link between a runbook and its process. +- **`RunbookTags`** :span[array of string]{.type-label} + 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`** :span[string]{.type-label} + A short URL-friendly identifier for the runbook, unique within the project. The current slug is kept when omitted. +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "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" +} +``` +::: + +**Response** + +`200` — Confirmation that the Runbook has been modified, containing the updated Runbook + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} +- **`CancelRunningTasks`** :span[boolean]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. +- **`Environments`** :span[array of string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`PublishedRunbookSnapshotId`** :span[string]{.type-label} +- **`RunRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookProcessId`** :span[string]{.type-label} +- **`RunbookTags`** :span[array of string]{.type-label} + List of tags assigned to this runbook. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 an existing Runbook + +:endpoint{method="DELETE" path="/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`** :span[string]{.type-label} *(required)* + The GitRef containing the resource(s). +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook to delete. +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`ChangeDescription`** :span[string]{.type-label} + The commit message for updating the Git repository. +- **`GitRef`** :span[string]{.type-label} *(required)* + The GitRef containing the resource(s). +- **`Id`** :span[string]{.type-label} *(required)* + ID of the Runbook to delete. +- **`ProjectId`** :span[string]{.type-label} *(required)* + The ID of the project. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "ChangeDescription": "string", + "GitRef": "string", + "Id": "string", + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Success + +## Get a list of environments a Runbook can be run within, based on its EnvironmentScope + +:endpoint{method="GET" path="/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`** :span[string]{.type-label} *(required)* + The Git ref to read the runbook from. +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project containing this resource. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested list of Runbook Environments + +- **`AllowDynamicInfrastructure`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + List of tags assigned to this environment. +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this environment. This should be short, preferably 5-20 characters. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} + 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`** :span[string]{.type-label} +- **`UseGuidedFailure`** :span[boolean]{.type-label} + 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. + +:::api-example{label="Response"} +```json +[ + { + "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 a list of environments a Runbook can be run within, based on its EnvironmentScope + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/runbooks/\{id\}/environments/v2"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/runbooks/{id}/environments/v2`. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`id`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* + The ID of the project containing this resource. Will be inferred if not provided. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested list of Runbook Environments + +- **`Environments`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + List of tags assigned to this environment. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this environment. This should be short, preferably 5-20 characters. Minimum length 1. + - **`Slug`** :span[string]{.type-label} + Minimum length 1. + - **`SpaceId`** :span[string]{.type-label} + - **`Type`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Environments": [ + { + "Description": "string", + "EnvironmentTags": [ + "string" + ], + "Id": "string", + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "Type": "string" + } + ] +} +``` +::: + +## Get all of the information necessary for creating or editing a Runbook Run for this Runbook (when you do not have a snapshot) + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/runbooks/\{id\}/runbookRunTemplate"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/runbooks/{id}/runbookRunTemplate`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/runbooks/{id}/runbookRunTemplate`. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* + Gitref to get the runbook template from. +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook to get a Runbook Run Template for. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the project the runbook belongs to. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Runbook Template + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsGitResourceModified`** :span[boolean]{.type-label} +- **`IsLibraryVariableSetModified`** :span[boolean]{.type-label} +- **`IsRunbookProcessModified`** :span[boolean]{.type-label} +- **`IsVariableSetModified`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`PromoteTo`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`TenantPromotions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`PromoteTo`** :span[array of object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 a Runbook Run Preview for a Runbook + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/runbooks/\{id\}/runbookRuns/preview/\{environment\}"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/runbooks/{id}/runbookRuns/preview/{environment}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/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`** :span[string]{.type-label} *(required)* + ID of the Environment. +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`includeDisabledSteps`** :span[boolean]{.type-label} + Boolean to include/exclude disabled steps from response. +- **`tenant`** :span[string]{.type-label} + ID of the Tenant. + +**Response** + +`200` — Success + +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StepsToExecute`** :span[array of object]{.type-label} + - **`ActionId`** :span[string]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`ActionNumber`** :span[string]{.type-label} + - **`AvailableTagSets`** :span[array of object]{.type-label} + - **`CanBeSkipped`** :span[boolean]{.type-label} + - **`ExcludedMachines`** :span[array of object]{.type-label} + - **`HasNoApplicableMachines`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`MachineNames`** :span[array of string]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`UnavailableMachines`** :span[array of object]{.type-label} +- **`UseGuidedFailureModeByDefault`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 a Runbook Run Preview for a Runbook + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/runbooks/\{id\}/runbookRuns/preview/\{environment\}/\{tenant\}"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/runbooks/{id}/runbookRuns/preview/{environment}/{tenant}`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/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`** :span[string]{.type-label} *(required)* + ID of the Environment. +- **`gitRef`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`tenant`** :span[string]{.type-label} *(required)* + ID of the Tenant. + +**Query Parameters** + +- **`includeDisabledSteps`** :span[boolean]{.type-label} + Boolean to include/exclude disabled steps from response. + +**Response** + +`200` — Success + +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StepsToExecute`** :span[array of object]{.type-label} + - **`ActionId`** :span[string]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`ActionNumber`** :span[string]{.type-label} + - **`AvailableTagSets`** :span[array of object]{.type-label} + - **`CanBeSkipped`** :span[boolean]{.type-label} + - **`ExcludedMachines`** :span[array of object]{.type-label} + - **`HasNoApplicableMachines`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`MachineNames`** :span[array of string]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`UnavailableMachines`** :span[array of object]{.type-label} +- **`UseGuidedFailureModeByDefault`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 a list of Runbook Run Previews for a Runbook + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/runbooks/\{runbookId\}/runbookRuns/previews"} + +Also reachable at `/api/projects/{projectId}/{gitRef}/runbooks/{runbookId}/runbookRuns/previews`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/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** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`runbookId`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`DeploymentPreviews`** :span[array of object]{.type-label} *(required)* + A list of Tenant/Environment mappings to retrieve runbook run previews for. + - **`EnvironmentId`** :span[string]{.type-label} + - **`TenantId`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`IncludeDisabledSteps`** :span[boolean]{.type-label} + Boolean to include/exclude disabled steps from response. +- **`ProjectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`RunbookId`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "DeploymentPreviews": [ + { + "EnvironmentId": "string", + "TenantId": "string" + } + ], + "GitRef": "string", + "IncludeDisabledSteps": true, + "ProjectId": "string", + "RunbookId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — The requested list of Runbook Run previews + +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StepsToExecute`** :span[array of object]{.type-label} + - **`ActionId`** :span[string]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`ActionNumber`** :span[string]{.type-label} + - **`AvailableTagSets`** :span[array of object]{.type-label} + - **`CanBeSkipped`** :span[boolean]{.type-label} + - **`ExcludedMachines`** :span[array of object]{.type-label} + - **`HasNoApplicableMachines`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`MachineNames`** :span[array of string]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`UnavailableMachines`** :span[array of object]{.type-label} +- **`UseGuidedFailureModeByDefault`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "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 all of the information necessary for creating or editing a Snapshot for a Runbook + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitref\}/runbooks/\{runbookId\}/runbookSnapshotTemplate"} + +Also reachable at `/api/projects/{projectId}/{gitref}/runbooks/{runbookId}/runbookSnapshotTemplate`, `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitref}/runbooks/{runbookId}/runbookSnapshotTemplate`. + +**Path Parameters** + +- **`gitref`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* + Project Id of the project containing the runbook. +- **`runbookId`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Confirmation that a new Runbook Snapshot Template has been created, containing the template + +- **`GitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`GitResourceSelectedLastRelease`** :span[object]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NextNameIncrement`** :span[string]{.type-label} +- **`Packages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`FeedId`** :span[string]{.type-label} + - **`FeedName`** :span[string]{.type-label} + - **`FixedVersion`** :span[string]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + - **`NuGetFeedName`** :span[string]{.type-label} + - **`NuGetPackageId`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`VersionSelectedLastRelease`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`RunbookProcessId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 a list of Runbooks + +:endpoint{method="GET" path="/api/\{spaceId\}/runbooks"} + +Also reachable at `/api/runbooks`, `/api/spaces/{spaceIdentifier}/runbooks`. + +Gets a paginated list of the Runbooks in the supplied Octopus Deploy Space (sorted by name). + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + List of Runbook IDs which if specified, filters the result to only include Runbooks with matching IDs. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — A paginated list of the Runbooks in the supplied Octopus Deploy Space (sorted by name). + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`CancelQueuedTasks`** :span[boolean]{.type-label} + - **`CancelRunningTasks`** :span[boolean]{.type-label} + - **`ConnectivityPolicy`** :span[object]{.type-label} + - **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. + - **`Description`** :span[string]{.type-label} + - **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. + - **`Environments`** :span[array of string]{.type-label} + - **`FailTargetDiscovery`** :span[boolean]{.type-label} + - **`ForcePackageDownload`** :span[boolean]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. + - **`Name`** :span[string]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`PublishedRunbookSnapshotId`** :span[string]{.type-label} + - **`RunRetentionPolicy`** :span[object]{.type-label} + - **`RunbookProcessId`** :span[string]{.type-label} + - **`RunbookTags`** :span[array of string]{.type-label} + List of tags assigned to this runbook. + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 +} +``` +::: + +## Create a new Runbook or clone an existing Runbook + +:endpoint{method="POST" path="/api/\{spaceId\}/runbooks"} + +Also reachable at `/api/runbooks`, `/api/spaces/{spaceIdentifier}/runbooks`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Clone`** :span[string]{.type-label} + 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`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + 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`** :span[string]{.type-label} + The description of the Runbook to create. +- **`EnvironmentScope`** :span[enum]{.type-label} + 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`** :span[array of string]{.type-label} + The environments the runbook may be run in. Only applies when EnvironmentScope is 'Specified'; ignored otherwise. +- **`ForcePackageDownload`** :span[boolean]{.type-label} + Re-download every package on each run instead of reusing the copy already cached on the deployment target. +- **`MultiTenancyMode`** :span[enum]{.type-label} + 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`** :span[string]{.type-label} *(required)* + The name of the Runbook to create. Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} *(required)* + The ID of the project to create the runbook in. Must be a project that stores its runbooks in the Octopus database. +- **`PublishedRunbookSnapshotId`** :span[string]{.type-label} + Leave unset. A snapshot can only be published after the runbook exists and has a process. +- **`RunRetentionPolicy`** :span[object]{.type-label} *(required)* + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookProcessId`** :span[string]{.type-label} + Leave unset. Octopus creates an empty runbook process for the new runbook and links it automatically. +- **`RunbookTags`** :span[array of string]{.type-label} + 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`** :span[string]{.type-label} + A short URL-friendly identifier for the runbook, unique within the project. Generated from the name when omitted. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "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" +} +``` +::: + +**Response** + +`201` — Created + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} +- **`CancelRunningTasks`** :span[boolean]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. +- **`Environments`** :span[array of string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`PublishedRunbookSnapshotId`** :span[string]{.type-label} +- **`RunRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookProcessId`** :span[string]{.type-label} +- **`RunbookTags`** :span[array of string]{.type-label} + List of tags assigned to this runbook. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 a list of Runbooks + +:endpoint{method="GET" path="/api/\{spaceId\}/runbooks/all"} + +Also reachable at `/api/runbooks/all`, `/api/spaces/{spaceIdentifier}/runbooks/all`. + +Lists all of the Runbooks in the supplied Space. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + A list of Runbook resource ids used to filter a query. +- **`projectIds`** :span[array of string]{.type-label} + A list of Project ids used to filter a query. + +**Response** + +`200` — Requested list of Runbooks + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} +- **`CancelRunningTasks`** :span[boolean]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. +- **`Environments`** :span[array of string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`PublishedRunbookSnapshotId`** :span[string]{.type-label} +- **`RunRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookProcessId`** :span[string]{.type-label} +- **`RunbookTags`** :span[array of string]{.type-label} + List of tags assigned to this runbook. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "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 a Runbook by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/runbooks/\{id\}"} + +Also reachable at `/api/runbooks/{id}`, `/api/spaces/{spaceIdentifier}/runbooks/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook to retrieve. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`projectId`** :span[string]{.type-label} + +**Response** + +`200` — Returns a runbook + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} +- **`CancelRunningTasks`** :span[boolean]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. +- **`Environments`** :span[array of string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`PublishedRunbookSnapshotId`** :span[string]{.type-label} +- **`RunRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookProcessId`** :span[string]{.type-label} +- **`RunbookTags`** :span[array of string]{.type-label} + List of tags assigned to this runbook. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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" +} +``` +::: + +## Update an existing Runbook + +:endpoint{method="PUT" path="/api/\{spaceId\}/runbooks/\{id\}"} + +Also reachable at `/api/runbooks/{id}`, `/api/spaces/{spaceIdentifier}/runbooks/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the runbook to update, for example 'Runbooks-123'. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} + 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`** :span[boolean]{.type-label} + 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`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + 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`** :span[string]{.type-label} +- **`EnvironmentScope`** :span[enum]{.type-label} + 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`** :span[array of string]{.type-label} + 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`** :span[boolean]{.type-label} + 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`** :span[boolean]{.type-label} + Re-download every package on each run instead of reusing the copy already cached on the deployment target. Resets to false when omitted. +- **`Id`** :span[string]{.type-label} *(required)* + The ID of the runbook to update, for example 'Runbooks-123'. +- **`MultiTenancyMode`** :span[enum]{.type-label} + 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`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ProjectId`** :span[string]{.type-label} *(required)* + The ID of the project the runbook belongs to. Must be a project that stores its runbooks in the Octopus database. +- **`PublishedRunbookSnapshotId`** :span[string]{.type-label} + 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`** :span[object]{.type-label} *(required)* + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookProcessId`** :span[string]{.type-label} + Leave this as the value returned by get_runbook. Octopus manages the link between a runbook and its process. +- **`RunbookTags`** :span[array of string]{.type-label} + 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`** :span[string]{.type-label} + A short URL-friendly identifier for the runbook, unique within the project. The current slug is kept when omitted. +- **`SpaceId`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "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" +} +``` +::: + +**Response** + +`200` — Confirmation that the Runbook has been modified, containing the updated Runbook + +- **`CancelQueuedTasks`** :span[boolean]{.type-label} +- **`CancelRunningTasks`** :span[boolean]{.type-label} +- **`ConnectivityPolicy`** :span[object]{.type-label} + - **`AllowDeploymentsToNoTargets`** :span[boolean]{.type-label} + - **`ExcludeUnhealthyTargets`** :span[boolean]{.type-label} + - **`SkipMachineBehavior`** :span[enum]{.type-label} + Allowed values: `None`, `SkipUnavailableMachines`. + - **`TargetRoles`** :span[array of string]{.type-label} +- **`DefaultGuidedFailureMode`** :span[enum]{.type-label} + Allowed values: `EnvironmentDefault`, `Off`, `On`. +- **`Description`** :span[string]{.type-label} +- **`EnvironmentScope`** :span[enum]{.type-label} + Allowed values: `All`, `Specified`, `FromProjectLifecycles`. +- **`Environments`** :span[array of string]{.type-label} +- **`FailTargetDiscovery`** :span[boolean]{.type-label} +- **`ForcePackageDownload`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MultiTenancyMode`** :span[enum]{.type-label} + Allowed values: `Untenanted`, `TenantedOrUntenanted`, `Tenanted`. +- **`Name`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} +- **`PublishedRunbookSnapshotId`** :span[string]{.type-label} +- **`RunRetentionPolicy`** :span[object]{.type-label} + - **`QuantityToKeep`** :span[integer]{.type-label} + - **`ShouldKeepForever`** :span[boolean]{.type-label} + - **`Strategy`** :span[string]{.type-label} + - **`Unit`** :span[enum]{.type-label} + Allowed values: `Days`, `Items`. +- **`RunbookProcessId`** :span[string]{.type-label} +- **`RunbookTags`** :span[array of string]{.type-label} + List of tags assigned to this runbook. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 an existing Runbook + +:endpoint{method="DELETE" path="/api/\{spaceId\}/runbooks/\{id\}"} + +Also reachable at `/api/runbooks/{id}`, `/api/spaces/{spaceIdentifier}/runbooks/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +## Get a list of environments a Runbook can be run within, based on its EnvironmentScope + +:endpoint{method="GET" path="/api/\{spaceId\}/runbooks/\{id\}/environments"} + +Also reachable at `/api/runbooks/{id}/environments`, `/api/spaces/{spaceIdentifier}/runbooks/{id}/environments`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`projectId`** :span[string]{.type-label} + The ID of the project containing this resource. Will be inferred if not provided. + +**Response** + +`200` — The requested list of Runbook Environments + +- **`AllowDynamicInfrastructure`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + List of tags assigned to this environment. +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this environment. This should be short, preferably 5-20 characters. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} + 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`** :span[string]{.type-label} +- **`UseGuidedFailure`** :span[boolean]{.type-label} + 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. + +:::api-example{label="Response"} +```json +[ + { + "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 all of the information necessary for creating or editing a Runbook Run for this Runbook (when you do not have a snapshot) + +:endpoint{method="GET" path="/api/\{spaceId\}/runbooks/\{id\}/runbookRunTemplate"} + +Also reachable at `/api/runbooks/{id}/runbookRunTemplate`, `/api/spaces/{spaceIdentifier}/runbooks/{id}/runbookRunTemplate`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook to get a Runbook Run Template for. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`projectId`** :span[string]{.type-label} + ID of the project the runbook belongs to. + +**Response** + +`200` — The requested Runbook Template + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsGitResourceModified`** :span[boolean]{.type-label} +- **`IsLibraryVariableSetModified`** :span[boolean]{.type-label} +- **`IsRunbookProcessModified`** :span[boolean]{.type-label} +- **`IsVariableSetModified`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`PromoteTo`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`TenantPromotions`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`PromoteTo`** :span[array of object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 a Runbook Run Preview for a Runbook + +:endpoint{method="GET" path="/api/\{spaceId\}/runbooks/\{id\}/runbookRuns/preview/\{environment\}"} + +Also reachable at `/api/runbooks/{id}/runbookRuns/preview/{environment}`, `/api/spaces/{spaceIdentifier}/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`** :span[string]{.type-label} *(required)* + ID of the Environment. +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`includeDisabledSteps`** :span[boolean]{.type-label} + Boolean to include/exclude disabled steps from response. +- **`projectId`** :span[string]{.type-label} + ID of the Project. +- **`tenant`** :span[string]{.type-label} + ID of the Tenant. + +**Response** + +`200` — Success + +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StepsToExecute`** :span[array of object]{.type-label} + - **`ActionId`** :span[string]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`ActionNumber`** :span[string]{.type-label} + - **`AvailableTagSets`** :span[array of object]{.type-label} + - **`CanBeSkipped`** :span[boolean]{.type-label} + - **`ExcludedMachines`** :span[array of object]{.type-label} + - **`HasNoApplicableMachines`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`MachineNames`** :span[array of string]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`UnavailableMachines`** :span[array of object]{.type-label} +- **`UseGuidedFailureModeByDefault`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 a Runbook Run Preview for a Runbook + +:endpoint{method="GET" path="/api/\{spaceId\}/runbooks/\{id\}/runbookRuns/preview/\{environment\}/\{tenant\}"} + +Also reachable at `/api/runbooks/{id}/runbookRuns/preview/{environment}/{tenant}`, `/api/spaces/{spaceIdentifier}/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`** :span[string]{.type-label} *(required)* + ID of the Environment. +- **`id`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`tenant`** :span[string]{.type-label} *(required)* + ID of the Tenant. + +**Query Parameters** + +- **`includeDisabledSteps`** :span[boolean]{.type-label} + Boolean to include/exclude disabled steps from response. +- **`projectId`** :span[string]{.type-label} + ID of the Project. + +**Response** + +`200` — Success + +- **`Form`** :span[object]{.type-label} + - **`Elements`** :span[array of object]{.type-label} + Elements of the form. + - **`Values`** :span[object]{.type-label} + Values supplied for the form elements. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`StepsToExecute`** :span[array of object]{.type-label} + - **`ActionId`** :span[string]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`ActionNumber`** :span[string]{.type-label} + - **`AvailableTagSets`** :span[array of object]{.type-label} + - **`CanBeSkipped`** :span[boolean]{.type-label} + - **`ExcludedMachines`** :span[array of object]{.type-label} + - **`HasNoApplicableMachines`** :span[boolean]{.type-label} + - **`IsDisabled`** :span[boolean]{.type-label} + - **`MachineNames`** :span[array of string]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`Roles`** :span[array of string]{.type-label} + - **`UnavailableMachines`** :span[array of object]{.type-label} +- **`UseGuidedFailureModeByDefault`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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 +} +``` +::: + +## Run the published version of this Runbook + +:endpoint{method="POST" path="/api/\{spaceId\}/runbooks/\{runbookId\}/run"} + +Also reachable at `/api/runbooks/{runbookId}/run`, `/api/spaces/{spaceIdentifier}/runbooks/{runbookId}/run`. + +**Path Parameters** + +- **`runbookId`** :span[string]{.type-label} *(required)* + ID of the runbook to run. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`ChangeRequestSettings`** :span[array of object]{.type-label} + Change Request Settings. + - **`Type`** :span[enum]{.type-label} + Allowed values: `ServiceNow`, `JiraServiceManagement`. +- **`Comments`** :span[string]{.type-label} + Any additional information/context. +- **`DebugMode`** :span[string]{.type-label} + If set to true contributes the OctopusPrintVariables and OctopusPrintEvaluatedVariables variables to the runbook run. +- **`EnvironmentId`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + 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`** :span[array of string]{.type-label} + A collection of machines in the target environment that should be excluded from the runbook run. +- **`ExcludedTargetTagIds`** :span[array of string]{.type-label} + 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`** :span[boolean]{.type-label} + Whether to skip or fail cloud discovery steps with no matching target (default false). +- **`ForcePackageDownload`** :span[boolean]{.type-label} + Whether to force downloading of already installed packages (flag, default false). +- **`FormValues`** :span[object]{.type-label} + Variables. +- **`Priority`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} + ID of the project that the runbook belongs to. +- **`QueueTime`** :span[string]{.type-label} + The time to execute the runbook run. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + The time at which the runbook run will timeout if it has not started executing. Format `date-time`. +- **`RunbookId`** :span[string]{.type-label} *(required)* + ID of the runbook to run. +- **`RunbookSnapshotNameOrId`** :span[string]{.type-label} + 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`** :span[array of string]{.type-label} + Actions that are to be skipped for this runbook. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`SpecificMachineIds`** :span[array of string]{.type-label} + 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`** :span[array of string]{.type-label} + 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`** :span[string]{.type-label} + Legacy single-tenant field; prefer TenantIds. If set, this tenant is added to the ones the runbook runs for. +- **`TenantIds`** :span[array of string]{.type-label} + 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`** :span[array of string]{.type-label} + The tenant tags to filter tenants to run the runbook. +- **`UseDefaultSnapshot`** :span[boolean]{.type-label} + 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`** :span[boolean]{.type-label} + 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. + +:::api-example{label="Request"} +```json +{ + "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 +} +``` +::: + +**Response** + +`200` — OK + +## Get all of the information necessary for creating or editing a Snapshot for a Runbook + +:endpoint{method="GET" path="/api/\{spaceId\}/runbooks/\{runbookId\}/runbookSnapshotTemplate"} + +Also reachable at `/api/runbooks/{runbookId}/runbookSnapshotTemplate`, `/api/spaces/{spaceIdentifier}/runbooks/{runbookId}/runbookSnapshotTemplate`. + +**Path Parameters** + +- **`runbookId`** :span[string]{.type-label} *(required)* + ID of the Runbook. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`projectId`** :span[string]{.type-label} + Project Id of the project containing the runbook. + +**Response** + +`200` — Confirmation that a new Runbook Snapshot Template has been created, containing the template + +- **`GitResources`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + Minimum length 1. + - **`DefaultBranch`** :span[string]{.type-label} + Minimum length 1. + - **`FilePathFilters`** :span[array of string]{.type-label} + - **`GitCredentialId`** :span[string]{.type-label} + - **`GitHubConnectionId`** :span[string]{.type-label} + - **`GitResourceSelectedLastRelease`** :span[object]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`RepositoryUri`** :span[string]{.type-label} + Minimum length 1. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NextNameIncrement`** :span[string]{.type-label} +- **`Packages`** :span[array of object]{.type-label} + - **`ActionName`** :span[string]{.type-label} + - **`FeedId`** :span[string]{.type-label} + - **`FeedName`** :span[string]{.type-label} + - **`FixedVersion`** :span[string]{.type-label} + - **`IsResolvable`** :span[boolean]{.type-label} + 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`** :span[string]{.type-label} + - **`NuGetFeedName`** :span[string]{.type-label} + - **`NuGetPackageId`** :span[string]{.type-label} + - **`PackageId`** :span[string]{.type-label} + - **`PackageReferenceName`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`StepName`** :span[string]{.type-label} + - **`VersionSelectedLastRelease`** :span[string]{.type-label} +- **`RunbookId`** :span[string]{.type-label} +- **`RunbookProcessId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "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" +} +``` +::: diff --git a/src/pages/docs/api/scheduled-jobs.md b/src/pages/docs/api/scheduled-jobs.md new file mode 100644 index 0000000000..5911f81924 --- /dev/null +++ b/src/pages/docs/api/scheduled-jobs.md @@ -0,0 +1,215 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Scheduled Jobs +--- + +## Get the status of all the scheduled jobs + +:endpoint{method="GET" path="/api/scheduler"} + +**Response** + +`200` — The Status of all the scheduled jobs + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsRunning`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`TaskStatus`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsEnabled`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "IsRunning": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "TaskStatus": [ + { + "Id": "string", + "IsEnabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } + ] +} +``` +::: + +## Enable a scheduled job or the job scheduler + +:endpoint{method="GET" path="/api/scheduler/start"} + +**Query Parameters** + +- **`task`** :span[string]{.type-label} + The name of the Job to enable. If null the job scheduler itself will be enabled. + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Disable a scheduled job or the job scheduler + +:endpoint{method="GET" path="/api/scheduler/stop"} + +**Query Parameters** + +- **`task`** :span[string]{.type-label} + The name of the Job to disable. If null the job scheduler itself will be disableped. + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Trigger a scheduled job immediately and waits for it to complete + +:endpoint{method="GET" path="/api/scheduler/trigger"} + +**Query Parameters** + +- **`task`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Get the structured log for a scheduled job + +:endpoint{method="GET" path="/api/scheduler/\{name\}/logs"} + +**Path Parameters** + +- **`name`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`tail`** :span[integer]{.type-label} +- **`verbose`** :span[boolean]{.type-label} + +**Response** + +`200` — The structured log for a scheduled job + +- **`ActivityLog`** :span[object]{.type-label} + - **`Children`** :span[array of object]{.type-label} + - **`Ended`** :span[string]{.type-label} + Format `date-time`. + - **`Id`** :span[string]{.type-label} + - **`LogElements`** :span[array of object]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`ProgressMessage`** :span[string]{.type-label} + - **`ProgressPercentage`** :span[integer]{.type-label} + - **`ShowAtSummaryLevel`** :span[boolean]{.type-label} + - **`Started`** :span[string]{.type-label} + Format `date-time`. + - **`Status`** :span[enum]{.type-label} + Allowed values: `Pending`, `Running`, `Success`, `Failed`, `Skipped`, `SuccessWithWarning`, `Canceled`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + +:::api-example{label="Response"} +```json +{ + "ActivityLog": { + "Children": [], + "Ended": "2020-01-01T00:00:00.000Z", + "Id": "string", + "LogElements": [ + { + "Category": "Trace", + "Detail": "string", + "GapLastNumber": 0, + "MessageText": "string", + "Number": 0, + "OccurredAt": "2020-01-01T00:00:00.000Z" + } + ], + "Name": "string", + "ProgressMessage": "string", + "ProgressPercentage": 0, + "ShowAtSummaryLevel": true, + "Started": "2020-01-01T00:00:00.000Z", + "Status": "Pending" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +## Get the raw log for a scheduled job + +:endpoint{method="GET" path="/api/scheduler/\{name\}/logs/raw"} + +**Path Parameters** + +- **`name`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: diff --git a/src/pages/docs/api/scoped-user-roles.md b/src/pages/docs/api/scoped-user-roles.md new file mode 100644 index 0000000000..f9dec3bc8f --- /dev/null +++ b/src/pages/docs/api/scoped-user-roles.md @@ -0,0 +1,378 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Scoped User Roles +--- + +## List the name and ID of all of the scoped user roles in the supplied Octopus Deploy Space. The results will be sorted by name + +:endpoint{method="GET" path="/api/\{spaceId\}/scopeduserroles"} + +Also reachable at `/api/scopeduserroles`, `/api/spaces/{spaceIdentifier}/scopeduserroles`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resources. + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested list of Scoped User Roles + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`EnvironmentIds`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ProjectGroupIds`** :span[array of string]{.type-label} + - **`ProjectIds`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`TeamId`** :span[string]{.type-label} + - **`TenantIds`** :span[array of string]{.type-label} + - **`UserRoleId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TeamId": "string", + "TenantIds": [ + "string" + ], + "UserRoleId": "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 +} +``` +::: + +## Create a scoped user role + +:endpoint{method="POST" path="/api/\{spaceId\}/scopeduserroles"} + +Also reachable at `/api/scopeduserroles`, `/api/spaces/{spaceIdentifier}/scopeduserroles`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`ProjectGroupIds`** :span[array of string]{.type-label} +- **`ProjectIds`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TeamId`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`TenantIds`** :span[array of string]{.type-label} +- **`UserRoleId`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "EnvironmentIds": [ + "string" + ], + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TeamId": "string", + "TenantIds": [ + "string" + ], + "UserRoleId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectGroupIds`** :span[array of string]{.type-label} +- **`ProjectIds`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TeamId`** :span[string]{.type-label} +- **`TenantIds`** :span[array of string]{.type-label} +- **`UserRoleId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TeamId": "string", + "TenantIds": [ + "string" + ], + "UserRoleId": "string" +} +``` +::: + +## Get a Scoped User Role by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/scopeduserroles/\{id\}"} + +Also reachable at `/api/scopeduserroles/{id}`, `/api/spaces/{spaceIdentifier}/scopeduserroles/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resources. + +**Response** + +`200` — Scoped User Role. + +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectGroupIds`** :span[array of string]{.type-label} +- **`ProjectIds`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TeamId`** :span[string]{.type-label} +- **`TenantIds`** :span[array of string]{.type-label} +- **`UserRoleId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TeamId": "string", + "TenantIds": [ + "string" + ], + "UserRoleId": "string" +} +``` +::: + +## Modify a scoped user role + +:endpoint{method="PUT" path="/api/\{spaceId\}/scopeduserroles/\{id\}"} + +Also reachable at `/api/scopeduserroles/{id}`, `/api/spaces/{spaceIdentifier}/scopeduserroles/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the scoped user role to modify. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* + The ID of the scoped user role to modify. Minimum length 1. +- **`ProjectGroupIds`** :span[array of string]{.type-label} +- **`ProjectIds`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TeamId`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`TenantIds`** :span[array of string]{.type-label} +- **`UserRoleId`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TeamId": "string", + "TenantIds": [ + "string" + ], + "UserRoleId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Scoped User Role was modified, containing the updated Role + +- **`EnvironmentIds`** :span[array of string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectGroupIds`** :span[array of string]{.type-label} +- **`ProjectIds`** :span[array of string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TeamId`** :span[string]{.type-label} +- **`TenantIds`** :span[array of string]{.type-label} +- **`UserRoleId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TeamId": "string", + "TenantIds": [ + "string" + ], + "UserRoleId": "string" +} +``` +::: + +## Delete an existing Scoped User Role + +:endpoint{method="DELETE" path="/api/\{spaceId\}/scopeduserroles/\{id\}"} + +Also reachable at `/api/scopeduserroles/{id}`, `/api/spaces/{spaceIdentifier}/scopeduserroles/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Scoped User Role to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success diff --git a/src/pages/docs/api/server-status.md b/src/pages/docs/api/server-status.md new file mode 100644 index 0000000000..cfe19f9de1 --- /dev/null +++ b/src/pages/docs/api/server-status.md @@ -0,0 +1,335 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Server Status +--- + +## Get the status of Octopus Server + +:endpoint{method="GET" path="/api/serverstatus"} + +Shows information about the status of the Octopus Server. + +**Response** + +`200` — A snapshot of the server's current status + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDatabaseEncrypted`** :span[boolean]{.type-label} +- **`IsInMaintenanceMode`** :span[boolean]{.type-label} +- **`IsMajorMinorUpgrade`** :span[boolean]{.type-label} +- **`IsPotentialClone`** :span[boolean]{.type-label} +- **`IsUpgradeAvailable`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MaintenanceExpires`** :span[string]{.type-label} +- **`MaximumAvailableVersion`** :span[string]{.type-label} +- **`MaximumAvailableVersionCoveredByLicense`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "IsDatabaseEncrypted": true, + "IsInMaintenanceMode": true, + "IsMajorMinorUpgrade": true, + "IsPotentialClone": true, + "IsUpgradeAvailable": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MaintenanceExpires": "string", + "MaximumAvailableVersion": "string", + "MaximumAvailableVersionCoveredByLicense": "string" +} +``` +::: + +## Get counts of documents in the server + +:endpoint{method="GET" path="/api/serverstatus/counts"} + +List counts of various document types to assist in diagnosing issues with the server. + +**Response** + +`200` — The requested Server Document Counts + +- **`Global`** :span[object]{.type-label} + - **`Spaces`** :span[integer]{.type-label} + - **`Teams`** :span[integer]{.type-label} + - **`Users`** :span[integer]{.type-label} +- **`Infrastructure`** :span[object]{.type-label} + - **`DeploymentTargets`** :span[integer]{.type-label} + - **`Environments`** :span[integer]{.type-label} + - **`Tenants`** :span[integer]{.type-label} + - **`WorkerPools`** :span[integer]{.type-label} + - **`Workers`** :span[integer]{.type-label} +- **`Library`** :span[object]{.type-label} + - **`Certificates`** :span[integer]{.type-label} + - **`Packages`** :span[integer]{.type-label} + - **`VariableSets`** :span[integer]{.type-label} +- **`Project`** :span[object]{.type-label} + - **`Deployments`** :span[integer]{.type-label} + - **`Projects`** :span[integer]{.type-label} + - **`Releases`** :span[integer]{.type-label} + - **`RunbookRuns`** :span[integer]{.type-label} + - **`Runbooks`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Global": { + "Spaces": 0, + "Teams": 0, + "Users": 0 + }, + "Infrastructure": { + "DeploymentTargets": 0, + "Environments": 0, + "Tenants": 0, + "WorkerPools": 0, + "Workers": 0 + }, + "Library": { + "Certificates": 0, + "Packages": 0, + "VariableSets": 0 + }, + "Project": { + "Deployments": 0, + "Projects": 0, + "Releases": 0, + "RunbookRuns": 0, + "Runbooks": 0 + } +} +``` +::: + +## Force a GC collect + +:endpoint{method="POST" path="/api/serverstatus/gc-collect"} + +Triggers a garbage collection pass for all heap generations, including the large object heap. + +**Response** + +`200` — OK + +## Force a GC collect + +:endpoint{method="POST" path="/api/serverstatus/gc-collect/v1"} + +Triggers a garbage collection pass for all heap generations, including the large object heap. + +**Response** + +`200` — Internal + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get the general health of Octopus Server + +:endpoint{method="GET" path="/api/serverstatus/health"} + +Provides a super simple interface perfect for checking the general health of your entire Octopus Server cluster. + +**Response** + +`200` — A snapshot of the server or cluster's current health + +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsCompliantWithLicense`** :span[boolean]{.type-label} +- **`IsEntireClusterDrainingTasks`** :span[boolean]{.type-label} +- **`IsEntireClusterReadOnly`** :span[boolean]{.type-label} +- **`IsOperatingNormally`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Id": "string", + "IsCompliantWithLicense": true, + "IsEntireClusterDrainingTasks": true, + "IsEntireClusterReadOnly": true, + "IsOperatingNormally": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +**Error Responses** + +- **`418`** — Indicates that the server is not operating normally + +## Retrieve the most recent high-priority log messages from this execution of the Octopus Server process + +:endpoint{method="GET" path="/api/serverstatus/logs"} + +**Query Parameters** + +- **`includeDetail`** :span[boolean]{.type-label} +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The most recent high-priority log messages from this execution of the Octopus Server process + +- **`Category`** :span[string]{.type-label} +- **`Detail`** :span[string]{.type-label} +- **`GapLastNumber`** :span[integer]{.type-label} +- **`MessageText`** :span[string]{.type-label} +- **`Number`** :span[integer]{.type-label} +- **`OccurredAt`** :span[string]{.type-label} + Format `date-time`. + +:::api-example{label="Response"} +```json +[ + { + "Category": "string", + "Detail": "string", + "GapLastNumber": 0, + "MessageText": "string", + "Number": 0, + "OccurredAt": "2020-01-01T00:00:00.000Z" + } +] +``` +::: + +## Provide information about the Octopus Server process and the machine on which it is running + +:endpoint{method="GET" path="/api/serverstatus/system-info"} + +**Response** + +`200` — Information about the Octopus Server process and the machine on which it is running. + +- **`ClrVersion`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MinThreadPoolCount`** :span[integer]{.type-label} +- **`OSVersion`** :span[string]{.type-label} +- **`ThreadCount`** :span[integer]{.type-label} +- **`Uptime`** :span[string]{.type-label} + Format `date-span`. +- **`Version`** :span[string]{.type-label} +- **`WorkingSetBytes`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ClrVersion": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MinThreadPoolCount": 0, + "OSVersion": "string", + "ThreadCount": 0, + "Uptime": "string", + "Version": "string", + "WorkingSetBytes": 0 +} +``` +::: + +## Create a .zip archive containing an aggregate of the other system information APIs + +:endpoint{method="GET" path="/api/serverstatus/system-report"} + +**Query Parameters** + +- **`nodeSpecificOnly`** :span[boolean]{.type-label} + When true, only node-specific sections are included (recent logs, system info, filesystem logs). Defaults to false (full report) when not set. + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## List timezones supported by the server + +:endpoint{method="GET" path="/api/serverstatus/timezones"} + +**Response** + +`200` — The requested list of timezones supported by the server. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsLocal`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Id": "string", + "IsLocal": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } +] +``` +::: diff --git a/src/pages/docs/api/server.md b/src/pages/docs/api/server.md new file mode 100644 index 0000000000..553f0605b7 --- /dev/null +++ b/src/pages/docs/api/server.md @@ -0,0 +1,117 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Server +--- + +## Request the current server configuration + +:endpoint{method="GET" path="/api/serverconfiguration"} + +**Response** + +`200` — The current server configuration + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ServerUri`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ServerUri": "string" +} +``` +::: + +## Set the server configuration + +:endpoint{method="PUT" path="/api/serverconfiguration"} + +**Request Body** + +- **`ServerUri`** :span[string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "ServerUri": "string" +} +``` +::: + +**Response** + +`200` — The updated server configuration + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ServerUri`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ServerUri": "string" +} +``` +::: + +## Request the current server configuration settings + +:endpoint{method="GET" path="/api/serverconfiguration/settings"} + +**Response** + +`200` — The current server configuration settings + +- **`ConfigurationSet`** :span[string]{.type-label} +- **`ConfigurationValues`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Key`** :span[string]{.type-label} + - **`Value`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "ConfigurationSet": "string", + "ConfigurationValues": [ + { + "Description": "string", + "Key": "string", + "Value": "string" + } + ] + } +] +``` +::: diff --git a/src/pages/docs/api/service-account-oidc-identities.md b/src/pages/docs/api/service-account-oidc-identities.md new file mode 100644 index 0000000000..6b6e7176e6 --- /dev/null +++ b/src/pages/docs/api/service-account-oidc-identities.md @@ -0,0 +1,224 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Service Account Oidc Identities +--- + +## Create new OIDC Identity for a Service Account + +:endpoint{method="POST" path="/api/serviceaccounts/\{serviceAccountId\}/oidcidentities/create/v1"} + +**Path Parameters** + +- **`serviceAccountId`** :span[string]{.type-label} *(required)* + The id of the service account that the identity belonds to. + +**Request Body** + +- **`Audience`** :span[string]{.type-label} + The audience of tokens for the identity. +- **`Issuer`** :span[string]{.type-label} *(required)* + Gets the issuer of tokens for the identity. Minimum length 1. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the ServiceAccountOidcIdentity. Minimum length 1. Maximum length 200. +- **`ServiceAccountId`** :span[string]{.type-label} *(required)* + The id of the service account that the identity belonds to. +- **`Subject`** :span[string]{.type-label} *(required)* + Gets the subject of tokens for the identity. Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "Audience": "string", + "Issuer": "string", + "Name": "string", + "ServiceAccountId": "string", + "Subject": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Id`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string" +} +``` +::: + +## Get ServiceAccountOidcIdentities + +:endpoint{method="GET" path="/api/serviceaccounts/\{serviceAccountId\}/oidcidentities/v1"} + +Gets a paginated set of ServiceAccountOidcIdentities. + +**Path Parameters** + +- **`serviceAccountId`** :span[string]{.type-label} *(required)* + The id of the service account to get OIDC identities for. + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} *(required)* + Number of items to skip. Minimum `0`. +- **`take`** :span[integer]{.type-label} *(required)* + Number of items to take. Minimum `0`. + +**Response** + +`200` — Rseponse to getting set of ServiceAccountOidcIdentities + +- **`Count`** :span[integer]{.type-label} +- **`ExternalId`** :span[string]{.type-label} + Minimum length 1. +- **`OidcIdentities`** :span[array of object]{.type-label} + - **`Audience`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`Issuer`** :span[string]{.type-label} + Minimum length 1. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`ServiceAccountId`** :span[string]{.type-label} + - **`Subject`** :span[string]{.type-label} + Minimum length 1. +- **`ServerUrl`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Count": 0, + "ExternalId": "string", + "OidcIdentities": [ + { + "Audience": "string", + "Id": "string", + "Issuer": "string", + "Name": "string", + "ServiceAccountId": "string", + "Subject": "string" + } + ], + "ServerUrl": "string" +} +``` +::: + +## Get ServiceAccountOidcIdentity by id + +:endpoint{method="GET" path="/api/serviceaccounts/\{serviceAccountId\}/oidcidentities/\{id\}/v1"} + +Gets a ServiceAccountOidcIdentity by its id. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the ServiceAccountOidcIdentity. +- **`serviceAccountId`** :span[string]{.type-label} *(required)* + The id of the space for the ServiceAccountOidcIdentity. + +**Response** + +`200` — Response to getting a ServiceAccountOidcIdentity by id + +- **`Audience`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} +- **`Issuer`** :span[string]{.type-label} + Minimum length 1. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`ServiceAccountId`** :span[string]{.type-label} +- **`Subject`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "Audience": "string", + "Id": "string", + "Issuer": "string", + "Name": "string", + "ServiceAccountId": "string", + "Subject": "string" +} +``` +::: + +## Modify ServiceAccountOidcIdentity + +:endpoint{method="PUT" path="/api/serviceaccounts/\{serviceAccountId\}/oidcidentities/\{id\}/v1"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the ServiceAccountOidcIdentity. +- **`serviceAccountId`** :span[string]{.type-label} *(required)* + The id of the space for the ServiceAccountOidcIdentity. + +**Request Body** + +- **`Audience`** :span[string]{.type-label} + The audience of tokens for the OIDC identity. +- **`Id`** :span[string]{.type-label} *(required)* + The id of the ServiceAccountOidcIdentity. +- **`Issuer`** :span[string]{.type-label} *(required)* + The issuer of tokens for the OIDC identity. Minimum length 1. Maximum length 200. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the ServiceAccountOidcIdentity. Minimum length 1. Maximum length 200. +- **`ServiceAccountId`** :span[string]{.type-label} *(required)* + The id of the space for the ServiceAccountOidcIdentity. +- **`Subject`** :span[string]{.type-label} *(required)* + The name of the ServiceAccountOidcIdentity. Minimum length 1. Maximum length 200. + +:::api-example{label="Request"} +```json +{ + "Audience": "string", + "Id": "string", + "Issuer": "string", + "Name": "string", + "ServiceAccountId": "string", + "Subject": "string" +} +``` +::: + +**Response** + +`200` — Response to modifying a ServiceAccountOidcIdentity + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Delete ServiceAccountOidcIdentity + +:endpoint{method="DELETE" path="/api/serviceaccounts/\{serviceAccountId\}/oidcidentities/\{id\}/v1"} + +Deletes a ServiceAccountOidcIdentity. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The id of the ServiceAccountOidcIdentity. +- **`serviceAccountId`** :span[string]{.type-label} *(required)* + The id of the service account that the identity belongs to. + +**Response** + +`200` — Response to deleting a ServiceAccountOidcIdentity + +:::api-example{label="Response"} +```json +{} +``` +::: diff --git a/src/pages/docs/api/signing.md b/src/pages/docs/api/signing.md new file mode 100644 index 0000000000..2f06ac1d8f --- /dev/null +++ b/src/pages/docs/api/signing.md @@ -0,0 +1,167 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Signing +--- + +## Request the current signing key configuration + +:endpoint{method="GET" path="/api/signingkeyconfiguration"} + +**Response** + +`200` — The current signing key configuration + +- **`ExpireAfterDays`** :span[integer]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`PublicKeyHostingLocation`** :span[enum]{.type-label} + Allowed values: `Internal`, `External`. +- **`RevokeAfterDays`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ExpireAfterDays": 0, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PublicKeyHostingLocation": "Internal", + "RevokeAfterDays": 0 +} +``` +::: + +## Set the signing key configuration + +:endpoint{method="PUT" path="/api/signingkeyconfiguration"} + +**Request Body** + +- **`ExpireAfterDays`** :span[integer]{.type-label} *(required)* + Minimum `1`. Maximum `365`. +- **`PublicKeyHostingLocation`** :span[enum]{.type-label} + Allowed values: `Internal`, `External`. +- **`RevokeAfterDays`** :span[integer]{.type-label} *(required)* + Minimum `1`. Maximum `365`. + +:::api-example{label="Request"} +```json +{ + "ExpireAfterDays": 0, + "PublicKeyHostingLocation": "Internal", + "RevokeAfterDays": 0 +} +``` +::: + +**Response** + +`200` — The updated signing key configuration + +- **`ExpireAfterDays`** :span[integer]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`PublicKeyHostingLocation`** :span[enum]{.type-label} + Allowed values: `Internal`, `External`. +- **`RevokeAfterDays`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ExpireAfterDays": 0, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PublicKeyHostingLocation": "Internal", + "RevokeAfterDays": 0 +} +``` +::: + +## Create a new key that is pending activation + +:endpoint{method="POST" path="/api/signingkeys/pending/generate/v1"} + +**Response** + +`200` — Returns the Id of the generated signing key. + +- **`Id`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string" +} +``` +::: + +## Activate an existing pending signing key, making it the active signing key for the system + +:endpoint{method="POST" path="/api/signingkeys/pending/\{id\}/activate/v1"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Indicates the key was activated + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Validate that the public signing keys are valid and can be used to verify signatures. This is intended to be used as a health check for external key hosting, and will return an error if the keys are invalid or expired + +:endpoint{method="POST" path="/api/signingkeys/verify/v1"} + +**Request Body** + +- **`IncludeExpiredKeys`** :span[boolean]{.type-label} +- **`Issuer`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "IncludeExpiredKeys": true, + "Issuer": "string" +} +``` +::: + +**Response** + +`200` — Response to VerifySigningKeysCommandV1. An empty response indicates that the signing keys are valid and can be used to verify signatures. If the signing keys are invalid or expired, an error will be returned instead of this response. + +:::api-example{label="Response"} +```json +{} +``` +::: diff --git a/src/pages/docs/api/slack-integration.md b/src/pages/docs/api/slack-integration.md new file mode 100644 index 0000000000..a6ff1b433f --- /dev/null +++ b/src/pages/docs/api/slack-integration.md @@ -0,0 +1,70 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Slack Integration +--- + +## GET /api/integrations/slack/channels + +:endpoint{method="GET" path="/api/integrations/slack/channels"} + +**Response** + +`200` — OK + +## GET /api/integrations/slack/channels/resolve + +:endpoint{method="GET" path="/api/integrations/slack/channels/resolve"} + +**Response** + +`200` — OK + +## GET /api/integrations/slack/configuration + +:endpoint{method="GET" path="/api/integrations/slack/configuration"} + +**Response** + +`200` — OK + +## DELETE /api/integrations/slack/connection + +:endpoint{method="DELETE" path="/api/integrations/slack/connection"} + +**Response** + +`200` — OK + +## POST /api/integrations/slack/connection/test + +:endpoint{method="POST" path="/api/integrations/slack/connection/test"} + +**Response** + +`200` — OK + +## POST /api/integrations/slack/credentials + +:endpoint{method="POST" path="/api/integrations/slack/credentials"} + +**Response** + +`200` — OK + +## GET /api/integrations/slack/oauth/callback + +:endpoint{method="GET" path="/api/integrations/slack/oauth/callback"} + +**Response** + +`200` — OK + +## GET /api/integrations/slack/oauth/start + +:endpoint{method="GET" path="/api/integrations/slack/oauth/start"} + +**Response** + +`200` — OK diff --git a/src/pages/docs/api/smtp.md b/src/pages/docs/api/smtp.md new file mode 100644 index 0000000000..ad0321b9f9 --- /dev/null +++ b/src/pages/docs/api/smtp.md @@ -0,0 +1,249 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Smtp +--- + +## Get information about the SMTP (email) settings in use by the Octopus Server + +:endpoint{method="GET" path="/api/smtpconfiguration"} + +**Response** + +`200` — The requested SMTP configuration + +- **`Details`** :span[object]{.type-label} + - **`CredentialType`** :span[string]{.type-label} +- **`EnableSsl`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`SendEmailFrom`** :span[string]{.type-label} +- **`SmtpHost`** :span[string]{.type-label} +- **`SmtpPort`** :span[number]{.type-label} + Minimum `0`. Maximum `65535`. +- **`Timeout`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Details": { + "CredentialType": "string" + }, + "EnableSsl": true, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "SendEmailFrom": "string", + "SmtpHost": "string", + "SmtpPort": 0, + "Timeout": 0 +} +``` +::: + +## Update the SMTP settings used by the Octopus Server + +:endpoint{method="PUT" path="/api/smtpconfiguration"} + +**Request Body** + +- **`Details`** :span[object]{.type-label} + - **`CredentialType`** :span[string]{.type-label} +- **`EnableSsl`** :span[boolean]{.type-label} +- **`SendEmailFrom`** :span[string]{.type-label} +- **`SmtpHost`** :span[string]{.type-label} +- **`SmtpPort`** :span[integer]{.type-label} + Minimum `0`. Maximum `65535`. +- **`Timeout`** :span[integer]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Details": { + "CredentialType": "string" + }, + "EnableSsl": true, + "SendEmailFrom": "string", + "SmtpHost": "string", + "SmtpPort": 0, + "Timeout": 0 +} +``` +::: + +**Response** + +`200` — Confirmation that SMTP Configuration was modified, containing the new configuration + +- **`Details`** :span[object]{.type-label} + - **`CredentialType`** :span[string]{.type-label} +- **`EnableSsl`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`SendEmailFrom`** :span[string]{.type-label} +- **`SmtpHost`** :span[string]{.type-label} +- **`SmtpPort`** :span[number]{.type-label} + Minimum `0`. Maximum `65535`. +- **`Timeout`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Details": { + "CredentialType": "string" + }, + "EnableSsl": true, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "SendEmailFrom": "string", + "SmtpHost": "string", + "SmtpPort": 0, + "Timeout": 0 +} +``` +::: + +## Check whether SMTP is configured with low privileges + +:endpoint{method="GET" path="/api/smtpconfiguration/isconfigured"} + +**Response** + +`200` — The requested information about whether SMTP is configured + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsConfigured`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "IsConfigured": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +## Check whether SMTP is configured with low privileges + +:endpoint{method="GET" path="/api/smtpconfiguration/isconfigured/v1"} + +**Response** + +`200` — The requested information about whether SMTP is configured + +- **`SmtpIsConfigured`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsConfigured`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + +:::api-example{label="Response"} +```json +{ + "SmtpIsConfigured": { + "Id": "string", + "IsConfigured": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + } +} +``` +::: + +## Get information about the SMTP (email) settings in use by the Octopus Server + +:endpoint{method="GET" path="/api/smtpconfiguration/v1"} + +**Response** + +`200` — The requested SMTP configuration + +- **`SmtpConfiguration`** :span[object]{.type-label} + - **`Details`** :span[object]{.type-label} + - **`EnableSsl`** :span[boolean]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`SendEmailFrom`** :span[string]{.type-label} + - **`SmtpHost`** :span[string]{.type-label} + - **`SmtpPort`** :span[number]{.type-label} + Minimum `0`. Maximum `65535`. + - **`Timeout`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "SmtpConfiguration": { + "Details": { + "CredentialType": "string" + }, + "EnableSsl": true, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "SendEmailFrom": "string", + "SmtpHost": "string", + "SmtpPort": 0, + "Timeout": 0 + } +} +``` +::: diff --git a/src/pages/docs/api/spaces.md b/src/pages/docs/api/spaces.md new file mode 100644 index 0000000000..0c048148e7 --- /dev/null +++ b/src/pages/docs/api/spaces.md @@ -0,0 +1,1769 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Spaces +--- + +## Get a collection of Git credentials + +:endpoint{method="GET" path="/api/\{spaceId\}/git-credentials"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`name`** :span[string]{.type-label} + Filters credentials matching any part of the `name` fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested Git Credentials + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Details`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`RepositoryRestrictions`** :span[object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Description": "string", + "Details": { + "Type": "UsernamePassword" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + }, + "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 +} +``` +::: + +## Create a new Git credential + +:endpoint{method="POST" path="/api/\{spaceId\}/git-credentials"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} *(required)* + - **`Password`** :span[sensitive value]{.type-label} *(required)* + - **`Username`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`RepositoryRestrictions`** :span[object]{.type-label} + - **`AllowedRepositories`** :span[array of string]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Details": { + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Username": "string" + }, + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + }, + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Id`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +## Get a collection of Git credentials + +:endpoint{method="GET" path="/api/\{spaceId\}/git-credentials/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials/v1`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`name`** :span[string]{.type-label} + Filters credentials matching any part of the `name` fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested Git Credentials + +- **`GitCredentials`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`ItemType`** :span[string]{.type-label} + - **`Items`** :span[array of object]{.type-label} + - **`ItemsPerPage`** :span[integer]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastPageNumber`** :span[integer]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`NumberOfPages`** :span[integer]{.type-label} + - **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "GitCredentials": { + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Description": "string", + "Details": {}, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {}, + "Name": "string", + "RepositoryRestrictions": {}, + "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 + } +} +``` +::: + +## Create a new Git credential + +:endpoint{method="POST" path="/api/\{spaceId\}/git-credentials/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials/v1`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} *(required)* + - **`Password`** :span[sensitive value]{.type-label} *(required)* + - **`Username`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`RepositoryRestrictions`** :span[object]{.type-label} + - **`AllowedRepositories`** :span[array of string]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Details": { + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Username": "string" + }, + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + }, + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Id`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +## Get a collection of Git credentials + +:endpoint{method="GET" path="/api/\{spaceId\}/git-credentials/v2"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials/v2`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`name`** :span[string]{.type-label} + Filters credentials matching any part of the `name` fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Success + +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Details`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + - **`LastModifiedOn`** :span[string]{.type-label} + Format `date-time`. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`RepositoryRestrictions`** :span[object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastPageNumber`** :span[integer]{.type-label} +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ItemType": "string", + "Items": [ + { + "Description": "string", + "Details": { + "Type": "UsernamePassword" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + }, + "SpaceId": "string" + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new Git credential + +:endpoint{method="POST" path="/api/\{spaceId\}/git-credentials/v2"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials/v2`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} *(required)* + - **`Type`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`RepositoryRestrictions`** :span[object]{.type-label} + - **`AllowedRepositories`** :span[array of string]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Details": { + "Type": "string" + }, + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + }, + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Id`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string" +} +``` +::: + +## Get a specific Git credential + +:endpoint{method="GET" path="/api/\{spaceId\}/git-credentials/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Git credential to get. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Git Credential + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `UsernamePassword`, `Anonymous`, `Library`, `GitHub`, `NotSpecified`, `SshKey`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`RepositoryRestrictions`** :span[object]{.type-label} + - **`AllowedRepositories`** :span[array of string]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Details": { + "Type": "UsernamePassword" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + }, + "SpaceId": "string" +} +``` +::: + +## Modify an existing Git credential + +:endpoint{method="PUT" path="/api/\{spaceId\}/git-credentials/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} *(required)* + - **`Password`** :span[sensitive value]{.type-label} *(required)* + - **`Username`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Id`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`RepositoryRestrictions`** :span[object]{.type-label} + - **`AllowedRepositories`** :span[array of string]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Details": { + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Username": "string" + }, + "Id": "string", + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + }, + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Git Credential was modified + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Delete an existing Git credential + +:endpoint{method="DELETE" path="/api/\{spaceId\}/git-credentials/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Git credential to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the Git Credential has been deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get usage of a specific Git credential + +:endpoint{method="GET" path="/api/\{spaceId\}/git-credentials/\{id\}/usage"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials/{id}/usage`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Git credential to get usage for. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Git Credential Usage + +- **`OtherProjects`** :span[integer]{.type-label} +- **`Projects`** :span[array of object]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`ProjectId`** :span[string]{.type-label} + - **`RepositoryUrl`** :span[string]{.type-label} + - **`Slug`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "OtherProjects": 0, + "Projects": [ + { + "Name": "string", + "ProjectId": "string", + "RepositoryUrl": "string", + "Slug": "string" + } + ] +} +``` +::: + +## Get usage of a specific Git credential + +:endpoint{method="GET" path="/api/\{spaceId\}/git-credentials/\{id\}/usage/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials/{id}/usage/v1`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Git credential to get usage for. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Git Credential Usage + +- **`OtherProjects`** :span[integer]{.type-label} +- **`Projects`** :span[array of object]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`ProjectId`** :span[string]{.type-label} + - **`RepositoryUrl`** :span[string]{.type-label} + - **`Slug`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +{ + "OtherProjects": 0, + "Projects": [ + { + "Name": "string", + "ProjectId": "string", + "RepositoryUrl": "string", + "Slug": "string" + } + ] +} +``` +::: + +## Get a specific Git credential + +:endpoint{method="GET" path="/api/\{spaceId\}/git-credentials/\{id\}/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials/{id}/v1`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Git credential to get. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Git Credential + +- **`GitCredential`** :span[object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Details`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`RepositoryRestrictions`** :span[object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "GitCredential": { + "Description": "string", + "Details": { + "Type": "UsernamePassword" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + }, + "SpaceId": "string" + } +} +``` +::: + +## Modify an existing Git credential + +:endpoint{method="PUT" path="/api/\{spaceId\}/git-credentials/\{id\}/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials/{id}/v1`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} *(required)* + - **`Password`** :span[sensitive value]{.type-label} *(required)* + - **`Username`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Id`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`RepositoryRestrictions`** :span[object]{.type-label} + - **`AllowedRepositories`** :span[array of string]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Details": { + "Password": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Username": "string" + }, + "Id": "string", + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + }, + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Git Credential was modified + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Delete an existing Git credential + +:endpoint{method="DELETE" path="/api/\{spaceId\}/git-credentials/\{id\}/v1"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials/{id}/v1`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Git credential to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the Git Credential has been deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get a specific Git credential + +:endpoint{method="GET" path="/api/\{spaceId\}/git-credentials/\{id\}/v2"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials/{id}/v2`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Git credential to get. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Git Credential + +- **`GitCredential`** :span[object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Details`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + - **`LastModifiedOn`** :span[string]{.type-label} + Format `date-time`. + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`RepositoryRestrictions`** :span[object]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "GitCredential": { + "Description": "string", + "Details": { + "Type": "UsernamePassword" + }, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + }, + "SpaceId": "string" + } +} +``` +::: + +## Modify an existing Git credential + +:endpoint{method="PUT" path="/api/\{spaceId\}/git-credentials/\{id\}/v2"} + +Also reachable at `/api/spaces/{spaceIdentifier}/git-credentials/{id}/v2`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Details`** :span[object]{.type-label} *(required)* + - **`Type`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Id`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`RepositoryRestrictions`** :span[object]{.type-label} + - **`AllowedRepositories`** :span[array of string]{.type-label} + - **`Enabled`** :span[boolean]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Details": { + "Type": "string" + }, + "Id": "string", + "Name": "string", + "RepositoryRestrictions": { + "AllowedRepositories": [ + "string" + ], + "Enabled": true + }, + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Confirmation that the Git Credential was modified + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get the git references that match the given rule pattern for a project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/git/refs"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/refs`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`patterns`** :span[array of string]{.type-label} *(required)* +- **`skip`** :span[integer]{.type-label} *(required)* + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} *(required)* + Number of items to skip. Defaults to zero. Minimum `0`. + +**Response** + +`200` — Response contain a set of Git references that match the rule pattern for the project + +- **`References`** :span[array of object]{.type-label} + - **`CanonicalName`** :span[string]{.type-label} + Minimum length 1. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`TotalCount`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "References": [ + { + "CanonicalName": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } + ], + "TotalCount": 0 +} +``` +::: + +## Get a list of Spaces + +:endpoint{method="GET" path="/api/spaces"} + +Lists all of the Spaces in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name. + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + Comma separated list of Ids. +- **`name`** :span[string]{.type-label} + The exact name of a Space to be matched. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested list of Spaces + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`ExtensionSettings`** :span[array of object]{.type-label} + - **`Icon`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDefault`** :span[boolean]{.type-label} + - **`IsPrivate`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceManagersTeamMembers`** :span[array of string]{.type-label} + - **`SpaceManagersTeams`** :span[array of string]{.type-label} + - **`TaskQueueStopped`** :span[boolean]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Description": "string", + "ExtensionSettings": [ + {} + ], + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsDefault": true, + "IsPrivate": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SpaceManagersTeamMembers": [ + "string" + ], + "SpaceManagersTeams": [ + "string" + ], + "TaskQueueStopped": true + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new Space + +:endpoint{method="POST" path="/api/spaces"} + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`IsDefault`** :span[boolean]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. Maximum length 50. +- **`Slug`** :span[string]{.type-label} + Maximum length 50. +- **`SpaceManagersTeamMembers`** :span[array of string]{.type-label} *(required)* +- **`SpaceManagersTeams`** :span[array of string]{.type-label} *(required)* +- **`TaskQueueStopped`** :span[boolean]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "IsDefault": true, + "Name": "string", + "Slug": "string", + "SpaceManagersTeamMembers": [ + "string" + ], + "SpaceManagersTeams": [ + "string" + ], + "TaskQueueStopped": true +} +``` +::: + +**Response** + +`201` — Created + +- **`Description`** :span[string]{.type-label} +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`IsPrivate`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceManagersTeamMembers`** :span[array of string]{.type-label} +- **`SpaceManagersTeams`** :span[array of string]{.type-label} +- **`TaskQueueStopped`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsDefault": true, + "IsPrivate": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SpaceManagersTeamMembers": [ + "string" + ], + "SpaceManagersTeams": [ + "string" + ], + "TaskQueueStopped": true +} +``` +::: + +## Get a list of Spaces + +:endpoint{method="GET" path="/api/spaces/all"} + +Lists all Spaces. The results will be sorted alphabetically by name. + +**Query Parameters** + +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a `contains` style match against the supplied name or name-fragment. + +**Response** + +`200` — The requested list of Spaces + +- **`Description`** :span[string]{.type-label} +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`IsPrivate`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceManagersTeamMembers`** :span[array of string]{.type-label} +- **`SpaceManagersTeams`** :span[array of string]{.type-label} +- **`TaskQueueStopped`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Description": "string", + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsDefault": true, + "IsPrivate": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SpaceManagersTeamMembers": [ + "string" + ], + "SpaceManagersTeams": [ + "string" + ], + "TaskQueueStopped": true + } +] +``` +::: + +## Create a new Space + +:endpoint{method="POST" path="/api/spaces/v1"} + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`IsDefault`** :span[boolean]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. Maximum length 50. +- **`Slug`** :span[string]{.type-label} + Maximum length 50. +- **`SpaceManagersTeamMembers`** :span[array of string]{.type-label} *(required)* +- **`SpaceManagersTeams`** :span[array of string]{.type-label} *(required)* +- **`TaskQueueStopped`** :span[boolean]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "IsDefault": true, + "Name": "string", + "Slug": "string", + "SpaceManagersTeamMembers": [ + "string" + ], + "SpaceManagersTeams": [ + "string" + ], + "TaskQueueStopped": true +} +``` +::: + +**Response** + +`201` — Created + +- **`Space`** :span[object]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`ExtensionSettings`** :span[array of object]{.type-label} + - **`Icon`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDefault`** :span[boolean]{.type-label} + - **`IsPrivate`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceManagersTeamMembers`** :span[array of string]{.type-label} + - **`SpaceManagersTeams`** :span[array of string]{.type-label} + - **`TaskQueueStopped`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Space": { + "Description": "string", + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsDefault": true, + "IsPrivate": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SpaceManagersTeamMembers": [ + "string" + ], + "SpaceManagersTeams": [ + "string" + ], + "TaskQueueStopped": true + } +} +``` +::: + +## Get a Space by ID + +:endpoint{method="GET" path="/api/spaces/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Space to load. + +**Response** + +`200` — Returns a space + +- **`Description`** :span[string]{.type-label} +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`IsPrivate`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceManagersTeamMembers`** :span[array of string]{.type-label} +- **`SpaceManagersTeams`** :span[array of string]{.type-label} +- **`TaskQueueStopped`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsDefault": true, + "IsPrivate": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SpaceManagersTeamMembers": [ + "string" + ], + "SpaceManagersTeams": [ + "string" + ], + "TaskQueueStopped": true +} +``` +::: + +## Update a Space + +:endpoint{method="PUT" path="/api/spaces/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* +- **`IsDefault`** :span[boolean]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. Maximum length 50. +- **`Slug`** :span[string]{.type-label} + Maximum length 50. +- **`SpaceManagersTeamMembers`** :span[array of string]{.type-label} *(required)* +- **`SpaceManagersTeams`** :span[array of string]{.type-label} *(required)* +- **`TaskQueueStopped`** :span[boolean]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Id": "string", + "IsDefault": true, + "Name": "string", + "Slug": "string", + "SpaceManagersTeamMembers": [ + "string" + ], + "SpaceManagersTeams": [ + "string" + ], + "TaskQueueStopped": true +} +``` +::: + +**Response** + +`200` — Confirmation that the Space was modified, contains the updated Space + +- **`Description`** :span[string]{.type-label} +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`IsPrivate`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceManagersTeamMembers`** :span[array of string]{.type-label} +- **`SpaceManagersTeams`** :span[array of string]{.type-label} +- **`TaskQueueStopped`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsDefault": true, + "IsPrivate": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SpaceManagersTeamMembers": [ + "string" + ], + "SpaceManagersTeams": [ + "string" + ], + "TaskQueueStopped": true +} +``` +::: + +## Delete an existing Space + +:endpoint{method="DELETE" path="/api/spaces/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Space to be deleted. + +**Response** + +`200` — Success + +## Get the logo for the space with the given space ID + +:endpoint{method="GET" path="/api/spaces/\{id\}/logo"} + +Gets the logo associated with the space. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the space. + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Modify the logo of the space with the given space ID + +:endpoint{method="POST" path="/api/spaces/\{id\}/logo"} + +Modifies the logo associated with the space. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the space. + +**Response** + +`200` — Success + +## Modify the logo of the space with the given space ID + +:endpoint{method="PUT" path="/api/spaces/\{id\}/logo"} + +Modifies the logo associated with the space. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the space. + +**Response** + +`200` — Success + +## Search in the supplied Octopus Deploy Space using the given keyword + +:endpoint{method="GET" path="/api/\{spaceId\}/spaces/\{id\}/search"} + +Also reachable at `/api/spaces/{id}/search`, `/api/spaces/{spaceIdentifier}/spaces/{id}/search`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Space to search. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`keyword`** :span[string]{.type-label} *(required)* + A keyword to search. Example: ABC. + +**Response** + +`200` — The requested Space Search Results + +- **`Id`** :span[string]{.type-label} + Minimum length 1. +- **`Name`** :span[string]{.type-label} + Minimum length 1. +- **`Owner`** :span[object]{.type-label} + - **`Name`** :span[string]{.type-label} + Minimum length 1. + - **`Type`** :span[string]{.type-label} + Minimum length 1. +- **`Type`** :span[string]{.type-label} + Minimum length 1. + +:::api-example{label="Response"} +```json +[ + { + "Id": "string", + "Name": "string", + "Owner": { + "Name": "string", + "Type": "string" + }, + "Type": "string" + } +] +``` +::: + +## Delete an existing Space + +:endpoint{method="DELETE" path="/api/spaces/\{id\}/v1"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Space to be deleted. + +**Response** + +`200` — Empty response indicating the Space was deleted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get a list of spaces available to the current authenticated user only + +:endpoint{method="GET" path="/api/users/\{id\}/spaces"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the user whose spaces we are looking up. + +**Response** + +`200` — The requested list of Spaces available to the user + +- **`Description`** :span[string]{.type-label} +- **`ExtensionSettings`** :span[array of object]{.type-label} + - **`ExtensionId`** :span[string]{.type-label} + - **`Values`** :span[string]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} +- **`IsPrivate`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceManagersTeamMembers`** :span[array of string]{.type-label} +- **`SpaceManagersTeams`** :span[array of string]{.type-label} +- **`TaskQueueStopped`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Description": "string", + "ExtensionSettings": [ + { + "ExtensionId": "string", + "Values": "string" + } + ], + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsDefault": true, + "IsPrivate": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SpaceManagersTeamMembers": [ + "string" + ], + "SpaceManagersTeams": [ + "string" + ], + "TaskQueueStopped": true + } +] +``` +::: diff --git a/src/pages/docs/api/ssh-known-hosts.md b/src/pages/docs/api/ssh-known-hosts.md new file mode 100644 index 0000000000..6ce42e0329 --- /dev/null +++ b/src/pages/docs/api/ssh-known-hosts.md @@ -0,0 +1,109 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Ssh Known Hosts +--- + +## Get a list of SSH Known Hosts + +:endpoint{method="GET" path="/api/sshknownhosts"} + +**Query Parameters** + +- **`partialHost`** :span[string]{.type-label} + Filters known hosts matching any part of the `host` fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Contains a list of SSH Known Hosts + +- **`FilteredCount`** :span[integer]{.type-label} +- **`Resources`** :span[array of object]{.type-label} + - **`Host`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`KeyType`** :span[string]{.type-label} + - **`PublicKey`** :span[string]{.type-label} +- **`TotalCount`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "FilteredCount": 0, + "Resources": [ + { + "Host": "string", + "Id": "string", + "KeyType": "string", + "PublicKey": "string" + } + ], + "TotalCount": 0 +} +``` +::: + +## Add new SSH Known Hosts from a list of entries + +:endpoint{method="POST" path="/api/sshknownhosts"} + +**Request Body** + +- **`KnownHostEntries`** :span[array of string]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "KnownHostEntries": [ + "string" + ] +} +``` +::: + +**Response** + +`200` — Contains a list of added SSH Known Hosts + +- **`AddedResources`** :span[array of object]{.type-label} + - **`Host`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`KeyType`** :span[string]{.type-label} + - **`PublicKey`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AddedResources": [ + { + "Host": "string", + "Id": "string", + "KeyType": "string", + "PublicKey": "string" + } + ] +} +``` +::: + +## Delete the specific SSH Known Host + +:endpoint{method="DELETE" path="/api/sshknownhosts/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — An empty response + +:::api-example{label="Response"} +```json +{} +``` +::: diff --git a/src/pages/docs/api/subscriptions.md b/src/pages/docs/api/subscriptions.md new file mode 100644 index 0000000000..1f0eb560d3 --- /dev/null +++ b/src/pages/docs/api/subscriptions.md @@ -0,0 +1,964 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Subscriptions +--- + +## Get a list of Subscriptions + +:endpoint{method="GET" path="/api/\{spaceId\}/subscriptions"} + +Also reachable at `/api/spaces/{spaceIdentifier}/subscriptions`, `/api/subscriptions`. + +Lists all of the Subscriptions in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested Subscriptions + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`EventNotificationSubscription`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`Type`** :span[enum]{.type-label} + Allowed values: `Event`. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "EventNotificationSubscription": { + "EmailDigestLastProcessed": "2020-01-01T00:00:00.000Z", + "EmailDigestLastProcessedEventAutoId": 0, + "EmailFrequencyPeriod": "string", + "EmailPriority": "Normal", + "EmailShowDatesInTimeZoneId": "string", + "EmailTeams": [ + "string" + ], + "Filter": {}, + "SlackChannelIds": [ + "string" + ], + "SlackChannelNames": [ + "string" + ], + "SlackDigestLastProcessed": "2020-01-01T00:00:00.000Z", + "SlackDigestLastProcessedEventAutoId": 0, + "SlackFrequencyPeriod": "string", + "WebhookHeaderKey": "string", + "WebhookHeaderValue": {}, + "WebhookLastProcessed": "2020-01-01T00:00:00.000Z", + "WebhookLastProcessedEventAutoId": 0, + "WebhookTeams": [ + "string" + ], + "WebhookTimeout": "string", + "WebhookURI": "https://example.com" + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpaceId": "string", + "Type": "Event" + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new Subscription + +:endpoint{method="POST" path="/api/\{spaceId\}/subscriptions"} + +Also reachable at `/api/spaces/{spaceIdentifier}/subscriptions`, `/api/subscriptions`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. + +**Request Body** + +- **`EventNotificationSubscription`** :span[object]{.type-label} *(required)* + - **`EmailDigestLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`EmailDigestLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`EmailFrequencyPeriod`** :span[string]{.type-label} + Format `date-span`. + - **`EmailPriority`** :span[enum]{.type-label} + Allowed values: `Normal`, `Low`, `High`. + - **`EmailShowDatesInTimeZoneId`** :span[string]{.type-label} + - **`EmailTeams`** :span[array of string]{.type-label} + - **`Filter`** :span[object]{.type-label} + - **`SlackChannelIds`** :span[array of string]{.type-label} + - **`SlackChannelNames`** :span[array of string]{.type-label} + - **`SlackDigestLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`SlackDigestLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`SlackFrequencyPeriod`** :span[string]{.type-label} + Format `date-span`. + - **`WebhookHeaderKey`** :span[string]{.type-label} + - **`WebhookHeaderValue`** :span[object]{.type-label} + - **`WebhookLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`WebhookLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`WebhookTeams`** :span[array of string]{.type-label} + - **`WebhookTimeout`** :span[string]{.type-label} + Format `date-span`. + - **`WebhookURI`** :span[string]{.type-label} + Use a backing field here, so we can ignore empty strings, which the portal sends us. Format `uri`. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. + +:::api-example{label="Request"} +```json +{ + "EventNotificationSubscription": { + "EmailDigestLastProcessed": "2020-01-01T00:00:00.000Z", + "EmailDigestLastProcessedEventAutoId": 0, + "EmailFrequencyPeriod": "string", + "EmailPriority": "Normal", + "EmailShowDatesInTimeZoneId": "string", + "EmailTeams": [ + "string" + ], + "Filter": { + "DocumentTypes": [ + "string" + ], + "Environments": [ + "string" + ], + "EventAgents": [ + "string" + ], + "EventCategories": [ + "string" + ], + "EventGroups": [ + "string" + ], + "ProjectGroups": [ + "string" + ], + "Projects": [ + "string" + ], + "Tags": [ + "string" + ], + "Tenants": [ + "string" + ], + "Users": [ + "string" + ] + }, + "SlackChannelIds": [ + "string" + ], + "SlackChannelNames": [ + "string" + ], + "SlackDigestLastProcessed": "2020-01-01T00:00:00.000Z", + "SlackDigestLastProcessedEventAutoId": 0, + "SlackFrequencyPeriod": "string", + "WebhookHeaderKey": "string", + "WebhookHeaderValue": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "WebhookLastProcessed": "2020-01-01T00:00:00.000Z", + "WebhookLastProcessedEventAutoId": 0, + "WebhookTeams": [ + "string" + ], + "WebhookTimeout": "string", + "WebhookURI": "https://example.com" + }, + "IsDisabled": true, + "Name": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`EventNotificationSubscription`** :span[object]{.type-label} + - **`EmailDigestLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`EmailDigestLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`EmailFrequencyPeriod`** :span[string]{.type-label} + Format `date-span`. + - **`EmailPriority`** :span[enum]{.type-label} + Allowed values: `Normal`, `Low`, `High`. + - **`EmailShowDatesInTimeZoneId`** :span[string]{.type-label} + - **`EmailTeams`** :span[array of string]{.type-label} + - **`Filter`** :span[object]{.type-label} + - **`SlackChannelIds`** :span[array of string]{.type-label} + - **`SlackChannelNames`** :span[array of string]{.type-label} + - **`SlackDigestLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`SlackDigestLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`SlackFrequencyPeriod`** :span[string]{.type-label} + Format `date-span`. + - **`WebhookHeaderKey`** :span[string]{.type-label} + - **`WebhookHeaderValue`** :span[object]{.type-label} + - **`WebhookLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`WebhookLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`WebhookTeams`** :span[array of string]{.type-label} + - **`WebhookTimeout`** :span[string]{.type-label} + Format `date-span`. + - **`WebhookURI`** :span[string]{.type-label} + Use a backing field here, so we can ignore empty strings, which the portal sends us. Format `uri`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Type`** :span[enum]{.type-label} + Allowed values: `Event`. + +:::api-example{label="Response"} +```json +{ + "EventNotificationSubscription": { + "EmailDigestLastProcessed": "2020-01-01T00:00:00.000Z", + "EmailDigestLastProcessedEventAutoId": 0, + "EmailFrequencyPeriod": "string", + "EmailPriority": "Normal", + "EmailShowDatesInTimeZoneId": "string", + "EmailTeams": [ + "string" + ], + "Filter": { + "DocumentTypes": [ + "string" + ], + "Environments": [ + "string" + ], + "EventAgents": [ + "string" + ], + "EventCategories": [ + "string" + ], + "EventGroups": [ + "string" + ], + "ProjectGroups": [ + "string" + ], + "Projects": [ + "string" + ], + "Tags": [ + "string" + ], + "Tenants": [ + "string" + ], + "Users": [ + "string" + ] + }, + "SlackChannelIds": [ + "string" + ], + "SlackChannelNames": [ + "string" + ], + "SlackDigestLastProcessed": "2020-01-01T00:00:00.000Z", + "SlackDigestLastProcessedEventAutoId": 0, + "SlackFrequencyPeriod": "string", + "WebhookHeaderKey": "string", + "WebhookHeaderValue": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "WebhookLastProcessed": "2020-01-01T00:00:00.000Z", + "WebhookLastProcessedEventAutoId": 0, + "WebhookTeams": [ + "string" + ], + "WebhookTimeout": "string", + "WebhookURI": "https://example.com" + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpaceId": "string", + "Type": "Event" +} +``` +::: + +## Get all Subscriptions + +:endpoint{method="GET" path="/api/\{spaceId\}/subscriptions/all"} + +Also reachable at `/api/spaces/{spaceIdentifier}/subscriptions/all`, `/api/subscriptions/all`. + +Lists all the Subscriptions in the supplied Octopus Deploy Space + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. + +**Response** + +`200` — All Subscriptions from the requested Space + +- **`EventNotificationSubscription`** :span[object]{.type-label} + - **`EmailDigestLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`EmailDigestLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`EmailFrequencyPeriod`** :span[string]{.type-label} + Format `date-span`. + - **`EmailPriority`** :span[enum]{.type-label} + Allowed values: `Normal`, `Low`, `High`. + - **`EmailShowDatesInTimeZoneId`** :span[string]{.type-label} + - **`EmailTeams`** :span[array of string]{.type-label} + - **`Filter`** :span[object]{.type-label} + - **`SlackChannelIds`** :span[array of string]{.type-label} + - **`SlackChannelNames`** :span[array of string]{.type-label} + - **`SlackDigestLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`SlackDigestLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`SlackFrequencyPeriod`** :span[string]{.type-label} + Format `date-span`. + - **`WebhookHeaderKey`** :span[string]{.type-label} + - **`WebhookHeaderValue`** :span[object]{.type-label} + - **`WebhookLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`WebhookLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`WebhookTeams`** :span[array of string]{.type-label} + - **`WebhookTimeout`** :span[string]{.type-label} + Format `date-span`. + - **`WebhookURI`** :span[string]{.type-label} + Use a backing field here, so we can ignore empty strings, which the portal sends us. Format `uri`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Type`** :span[enum]{.type-label} + Allowed values: `Event`. + +:::api-example{label="Response"} +```json +[ + { + "EventNotificationSubscription": { + "EmailDigestLastProcessed": "2020-01-01T00:00:00.000Z", + "EmailDigestLastProcessedEventAutoId": 0, + "EmailFrequencyPeriod": "string", + "EmailPriority": "Normal", + "EmailShowDatesInTimeZoneId": "string", + "EmailTeams": [ + "string" + ], + "Filter": { + "DocumentTypes": [ + "string" + ], + "Environments": [ + "string" + ], + "EventAgents": [ + "string" + ], + "EventCategories": [ + "string" + ], + "EventGroups": [ + "string" + ], + "ProjectGroups": [ + "string" + ], + "Projects": [ + "string" + ], + "Tags": [ + "string" + ], + "Tenants": [ + "string" + ], + "Users": [ + "string" + ] + }, + "SlackChannelIds": [ + "string" + ], + "SlackChannelNames": [ + "string" + ], + "SlackDigestLastProcessed": "2020-01-01T00:00:00.000Z", + "SlackDigestLastProcessedEventAutoId": 0, + "SlackFrequencyPeriod": "string", + "WebhookHeaderKey": "string", + "WebhookHeaderValue": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + }, + "WebhookLastProcessed": "2020-01-01T00:00:00.000Z", + "WebhookLastProcessedEventAutoId": 0, + "WebhookTeams": [ + "string" + ], + "WebhookTimeout": "string", + "WebhookURI": "https://example.com" + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpaceId": "string", + "Type": "Event" + } +] +``` +::: + +## Get a Subscription by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/subscriptions/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/subscriptions/{id}`, `/api/subscriptions/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Subscription to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. + +**Response** + +`200` — The requested Subscription + +- **`EventNotificationSubscription`** :span[object]{.type-label} + - **`EmailDigestLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`EmailDigestLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`EmailFrequencyPeriod`** :span[string]{.type-label} + Format `date-span`. + - **`EmailPriority`** :span[enum]{.type-label} + Allowed values: `Normal`, `Low`, `High`. + - **`EmailShowDatesInTimeZoneId`** :span[string]{.type-label} + - **`EmailTeams`** :span[array of string]{.type-label} + - **`Filter`** :span[object]{.type-label} + - **`SlackChannelIds`** :span[array of string]{.type-label} + - **`SlackChannelNames`** :span[array of string]{.type-label} + - **`SlackDigestLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`SlackDigestLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`SlackFrequencyPeriod`** :span[string]{.type-label} + Format `date-span`. + - **`WebhookHeaderKey`** :span[string]{.type-label} + - **`WebhookHeaderValue`** :span[object]{.type-label} + - **`WebhookLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`WebhookLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`WebhookTeams`** :span[array of string]{.type-label} + - **`WebhookTimeout`** :span[string]{.type-label} + Format `date-span`. + - **`WebhookURI`** :span[string]{.type-label} + Use a backing field here, so we can ignore empty strings, which the portal sends us. Format `uri`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Type`** :span[enum]{.type-label} + Allowed values: `Event`. + +:::api-example{label="Response"} +```json +{ + "EventNotificationSubscription": { + "EmailDigestLastProcessed": "2020-01-01T00:00:00.000Z", + "EmailDigestLastProcessedEventAutoId": 0, + "EmailFrequencyPeriod": "string", + "EmailPriority": "Normal", + "EmailShowDatesInTimeZoneId": "string", + "EmailTeams": [ + "string" + ], + "Filter": { + "DocumentTypes": [ + "string" + ], + "Environments": [ + "string" + ], + "EventAgents": [ + "string" + ], + "EventCategories": [ + "string" + ], + "EventGroups": [ + "string" + ], + "ProjectGroups": [ + "string" + ], + "Projects": [ + "string" + ], + "Tags": [ + "string" + ], + "Tenants": [ + "string" + ], + "Users": [ + "string" + ] + }, + "SlackChannelIds": [ + "string" + ], + "SlackChannelNames": [ + "string" + ], + "SlackDigestLastProcessed": "2020-01-01T00:00:00.000Z", + "SlackDigestLastProcessedEventAutoId": 0, + "SlackFrequencyPeriod": "string", + "WebhookHeaderKey": "string", + "WebhookHeaderValue": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "WebhookLastProcessed": "2020-01-01T00:00:00.000Z", + "WebhookLastProcessedEventAutoId": 0, + "WebhookTeams": [ + "string" + ], + "WebhookTimeout": "string", + "WebhookURI": "https://example.com" + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpaceId": "string", + "Type": "Event" +} +``` +::: + +## Update an existing Subscription + +:endpoint{method="PUT" path="/api/\{spaceId\}/subscriptions/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/subscriptions/{id}`, `/api/subscriptions/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Subscription to modify. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. + +**Request Body** + +- **`EventNotificationSubscription`** :span[object]{.type-label} *(required)* + - **`EmailDigestLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`EmailDigestLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`EmailFrequencyPeriod`** :span[string]{.type-label} + Format `date-span`. + - **`EmailPriority`** :span[enum]{.type-label} + Allowed values: `Normal`, `Low`, `High`. + - **`EmailShowDatesInTimeZoneId`** :span[string]{.type-label} + - **`EmailTeams`** :span[array of string]{.type-label} + - **`Filter`** :span[object]{.type-label} + - **`SlackChannelIds`** :span[array of string]{.type-label} + - **`SlackChannelNames`** :span[array of string]{.type-label} + - **`SlackDigestLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`SlackDigestLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`SlackFrequencyPeriod`** :span[string]{.type-label} + Format `date-span`. + - **`WebhookHeaderKey`** :span[string]{.type-label} + - **`WebhookHeaderValue`** :span[object]{.type-label} + - **`WebhookLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`WebhookLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`WebhookTeams`** :span[array of string]{.type-label} + - **`WebhookTimeout`** :span[string]{.type-label} + Format `date-span`. + - **`WebhookURI`** :span[string]{.type-label} + Use a backing field here, so we can ignore empty strings, which the portal sends us. Format `uri`. +- **`Id`** :span[string]{.type-label} *(required)* + ID of the Subscription to modify. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. +- **`Type`** :span[enum]{.type-label} + Allowed values: `Event`. + +:::api-example{label="Request"} +```json +{ + "EventNotificationSubscription": { + "EmailDigestLastProcessed": "2020-01-01T00:00:00.000Z", + "EmailDigestLastProcessedEventAutoId": 0, + "EmailFrequencyPeriod": "string", + "EmailPriority": "Normal", + "EmailShowDatesInTimeZoneId": "string", + "EmailTeams": [ + "string" + ], + "Filter": { + "DocumentTypes": [ + "string" + ], + "Environments": [ + "string" + ], + "EventAgents": [ + "string" + ], + "EventCategories": [ + "string" + ], + "EventGroups": [ + "string" + ], + "ProjectGroups": [ + "string" + ], + "Projects": [ + "string" + ], + "Tags": [ + "string" + ], + "Tenants": [ + "string" + ], + "Users": [ + "string" + ] + }, + "SlackChannelIds": [ + "string" + ], + "SlackChannelNames": [ + "string" + ], + "SlackDigestLastProcessed": "2020-01-01T00:00:00.000Z", + "SlackDigestLastProcessedEventAutoId": 0, + "SlackFrequencyPeriod": "string", + "WebhookHeaderKey": "string", + "WebhookHeaderValue": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "WebhookLastProcessed": "2020-01-01T00:00:00.000Z", + "WebhookLastProcessedEventAutoId": 0, + "WebhookTeams": [ + "string" + ], + "WebhookTimeout": "string", + "WebhookURI": "https://example.com" + }, + "Id": "string", + "IsDisabled": true, + "Name": "string", + "SpaceId": "string", + "Type": "Event" +} +``` +::: + +**Response** + +`200` — The updated Subscription + +- **`EventNotificationSubscription`** :span[object]{.type-label} + - **`EmailDigestLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`EmailDigestLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`EmailFrequencyPeriod`** :span[string]{.type-label} + Format `date-span`. + - **`EmailPriority`** :span[enum]{.type-label} + Allowed values: `Normal`, `Low`, `High`. + - **`EmailShowDatesInTimeZoneId`** :span[string]{.type-label} + - **`EmailTeams`** :span[array of string]{.type-label} + - **`Filter`** :span[object]{.type-label} + - **`SlackChannelIds`** :span[array of string]{.type-label} + - **`SlackChannelNames`** :span[array of string]{.type-label} + - **`SlackDigestLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`SlackDigestLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`SlackFrequencyPeriod`** :span[string]{.type-label} + Format `date-span`. + - **`WebhookHeaderKey`** :span[string]{.type-label} + - **`WebhookHeaderValue`** :span[object]{.type-label} + - **`WebhookLastProcessed`** :span[string]{.type-label} + Format `date-time`. + - **`WebhookLastProcessedEventAutoId`** :span[integer]{.type-label} + - **`WebhookTeams`** :span[array of string]{.type-label} + - **`WebhookTimeout`** :span[string]{.type-label} + Format `date-span`. + - **`WebhookURI`** :span[string]{.type-label} + Use a backing field here, so we can ignore empty strings, which the portal sends us. Format `uri`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Type`** :span[enum]{.type-label} + Allowed values: `Event`. + +:::api-example{label="Response"} +```json +{ + "EventNotificationSubscription": { + "EmailDigestLastProcessed": "2020-01-01T00:00:00.000Z", + "EmailDigestLastProcessedEventAutoId": 0, + "EmailFrequencyPeriod": "string", + "EmailPriority": "Normal", + "EmailShowDatesInTimeZoneId": "string", + "EmailTeams": [ + "string" + ], + "Filter": { + "DocumentTypes": [ + "string" + ], + "Environments": [ + "string" + ], + "EventAgents": [ + "string" + ], + "EventCategories": [ + "string" + ], + "EventGroups": [ + "string" + ], + "ProjectGroups": [ + "string" + ], + "Projects": [ + "string" + ], + "Tags": [ + "string" + ], + "Tenants": [ + "string" + ], + "Users": [ + "string" + ] + }, + "SlackChannelIds": [ + "string" + ], + "SlackChannelNames": [ + "string" + ], + "SlackDigestLastProcessed": "2020-01-01T00:00:00.000Z", + "SlackDigestLastProcessedEventAutoId": 0, + "SlackFrequencyPeriod": "string", + "WebhookHeaderKey": "string", + "WebhookHeaderValue": { + "IsSensitive": true, + "SensitiveValue": { + "HasValue": true, + "Hint": "string", + "NewValue": "string" + }, + "Value": "string" + }, + "WebhookLastProcessed": "2020-01-01T00:00:00.000Z", + "WebhookLastProcessedEventAutoId": 0, + "WebhookTeams": [ + "string" + ], + "WebhookTimeout": "string", + "WebhookURI": "https://example.com" + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpaceId": "string", + "Type": "Event" +} +``` +::: + +## Delete an existing Subscription + +:endpoint{method="DELETE" path="/api/\{spaceId\}/subscriptions/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/subscriptions/{id}`, `/api/subscriptions/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Subscription to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource. + +**Response** + +`200` — Confirmation that the Subscription was deleted + +:::api-example{label="Response"} +```json +{} +``` +::: diff --git a/src/pages/docs/api/tag-sets.md b/src/pages/docs/api/tag-sets.md new file mode 100644 index 0000000000..571b4a8b37 --- /dev/null +++ b/src/pages/docs/api/tag-sets.md @@ -0,0 +1,610 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Tag Sets +--- + +## Get a list of Tag Sets + +:endpoint{method="GET" path="/api/\{spaceId\}/tagsets"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tagsets`, `/api/tagsets`. + +Lists all of the Tag Sets in the supplied Octopus Deploy Space. The results will be sorted alphabetically by the `SortOrder` field on each tag set. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + Comma separated list of Ids. +- **`name`** :span[string]{.type-label} + The exact name of a Tag Set to be matched. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a \"contains\" style match against the supplied name or name-fragment. +- **`scopes`** :span[array of string]{.type-label} + Limits results to tag sets that apply to any of these resource types. Valid values: 'Tenant', 'Environment', 'Project', 'Target', 'Runbook', 'Feature Toggle'. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`types`** :span[array of string]{.type-label} + Limits results to tag sets of these types. Valid values: 'SingleSelect', 'MultiSelect', 'FreeText'. + +**Response** + +`200` — The list of matching Tag Sets, sorted alphabetically by the `SortOrder` field on each tag set. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Description`** :span[string]{.type-label} + Gets or sets the description of this tag set. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsSystem`** :span[boolean]{.type-label} + Whether this tag set is a system-managed tag set. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this tag set. Minimum length 1. + - **`Scopes`** :span[array of string]{.type-label} + The resource types this tag set applies to. + - **`SortOrder`** :span[integer]{.type-label} + Gets or sets the sort order of this tag set. + - **`SpaceId`** :span[string]{.type-label} + - **`Tags`** :span[array of object]{.type-label} + The tags that make up this tag set. + - **`Type`** :span[string]{.type-label} + The type of this tag set. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Description": "string", + "Id": "string", + "IsSystem": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Scopes": [ + "string" + ], + "SortOrder": 0, + "SpaceId": "string", + "Tags": [ + {} + ], + "Type": "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 +} +``` +::: + +## Create a new Tag Set + +:endpoint{method="POST" path="/api/\{spaceId\}/tagsets"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tagsets`, `/api/tagsets`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Description`** :span[string]{.type-label} + Sets the description of this tag set. +- **`Name`** :span[string]{.type-label} *(required)* + Sets the name of this tag set. Minimum length 1. +- **`Scopes`** :span[array of string]{.type-label} + The resource types the tag set applies to. Valid values: 'Tenant', 'Environment', 'Project', 'Target', 'Runbook', 'Feature Toggle'. Defaults to ['Tenant'] when omitted. +- **`SortOrder`** :span[integer]{.type-label} + Sets the sort order of this tag set. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`Tags`** :span[array of object]{.type-label} + The tags that make up the tag set. Each tag is an object with a 'Name', an optional 'Description', a 'Color' hex code (e.g. '#3156B3'), and a 'SortOrder'. Leave empty for a 'FreeText' tag set, which does not allow predefined tags. + - **`CanonicalTagName`** :span[string]{.type-label} + This is the canonical name for the Tag formed as {TagSetName}/{TagName} which is easier to work with than the ID in certain scenarios. + - **`Color`** :span[string]{.type-label} + Gets or sets the color of this tag. + - **`Description`** :span[string]{.type-label} + Gets or sets the description of this tag. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this tag. + - **`SortOrder`** :span[integer]{.type-label} +- **`Type`** :span[string]{.type-label} + How tags from the set are applied to a resource: 'MultiSelect' (any number of tags), 'SingleSelect' (one tag at a time), or 'FreeText' (arbitrary values, no predefined tags). Defaults to 'MultiSelect' when omitted. + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Name": "string", + "Scopes": [ + "string" + ], + "SortOrder": 0, + "SpaceId": "string", + "Tags": [ + { + "CanonicalTagName": "string", + "Color": "string", + "Description": "string", + "Id": "string", + "Name": "string", + "SortOrder": 0 + } + ], + "Type": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`Description`** :span[string]{.type-label} + Gets or sets the description of this tag set. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsSystem`** :span[boolean]{.type-label} + Whether this tag set is a system-managed tag set. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this tag set. Minimum length 1. +- **`Scopes`** :span[array of string]{.type-label} + The resource types this tag set applies to. +- **`SortOrder`** :span[integer]{.type-label} + Gets or sets the sort order of this tag set. +- **`SpaceId`** :span[string]{.type-label} +- **`Tags`** :span[array of object]{.type-label} + The tags that make up this tag set. + - **`CanonicalTagName`** :span[string]{.type-label} + This is the canonical name for the Tag formed as {TagSetName}/{TagName} which is easier to work with than the ID in certain scenarios. + - **`Color`** :span[string]{.type-label} + Gets or sets the color of this tag. + - **`Description`** :span[string]{.type-label} + Gets or sets the description of this tag. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this tag. + - **`SortOrder`** :span[integer]{.type-label} +- **`Type`** :span[string]{.type-label} + The type of this tag set. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Id": "string", + "IsSystem": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Scopes": [ + "string" + ], + "SortOrder": 0, + "SpaceId": "string", + "Tags": [ + { + "CanonicalTagName": "string", + "Color": "string", + "Description": "string", + "Id": "string", + "Name": "string", + "SortOrder": 0 + } + ], + "Type": "string" +} +``` +::: + +## Get a list of Tag Sets + +:endpoint{method="GET" path="/api/\{spaceId\}/tagsets/all"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tagsets/all`, `/api/tagsets/all`. + +Lists the details of all of the Tag Sets in the supplied Octopus Deploy Space. The results will be sorted by the `SortOrder` field on each Tag Set. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`scopes`** :span[array of string]{.type-label} + +**Response** + +`200` — List of Tag Sets, sorted by the `SortOrder` field on each Tag Set. + +- **`Description`** :span[string]{.type-label} + Gets or sets the description of this tag set. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsSystem`** :span[boolean]{.type-label} + Whether this tag set is a system-managed tag set. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this tag set. Minimum length 1. +- **`Scopes`** :span[array of string]{.type-label} + The resource types this tag set applies to. +- **`SortOrder`** :span[integer]{.type-label} + Gets or sets the sort order of this tag set. +- **`SpaceId`** :span[string]{.type-label} +- **`Tags`** :span[array of object]{.type-label} + The tags that make up this tag set. + - **`CanonicalTagName`** :span[string]{.type-label} + This is the canonical name for the Tag formed as {TagSetName}/{TagName} which is easier to work with than the ID in certain scenarios. + - **`Color`** :span[string]{.type-label} + Gets or sets the color of this tag. + - **`Description`** :span[string]{.type-label} + Gets or sets the description of this tag. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this tag. + - **`SortOrder`** :span[integer]{.type-label} +- **`Type`** :span[string]{.type-label} + The type of this tag set. + +:::api-example{label="Response"} +```json +[ + { + "Description": "string", + "Id": "string", + "IsSystem": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Scopes": [ + "string" + ], + "SortOrder": 0, + "SpaceId": "string", + "Tags": [ + { + "CanonicalTagName": "string", + "Color": "string", + "Description": "string", + "Id": "string", + "Name": "string", + "SortOrder": 0 + } + ], + "Type": "string" + } +] +``` +::: + +## PUT /api/{spaceId}/tagsets/sortorder + +:endpoint{method="PUT" path="/api/\{spaceId\}/tagsets/sortorder"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tagsets/sortorder`, `/api/tagsets/sortorder`. + +Takes an array of tag set IDs as the request body, uses the order of items in the array to sort the tag sets on the server. The ID of every tag set must be specified. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +A `array of string` payload. + +:::api-example{label="Request"} +```json +[ + "string" +] +``` +::: + +**Response** + +`200` — Success + +## Get a Tag Set by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/tagsets/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tagsets/{id}`, `/api/tagsets/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Tag Set to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested Tag Set + +- **`Description`** :span[string]{.type-label} + Gets or sets the description of this tag set. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsSystem`** :span[boolean]{.type-label} + Whether this tag set is a system-managed tag set. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this tag set. Minimum length 1. +- **`Scopes`** :span[array of string]{.type-label} + The resource types this tag set applies to. +- **`SortOrder`** :span[integer]{.type-label} + Gets or sets the sort order of this tag set. +- **`SpaceId`** :span[string]{.type-label} +- **`Tags`** :span[array of object]{.type-label} + The tags that make up this tag set. + - **`CanonicalTagName`** :span[string]{.type-label} + This is the canonical name for the Tag formed as {TagSetName}/{TagName} which is easier to work with than the ID in certain scenarios. + - **`Color`** :span[string]{.type-label} + Gets or sets the color of this tag. + - **`Description`** :span[string]{.type-label} + Gets or sets the description of this tag. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this tag. + - **`SortOrder`** :span[integer]{.type-label} +- **`Type`** :span[string]{.type-label} + The type of this tag set. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Id": "string", + "IsSystem": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Scopes": [ + "string" + ], + "SortOrder": 0, + "SpaceId": "string", + "Tags": [ + { + "CanonicalTagName": "string", + "Color": "string", + "Description": "string", + "Id": "string", + "Name": "string", + "SortOrder": 0 + } + ], + "Type": "string" +} +``` +::: + +## Modify an existing Tag Set + +:endpoint{method="PUT" path="/api/\{spaceId\}/tagsets/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tagsets/{id}`, `/api/tagsets/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Tag Set to modify. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Description`** :span[string]{.type-label} + Sets the description of this tag set. +- **`Id`** :span[string]{.type-label} *(required)* + ID of the Tag Set to modify. +- **`Name`** :span[string]{.type-label} *(required)* + Sets the name of this tag set. Minimum length 1. +- **`Scopes`** :span[array of string]{.type-label} + The complete set of resource types the tag set applies to; a scope omitted here is removed (rejected if tags are in use for it). Valid values: 'Tenant', 'Environment', 'Project', 'Target', 'Runbook', 'Feature Toggle'. Defaults to ['Tenant'] when omitted. +- **`SortOrder`** :span[integer]{.type-label} + Sets the sort order of this tag set. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`Tags`** :span[array of object]{.type-label} + The complete list of tags for the tag set; existing tags omitted here are deleted (rejected if still in use). Each tag is an object with a 'Name', an optional 'Description', a 'Color' hex code (e.g. '#3156B3'), a 'SortOrder', and — for existing tags — the 'Id' from get_tag_set, which must be kept to update or rename a tag rather than replace it. + - **`CanonicalTagName`** :span[string]{.type-label} + This is the canonical name for the Tag formed as {TagSetName}/{TagName} which is easier to work with than the ID in certain scenarios. + - **`Color`** :span[string]{.type-label} + Gets or sets the color of this tag. + - **`Description`** :span[string]{.type-label} + Gets or sets the description of this tag. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this tag. + - **`SortOrder`** :span[integer]{.type-label} +- **`Type`** :span[string]{.type-label} + How tags from the set are applied to a resource: 'MultiSelect' (any number of tags), 'SingleSelect' (one tag at a time), or 'FreeText' (arbitrary values, no predefined tags). Defaults to 'MultiSelect' when omitted; a tag set in use can only change from SingleSelect to MultiSelect. + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Id": "string", + "Name": "string", + "Scopes": [ + "string" + ], + "SortOrder": 0, + "SpaceId": "string", + "Tags": [ + { + "CanonicalTagName": "string", + "Color": "string", + "Description": "string", + "Id": "string", + "Name": "string", + "SortOrder": 0 + } + ], + "Type": "string" +} +``` +::: + +**Response** + +`200` — Confirms that a Tag Set has been modified, containing the updated Tag Set + +- **`Description`** :span[string]{.type-label} + Gets or sets the description of this tag set. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsSystem`** :span[boolean]{.type-label} + Whether this tag set is a system-managed tag set. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this tag set. Minimum length 1. +- **`Scopes`** :span[array of string]{.type-label} + The resource types this tag set applies to. +- **`SortOrder`** :span[integer]{.type-label} + Gets or sets the sort order of this tag set. +- **`SpaceId`** :span[string]{.type-label} +- **`Tags`** :span[array of object]{.type-label} + The tags that make up this tag set. + - **`CanonicalTagName`** :span[string]{.type-label} + This is the canonical name for the Tag formed as {TagSetName}/{TagName} which is easier to work with than the ID in certain scenarios. + - **`Color`** :span[string]{.type-label} + Gets or sets the color of this tag. + - **`Description`** :span[string]{.type-label} + Gets or sets the description of this tag. + - **`Id`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this tag. + - **`SortOrder`** :span[integer]{.type-label} +- **`Type`** :span[string]{.type-label} + The type of this tag set. + +:::api-example{label="Response"} +```json +{ + "Description": "string", + "Id": "string", + "IsSystem": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Scopes": [ + "string" + ], + "SortOrder": 0, + "SpaceId": "string", + "Tags": [ + { + "CanonicalTagName": "string", + "Color": "string", + "Description": "string", + "Id": "string", + "Name": "string", + "SortOrder": 0 + } + ], + "Type": "string" +} +``` +::: + +## Delete an existing Tag Set + +:endpoint{method="DELETE" path="/api/\{spaceId\}/tagsets/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tagsets/{id}`, `/api/tagsets/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Tag Set to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success diff --git a/src/pages/docs/api/tasks.md b/src/pages/docs/api/tasks.md new file mode 100644 index 0000000000..6cb7ea7c16 --- /dev/null +++ b/src/pages/docs/api/tasks.md @@ -0,0 +1,1353 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Tasks +--- + +## List all of the tasks in the supplied Octopus Deploy Space. The results will be sorted from newest to oldest + +:endpoint{method="GET" path="/api/\{spaceId\}/tasks"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tasks`, `/api/tasks`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`active`** :span[boolean]{.type-label} + Set to true for tasks that have not finished (New, Queued, Executing or Cancelling), or false for tasks that have. +- **`batch`** :span[string]{.type-label} +- **`description`** :span[string]{.type-label} + Text to match within a task's description, such as a project or release name. This is a partial match, not an exact one. +- **`environment`** :span[string]{.type-label} + The ID of an environment, to return only tasks against that environment. This is an ID such as 'Environments-1', not an environment name. +- **`fromCompletedDate`** :span[string]{.type-label} + Format `date-time`. +- **`fromQueueDate`** :span[string]{.type-label} + Format `date-time`. +- **`fromStartDate`** :span[string]{.type-label} + Format `date-time`. +- **`hasPendingInterruptions`** :span[boolean]{.type-label} +- **`hasPendingPreconditions`** :span[boolean]{.type-label} +- **`hasWarningsOrErrors`** :span[boolean]{.type-label} +- **`ids`** :span[array of string]{.type-label} + Task IDs to return, such as 'ServerTasks-1'. +- **`name`** :span[array of string]{.type-label} + Task type names to match exactly, such as 'Deploy' or 'RunbookRun'. Use ListServerTaskTypes to get the supported values. +- **`node`** :span[string]{.type-label} + The ID of the Octopus Server node a task ran on, to return only tasks from that node. +- **`partialName`** :span[string]{.type-label} + A partial task type name, to match tasks whose type name includes it. +- **`project`** :span[string]{.type-label} + The ID of a project, to return only tasks against that project. This is an ID such as 'Projects-1', not a project name. +- **`runbook`** :span[string]{.type-label} + The ID of a runbook, to return only runs of that runbook. +- **`running`** :span[boolean]{.type-label} + Set to true for tasks currently in progress (Executing or Cancelling), or false for tasks that are not. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`states`** :span[array of string]{.type-label} + Task states to match. One or more of New, Queued, Executing, Cancelling, Success, Failed, Canceled, TimedOut. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`tenant`** :span[string]{.type-label} + The ID of a tenant, to return only tasks against that tenant. This is an ID such as 'Tenants-1', not a tenant name. +- **`tenantTag`** :span[string]{.type-label} + A tenant tag in canonical form, such as 'Regions/EMEA', to return only tasks against tenants carrying it. +- **`toCompletedDate`** :span[string]{.type-label} + Format `date-time`. +- **`toQueueDate`** :span[string]{.type-label} + Format `date-time`. +- **`toStartDate`** :span[string]{.type-label} + Format `date-time`. + +**Response** + +`200` — Holds a TaskResourceCollection generated in response to a ListServerTasksRequest + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Arguments`** :span[object]{.type-label} + Gets or sets any arguments to the task. + - **`CanRerun`** :span[boolean]{.type-label} + If true, then the task can be used as the basis for a new task with the same effect. + - **`Completed`** :span[string]{.type-label} + Gets or sets a value indicating the completion status of the task. May be "Timed out", "Queued...", "Executing...", or the time at which the task completed for completed tasks. + - **`CompletedTime`** :span[string]{.type-label} + Gets or sets the date/time that the task completed. Will be null if the task has not yet completed. Format `date-time`. + - **`Description`** :span[string]{.type-label} + Gets or sets a short, human-understandable description of this task. An example might be "Manual database backup". This is the name that will be shown in the task list. + - **`Duration`** :span[string]{.type-label} + Gets or sets a string indicating how long the task took to run. + - **`ErrorMessage`** :span[string]{.type-label} + Gets or sets a short summary of the errors encountered when the task ran (if any). + - **`EstimatedRemainingQueueDurationSeconds`** :span[integer]{.type-label} + - **`FinishedSuccessfully`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task ran to completion successfully. + - **`HasBeenPickedUpByProcessor`** :span[boolean]{.type-label} + Gets or sets a boolean value indicating whether the Octopus Server is processing this task. + - **`HasPendingInterruptions`** :span[boolean]{.type-label} + True if the task has any pending interruptions. + - **`HasPendingPreconditions`** :span[boolean]{.type-label} + True if the task has any pending preconditions. + - **`HasWarningsOrErrors`** :span[boolean]{.type-label} + True if any warnings or non-fatal errors were recorded in the task log during execution. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsCompleted`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task has completed (that is, not queued, not running, and not paused; may have finished successfully or failed). + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastUpdatedTime`** :span[string]{.type-label} + Gets or sets the time that the Octopus server last updated the status of this task. For a running task this should happen at least every couple of minutes. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of the task to create. This name must be one of the list of possible names documented in the create API operation documentation. + - **`PendingInterruptionTypes`** :span[array of enum]{.type-label} + Contains a list of the types of any pending interruptions. + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. + - **`PendingPreconditionTypes`** :span[array of string]{.type-label} + Contains a list of the types of any pending preconditions. + - **`ProjectId`** :span[string]{.type-label} + If the task belongs to a project (e.g. a deployment), the ID of the project it belongs to. + - **`QueueTime`** :span[string]{.type-label} + Gets or sets the time at which the task was queued. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Gets or sets the time at which the task will timeout if it has not started executing. Format `date-time`. + - **`ServerNode`** :span[string]{.type-label} + Gets the ID of the Octopus server that created and will control this task. + - **`SpaceId`** :span[string]{.type-label} + - **`StartTime`** :span[string]{.type-label} + Gets or sets the time at which the task started executing. Format `date-time`. + - **`State`** :span[enum]{.type-label} + Gets or sets the current state of the task. + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Arguments": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "CanRerun": true, + "Completed": "string", + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Description": "string", + "Duration": "string", + "ErrorMessage": "string", + "EstimatedRemainingQueueDurationSeconds": 0, + "FinishedSuccessfully": true, + "HasBeenPickedUpByProcessor": true, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUpdatedTime": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ServerNode": "string", + "SpaceId": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued" + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new Task + +:endpoint{method="POST" path="/api/\{spaceId\}/tasks"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tasks`, `/api/tasks`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Arguments`** :span[object]{.type-label} +- **`Description`** :span[string]{.type-label} *(required)* +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`QueueTime`** :span[string]{.type-label} + Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Format `date-time`. +- **`SpaceId`** :span[string]{.type-label} +- **`Weight`** :span[number]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Arguments": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Description": "string", + "Name": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "SpaceId": "string", + "Weight": 0 +} +``` +::: + +**Response** + +`201` — Created + +- **`Arguments`** :span[object]{.type-label} + Gets or sets any arguments to the task. +- **`CanRerun`** :span[boolean]{.type-label} + If true, then the task can be used as the basis for a new task with the same effect. +- **`Completed`** :span[string]{.type-label} + Gets or sets a value indicating the completion status of the task. May be "Timed out", "Queued...", "Executing...", or the time at which the task completed for completed tasks. +- **`CompletedTime`** :span[string]{.type-label} + Gets or sets the date/time that the task completed. Will be null if the task has not yet completed. Format `date-time`. +- **`Description`** :span[string]{.type-label} + Gets or sets a short, human-understandable description of this task. An example might be "Manual database backup". This is the name that will be shown in the task list. +- **`Duration`** :span[string]{.type-label} + Gets or sets a string indicating how long the task took to run. +- **`ErrorMessage`** :span[string]{.type-label} + Gets or sets a short summary of the errors encountered when the task ran (if any). +- **`EstimatedRemainingQueueDurationSeconds`** :span[integer]{.type-label} +- **`FinishedSuccessfully`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task ran to completion successfully. +- **`HasBeenPickedUpByProcessor`** :span[boolean]{.type-label} + Gets or sets a boolean value indicating whether the Octopus Server is processing this task. +- **`HasPendingInterruptions`** :span[boolean]{.type-label} + True if the task has any pending interruptions. +- **`HasPendingPreconditions`** :span[boolean]{.type-label} + True if the task has any pending preconditions. +- **`HasWarningsOrErrors`** :span[boolean]{.type-label} + True if any warnings or non-fatal errors were recorded in the task log during execution. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsCompleted`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task has completed (that is, not queued, not running, and not paused; may have finished successfully or failed). +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastUpdatedTime`** :span[string]{.type-label} + Gets or sets the time that the Octopus server last updated the status of this task. For a running task this should happen at least every couple of minutes. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of the task to create. This name must be one of the list of possible names documented in the create API operation documentation. +- **`PendingInterruptionTypes`** :span[array of enum]{.type-label} + Contains a list of the types of any pending interruptions. + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. +- **`PendingPreconditionTypes`** :span[array of string]{.type-label} + Contains a list of the types of any pending preconditions. +- **`ProjectId`** :span[string]{.type-label} + If the task belongs to a project (e.g. a deployment), the ID of the project it belongs to. +- **`QueueTime`** :span[string]{.type-label} + Gets or sets the time at which the task was queued. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Gets or sets the time at which the task will timeout if it has not started executing. Format `date-time`. +- **`ServerNode`** :span[string]{.type-label} + Gets the ID of the Octopus server that created and will control this task. +- **`SpaceId`** :span[string]{.type-label} +- **`StartTime`** :span[string]{.type-label} + Gets or sets the time at which the task started executing. Format `date-time`. +- **`State`** :span[enum]{.type-label} + Gets or sets the current state of the task. + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. + +:::api-example{label="Response"} +```json +{ + "Arguments": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "CanRerun": true, + "Completed": "string", + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Description": "string", + "Duration": "string", + "ErrorMessage": "string", + "EstimatedRemainingQueueDurationSeconds": 0, + "FinishedSuccessfully": true, + "HasBeenPickedUpByProcessor": true, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUpdatedTime": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ServerNode": "string", + "SpaceId": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued" +} +``` +::: + +## Create a new task and execute it, using a given task as the input. Note that deployment tasks cannot be re-run + +:endpoint{method="POST" path="/api/\{spaceId\}/tasks/rerun/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tasks/rerun/{id}`, `/api/tasks/rerun/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Task to re-run. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resources. + +**Response** + +`200` — Carries the new task created in response to re-running an existing task via RerunServerTaskCommand. + +- **`Arguments`** :span[object]{.type-label} + Gets or sets any arguments to the task. +- **`CanRerun`** :span[boolean]{.type-label} + If true, then the task can be used as the basis for a new task with the same effect. +- **`Completed`** :span[string]{.type-label} + Gets or sets a value indicating the completion status of the task. May be "Timed out", "Queued...", "Executing...", or the time at which the task completed for completed tasks. +- **`CompletedTime`** :span[string]{.type-label} + Gets or sets the date/time that the task completed. Will be null if the task has not yet completed. Format `date-time`. +- **`Description`** :span[string]{.type-label} + Gets or sets a short, human-understandable description of this task. An example might be "Manual database backup". This is the name that will be shown in the task list. +- **`Duration`** :span[string]{.type-label} + Gets or sets a string indicating how long the task took to run. +- **`ErrorMessage`** :span[string]{.type-label} + Gets or sets a short summary of the errors encountered when the task ran (if any). +- **`EstimatedRemainingQueueDurationSeconds`** :span[integer]{.type-label} +- **`FinishedSuccessfully`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task ran to completion successfully. +- **`HasBeenPickedUpByProcessor`** :span[boolean]{.type-label} + Gets or sets a boolean value indicating whether the Octopus Server is processing this task. +- **`HasPendingInterruptions`** :span[boolean]{.type-label} + True if the task has any pending interruptions. +- **`HasPendingPreconditions`** :span[boolean]{.type-label} + True if the task has any pending preconditions. +- **`HasWarningsOrErrors`** :span[boolean]{.type-label} + True if any warnings or non-fatal errors were recorded in the task log during execution. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsCompleted`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task has completed (that is, not queued, not running, and not paused; may have finished successfully or failed). +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastUpdatedTime`** :span[string]{.type-label} + Gets or sets the time that the Octopus server last updated the status of this task. For a running task this should happen at least every couple of minutes. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of the task to create. This name must be one of the list of possible names documented in the create API operation documentation. +- **`PendingInterruptionTypes`** :span[array of enum]{.type-label} + Contains a list of the types of any pending interruptions. + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. +- **`PendingPreconditionTypes`** :span[array of string]{.type-label} + Contains a list of the types of any pending preconditions. +- **`ProjectId`** :span[string]{.type-label} + If the task belongs to a project (e.g. a deployment), the ID of the project it belongs to. +- **`QueueTime`** :span[string]{.type-label} + Gets or sets the time at which the task was queued. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Gets or sets the time at which the task will timeout if it has not started executing. Format `date-time`. +- **`ServerNode`** :span[string]{.type-label} + Gets the ID of the Octopus server that created and will control this task. +- **`SpaceId`** :span[string]{.type-label} +- **`StartTime`** :span[string]{.type-label} + Gets or sets the time at which the task started executing. Format `date-time`. +- **`State`** :span[enum]{.type-label} + Gets or sets the current state of the task. + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. + +:::api-example{label="Response"} +```json +{ + "Arguments": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "CanRerun": true, + "Completed": "string", + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Description": "string", + "Duration": "string", + "ErrorMessage": "string", + "EstimatedRemainingQueueDurationSeconds": 0, + "FinishedSuccessfully": true, + "HasBeenPickedUpByProcessor": true, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUpdatedTime": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ServerNode": "string", + "SpaceId": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued" +} +``` +::: + +## List supported task types + +:endpoint{method="GET" path="/api/\{spaceId\}/tasks/tasktypes"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tasks/tasktypes`, `/api/tasks/tasktypes`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Holds a list of supported task types, generated in response to a ListServerTaskTypesRequest + +- **`Id`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} +- **`Name`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Id": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } +] +``` +::: + +## Get a single Task by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/tasks/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tasks/{id}`, `/api/tasks/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Task to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resources. + +**Response** + +`200` — Holds a task, returned in response to GetServerTaskByIdRequest + +- **`Arguments`** :span[object]{.type-label} + Gets or sets any arguments to the task. +- **`CanRerun`** :span[boolean]{.type-label} + If true, then the task can be used as the basis for a new task with the same effect. +- **`Completed`** :span[string]{.type-label} + Gets or sets a value indicating the completion status of the task. May be "Timed out", "Queued...", "Executing...", or the time at which the task completed for completed tasks. +- **`CompletedTime`** :span[string]{.type-label} + Gets or sets the date/time that the task completed. Will be null if the task has not yet completed. Format `date-time`. +- **`Description`** :span[string]{.type-label} + Gets or sets a short, human-understandable description of this task. An example might be "Manual database backup". This is the name that will be shown in the task list. +- **`Duration`** :span[string]{.type-label} + Gets or sets a string indicating how long the task took to run. +- **`ErrorMessage`** :span[string]{.type-label} + Gets or sets a short summary of the errors encountered when the task ran (if any). +- **`EstimatedRemainingQueueDurationSeconds`** :span[integer]{.type-label} +- **`FinishedSuccessfully`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task ran to completion successfully. +- **`HasBeenPickedUpByProcessor`** :span[boolean]{.type-label} + Gets or sets a boolean value indicating whether the Octopus Server is processing this task. +- **`HasPendingInterruptions`** :span[boolean]{.type-label} + True if the task has any pending interruptions. +- **`HasPendingPreconditions`** :span[boolean]{.type-label} + True if the task has any pending preconditions. +- **`HasWarningsOrErrors`** :span[boolean]{.type-label} + True if any warnings or non-fatal errors were recorded in the task log during execution. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsCompleted`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task has completed (that is, not queued, not running, and not paused; may have finished successfully or failed). +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastUpdatedTime`** :span[string]{.type-label} + Gets or sets the time that the Octopus server last updated the status of this task. For a running task this should happen at least every couple of minutes. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of the task to create. This name must be one of the list of possible names documented in the create API operation documentation. +- **`PendingInterruptionTypes`** :span[array of enum]{.type-label} + Contains a list of the types of any pending interruptions. + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. +- **`PendingPreconditionTypes`** :span[array of string]{.type-label} + Contains a list of the types of any pending preconditions. +- **`ProjectId`** :span[string]{.type-label} + If the task belongs to a project (e.g. a deployment), the ID of the project it belongs to. +- **`QueueTime`** :span[string]{.type-label} + Gets or sets the time at which the task was queued. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Gets or sets the time at which the task will timeout if it has not started executing. Format `date-time`. +- **`ServerNode`** :span[string]{.type-label} + Gets the ID of the Octopus server that created and will control this task. +- **`SpaceId`** :span[string]{.type-label} +- **`StartTime`** :span[string]{.type-label} + Gets or sets the time at which the task started executing. Format `date-time`. +- **`State`** :span[enum]{.type-label} + Gets or sets the current state of the task. + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. + +:::api-example{label="Response"} +```json +{ + "Arguments": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "CanRerun": true, + "Completed": "string", + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Description": "string", + "Duration": "string", + "ErrorMessage": "string", + "EstimatedRemainingQueueDurationSeconds": 0, + "FinishedSuccessfully": true, + "HasBeenPickedUpByProcessor": true, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUpdatedTime": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ServerNode": "string", + "SpaceId": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued" +} +``` +::: + +## Mark the given task as canceled + +:endpoint{method="POST" path="/api/\{spaceId\}/tasks/\{id\}/cancel"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tasks/{id}/cancel`, `/api/tasks/{id}/cancel`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Task to cancel. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resources. + +**Response** + +`200` — Returned in response to CancelServerTaskRequest. If the ServerTask cancellation failed, clients should receive an error instead. + +- **`Arguments`** :span[object]{.type-label} + Gets or sets any arguments to the task. +- **`CanRerun`** :span[boolean]{.type-label} + If true, then the task can be used as the basis for a new task with the same effect. +- **`Completed`** :span[string]{.type-label} + Gets or sets a value indicating the completion status of the task. May be "Timed out", "Queued...", "Executing...", or the time at which the task completed for completed tasks. +- **`CompletedTime`** :span[string]{.type-label} + Gets or sets the date/time that the task completed. Will be null if the task has not yet completed. Format `date-time`. +- **`Description`** :span[string]{.type-label} + Gets or sets a short, human-understandable description of this task. An example might be "Manual database backup". This is the name that will be shown in the task list. +- **`Duration`** :span[string]{.type-label} + Gets or sets a string indicating how long the task took to run. +- **`ErrorMessage`** :span[string]{.type-label} + Gets or sets a short summary of the errors encountered when the task ran (if any). +- **`EstimatedRemainingQueueDurationSeconds`** :span[integer]{.type-label} +- **`FinishedSuccessfully`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task ran to completion successfully. +- **`HasBeenPickedUpByProcessor`** :span[boolean]{.type-label} + Gets or sets a boolean value indicating whether the Octopus Server is processing this task. +- **`HasPendingInterruptions`** :span[boolean]{.type-label} + True if the task has any pending interruptions. +- **`HasPendingPreconditions`** :span[boolean]{.type-label} + True if the task has any pending preconditions. +- **`HasWarningsOrErrors`** :span[boolean]{.type-label} + True if any warnings or non-fatal errors were recorded in the task log during execution. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsCompleted`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task has completed (that is, not queued, not running, and not paused; may have finished successfully or failed). +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastUpdatedTime`** :span[string]{.type-label} + Gets or sets the time that the Octopus server last updated the status of this task. For a running task this should happen at least every couple of minutes. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of the task to create. This name must be one of the list of possible names documented in the create API operation documentation. +- **`PendingInterruptionTypes`** :span[array of enum]{.type-label} + Contains a list of the types of any pending interruptions. + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. +- **`PendingPreconditionTypes`** :span[array of string]{.type-label} + Contains a list of the types of any pending preconditions. +- **`ProjectId`** :span[string]{.type-label} + If the task belongs to a project (e.g. a deployment), the ID of the project it belongs to. +- **`QueueTime`** :span[string]{.type-label} + Gets or sets the time at which the task was queued. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Gets or sets the time at which the task will timeout if it has not started executing. Format `date-time`. +- **`ServerNode`** :span[string]{.type-label} + Gets the ID of the Octopus server that created and will control this task. +- **`SpaceId`** :span[string]{.type-label} +- **`StartTime`** :span[string]{.type-label} + Gets or sets the time at which the task started executing. Format `date-time`. +- **`State`** :span[enum]{.type-label} + Gets or sets the current state of the task. + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. + +:::api-example{label="Response"} +```json +{ + "Arguments": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "CanRerun": true, + "Completed": "string", + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Description": "string", + "Duration": "string", + "ErrorMessage": "string", + "EstimatedRemainingQueueDurationSeconds": 0, + "FinishedSuccessfully": true, + "HasBeenPickedUpByProcessor": true, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUpdatedTime": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ServerNode": "string", + "SpaceId": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued" +} +``` +::: + +## Get a single task by ID, including the full task log as a tree of activity elements + +:endpoint{method="GET" path="/api/\{spaceId\}/tasks/\{id\}/details"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tasks/{id}/details`, `/api/tasks/{id}/details`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the task to load details for. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ranges`** :span[string]{.type-label} +- **`tail`** :span[integer]{.type-label} + If set, determines how many log entries will be returned. +- **`verbose`** :span[boolean]{.type-label} + If true, includes verbose output. + +**Response** + +`200` — Returns details about a specific server task + +- **`ActivityLogs`** :span[array of object]{.type-label} + - **`Children`** :span[array of object]{.type-label} + - **`Ended`** :span[string]{.type-label} + Format `date-time`. + - **`Id`** :span[string]{.type-label} + - **`LogElements`** :span[array of object]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`ProgressMessage`** :span[string]{.type-label} + - **`ProgressPercentage`** :span[integer]{.type-label} + - **`ShowAtSummaryLevel`** :span[boolean]{.type-label} + - **`Started`** :span[string]{.type-label} + Format `date-time`. + - **`Status`** :span[enum]{.type-label} + Allowed values: `Pending`, `Running`, `Success`, `Failed`, `Skipped`, `SuccessWithWarning`, `Canceled`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`PhysicalLogSize`** :span[integer]{.type-label} +- **`Progress`** :span[object]{.type-label} + - **`EstimatedTimeRemaining`** :span[string]{.type-label} + - **`ProgressPercentage`** :span[integer]{.type-label} +- **`Task`** :span[object]{.type-label} + - **`Arguments`** :span[object]{.type-label} + Gets or sets any arguments to the task. + - **`CanRerun`** :span[boolean]{.type-label} + If true, then the task can be used as the basis for a new task with the same effect. + - **`Completed`** :span[string]{.type-label} + Gets or sets a value indicating the completion status of the task. May be "Timed out", "Queued...", "Executing...", or the time at which the task completed for completed tasks. + - **`CompletedTime`** :span[string]{.type-label} + Gets or sets the date/time that the task completed. Will be null if the task has not yet completed. Format `date-time`. + - **`Description`** :span[string]{.type-label} + Gets or sets a short, human-understandable description of this task. An example might be "Manual database backup". This is the name that will be shown in the task list. + - **`Duration`** :span[string]{.type-label} + Gets or sets a string indicating how long the task took to run. + - **`ErrorMessage`** :span[string]{.type-label} + Gets or sets a short summary of the errors encountered when the task ran (if any). + - **`EstimatedRemainingQueueDurationSeconds`** :span[integer]{.type-label} + - **`FinishedSuccessfully`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task ran to completion successfully. + - **`HasBeenPickedUpByProcessor`** :span[boolean]{.type-label} + Gets or sets a boolean value indicating whether the Octopus Server is processing this task. + - **`HasPendingInterruptions`** :span[boolean]{.type-label} + True if the task has any pending interruptions. + - **`HasPendingPreconditions`** :span[boolean]{.type-label} + True if the task has any pending preconditions. + - **`HasWarningsOrErrors`** :span[boolean]{.type-label} + True if any warnings or non-fatal errors were recorded in the task log during execution. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsCompleted`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task has completed (that is, not queued, not running, and not paused; may have finished successfully or failed). + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastUpdatedTime`** :span[string]{.type-label} + Gets or sets the time that the Octopus server last updated the status of this task. For a running task this should happen at least every couple of minutes. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of the task to create. This name must be one of the list of possible names documented in the create API operation documentation. + - **`PendingInterruptionTypes`** :span[array of enum]{.type-label} + Contains a list of the types of any pending interruptions. + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. + - **`PendingPreconditionTypes`** :span[array of string]{.type-label} + Contains a list of the types of any pending preconditions. + - **`ProjectId`** :span[string]{.type-label} + If the task belongs to a project (e.g. a deployment), the ID of the project it belongs to. + - **`QueueTime`** :span[string]{.type-label} + Gets or sets the time at which the task was queued. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Gets or sets the time at which the task will timeout if it has not started executing. Format `date-time`. + - **`ServerNode`** :span[string]{.type-label} + Gets the ID of the Octopus server that created and will control this task. + - **`SpaceId`** :span[string]{.type-label} + - **`StartTime`** :span[string]{.type-label} + Gets or sets the time at which the task started executing. Format `date-time`. + - **`State`** :span[enum]{.type-label} + Gets or sets the current state of the task. + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. + +:::api-example{label="Response"} +```json +{ + "ActivityLogs": [ + { + "Children": [], + "Ended": "2020-01-01T00:00:00.000Z", + "Id": "string", + "LogElements": [ + {} + ], + "Name": "string", + "ProgressMessage": "string", + "ProgressPercentage": 0, + "ShowAtSummaryLevel": true, + "Started": "2020-01-01T00:00:00.000Z", + "Status": "Pending" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "PhysicalLogSize": 0, + "Progress": { + "EstimatedTimeRemaining": "string", + "ProgressPercentage": 0 + }, + "Task": { + "Arguments": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "CanRerun": true, + "Completed": "string", + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Description": "string", + "Duration": "string", + "ErrorMessage": "string", + "EstimatedRemainingQueueDurationSeconds": 0, + "FinishedSuccessfully": true, + "HasBeenPickedUpByProcessor": true, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUpdatedTime": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ServerNode": "string", + "SpaceId": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued" + } +} +``` +::: + +## Prioritize given task to the top of the Task Queue + +:endpoint{method="POST" path="/api/\{spaceId\}/tasks/\{id\}/prioritize"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tasks/{id}/prioritize`, `/api/tasks/{id}/prioritize`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +## Get a list of tasks that this task is currently queued behind + +:endpoint{method="GET" path="/api/\{spaceId\}/tasks/\{id\}/queued-behind"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tasks/{id}/queued-behind`, `/api/tasks/{id}/queued-behind`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Task. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Holds the list of tasks that a task is currently queued behind. Response to GetServerTaskQueuedBehindRequest. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Arguments`** :span[object]{.type-label} + Gets or sets any arguments to the task. + - **`CanRerun`** :span[boolean]{.type-label} + If true, then the task can be used as the basis for a new task with the same effect. + - **`Completed`** :span[string]{.type-label} + Gets or sets a value indicating the completion status of the task. May be "Timed out", "Queued...", "Executing...", or the time at which the task completed for completed tasks. + - **`CompletedTime`** :span[string]{.type-label} + Gets or sets the date/time that the task completed. Will be null if the task has not yet completed. Format `date-time`. + - **`Description`** :span[string]{.type-label} + Gets or sets a short, human-understandable description of this task. An example might be "Manual database backup". This is the name that will be shown in the task list. + - **`Duration`** :span[string]{.type-label} + Gets or sets a string indicating how long the task took to run. + - **`ErrorMessage`** :span[string]{.type-label} + Gets or sets a short summary of the errors encountered when the task ran (if any). + - **`EstimatedRemainingQueueDurationSeconds`** :span[integer]{.type-label} + - **`FinishedSuccessfully`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task ran to completion successfully. + - **`HasBeenPickedUpByProcessor`** :span[boolean]{.type-label} + Gets or sets a boolean value indicating whether the Octopus Server is processing this task. + - **`HasPendingInterruptions`** :span[boolean]{.type-label} + True if the task has any pending interruptions. + - **`HasPendingPreconditions`** :span[boolean]{.type-label} + True if the task has any pending preconditions. + - **`HasWarningsOrErrors`** :span[boolean]{.type-label} + True if any warnings or non-fatal errors were recorded in the task log during execution. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsCompleted`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task has completed (that is, not queued, not running, and not paused; may have finished successfully or failed). + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastUpdatedTime`** :span[string]{.type-label} + Gets or sets the time that the Octopus server last updated the status of this task. For a running task this should happen at least every couple of minutes. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of the task to create. This name must be one of the list of possible names documented in the create API operation documentation. + - **`PendingInterruptionTypes`** :span[array of enum]{.type-label} + Contains a list of the types of any pending interruptions. + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. + - **`PendingPreconditionTypes`** :span[array of string]{.type-label} + Contains a list of the types of any pending preconditions. + - **`ProjectId`** :span[string]{.type-label} + If the task belongs to a project (e.g. a deployment), the ID of the project it belongs to. + - **`QueueTime`** :span[string]{.type-label} + Gets or sets the time at which the task was queued. Format `date-time`. + - **`QueueTimeExpiry`** :span[string]{.type-label} + Gets or sets the time at which the task will timeout if it has not started executing. Format `date-time`. + - **`ServerNode`** :span[string]{.type-label} + Gets the ID of the Octopus server that created and will control this task. + - **`SpaceId`** :span[string]{.type-label} + - **`StartTime`** :span[string]{.type-label} + Gets or sets the time at which the task started executing. Format `date-time`. + - **`State`** :span[enum]{.type-label} + Gets or sets the current state of the task. + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Arguments": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "CanRerun": true, + "Completed": "string", + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Description": "string", + "Duration": "string", + "ErrorMessage": "string", + "EstimatedRemainingQueueDurationSeconds": 0, + "FinishedSuccessfully": true, + "HasBeenPickedUpByProcessor": true, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUpdatedTime": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ServerNode": "string", + "SpaceId": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued" + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Get the full task log of a given resource as plain text. Useful when the log needs to be rendered to a console or sent as an email attachment + +:endpoint{method="GET" path="/api/\{spaceId\}/tasks/\{id\}/raw"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tasks/{id}/raw`, `/api/tasks/{id}/raw`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the task. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Change the state of a task + +:endpoint{method="POST" path="/api/\{spaceId\}/tasks/\{id\}/state"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tasks/{id}/state`, `/api/tasks/{id}/state`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the task. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Id`** :span[string]{.type-label} *(required)* + The ID of the task. +- **`Reason`** :span[string]{.type-label} *(required)* + The reason for the state change. Minimum length 1. +- **`SpaceId`** :span[string]{.type-label} + The ID of the space containing the resource(s). +- **`State`** :span[enum]{.type-label} *(required)* + The state to set the task to. + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "Reason": "string", + "SpaceId": "string", + "State": "Queued" +} +``` +::: + +**Response** + +`200` — Returns the Task resource after the state has been changed in response to a ModifyServerTaskStateCommand + +- **`Arguments`** :span[object]{.type-label} + Gets or sets any arguments to the task. +- **`CanRerun`** :span[boolean]{.type-label} + If true, then the task can be used as the basis for a new task with the same effect. +- **`Completed`** :span[string]{.type-label} + Gets or sets a value indicating the completion status of the task. May be "Timed out", "Queued...", "Executing...", or the time at which the task completed for completed tasks. +- **`CompletedTime`** :span[string]{.type-label} + Gets or sets the date/time that the task completed. Will be null if the task has not yet completed. Format `date-time`. +- **`Description`** :span[string]{.type-label} + Gets or sets a short, human-understandable description of this task. An example might be "Manual database backup". This is the name that will be shown in the task list. +- **`Duration`** :span[string]{.type-label} + Gets or sets a string indicating how long the task took to run. +- **`ErrorMessage`** :span[string]{.type-label} + Gets or sets a short summary of the errors encountered when the task ran (if any). +- **`EstimatedRemainingQueueDurationSeconds`** :span[integer]{.type-label} +- **`FinishedSuccessfully`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task ran to completion successfully. +- **`HasBeenPickedUpByProcessor`** :span[boolean]{.type-label} + Gets or sets a boolean value indicating whether the Octopus Server is processing this task. +- **`HasPendingInterruptions`** :span[boolean]{.type-label} + True if the task has any pending interruptions. +- **`HasPendingPreconditions`** :span[boolean]{.type-label} + True if the task has any pending preconditions. +- **`HasWarningsOrErrors`** :span[boolean]{.type-label} + True if any warnings or non-fatal errors were recorded in the task log during execution. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsCompleted`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task has completed (that is, not queued, not running, and not paused; may have finished successfully or failed). +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastUpdatedTime`** :span[string]{.type-label} + Gets or sets the time that the Octopus server last updated the status of this task. For a running task this should happen at least every couple of minutes. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of the task to create. This name must be one of the list of possible names documented in the create API operation documentation. +- **`PendingInterruptionTypes`** :span[array of enum]{.type-label} + Contains a list of the types of any pending interruptions. + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. +- **`PendingPreconditionTypes`** :span[array of string]{.type-label} + Contains a list of the types of any pending preconditions. +- **`ProjectId`** :span[string]{.type-label} + If the task belongs to a project (e.g. a deployment), the ID of the project it belongs to. +- **`QueueTime`** :span[string]{.type-label} + Gets or sets the time at which the task was queued. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Gets or sets the time at which the task will timeout if it has not started executing. Format `date-time`. +- **`ServerNode`** :span[string]{.type-label} + Gets the ID of the Octopus server that created and will control this task. +- **`SpaceId`** :span[string]{.type-label} +- **`StartTime`** :span[string]{.type-label} + Gets or sets the time at which the task started executing. Format `date-time`. +- **`State`** :span[enum]{.type-label} + Gets or sets the current state of the task. + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. + +:::api-example{label="Response"} +```json +{ + "Arguments": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "CanRerun": true, + "Completed": "string", + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Description": "string", + "Duration": "string", + "ErrorMessage": "string", + "EstimatedRemainingQueueDurationSeconds": 0, + "FinishedSuccessfully": true, + "HasBeenPickedUpByProcessor": true, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUpdatedTime": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ServerNode": "string", + "SpaceId": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued" +} +``` +::: + +## Get messages for a single Task by Id + +:endpoint{method="GET" path="/api/\{spaceId\}/tasks/\{id\}/status/messages"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tasks/{id}/status/messages`, `/api/tasks/{id}/status/messages`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Task to load status messages for. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resources. + +**Response** + +`200` — The requested Task Status Messages + +- **`Messages`** :span[array of object]{.type-label} + - **`Category`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Message`** :span[string]{.type-label} + - **`Title`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Messages": [ + { + "Category": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Message": "string", + "Title": "string" + } + ] +} +``` +::: diff --git a/src/pages/docs/api/team-memberships.md b/src/pages/docs/api/team-memberships.md new file mode 100644 index 0000000000..0f32b148cd --- /dev/null +++ b/src/pages/docs/api/team-memberships.md @@ -0,0 +1,144 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Team Memberships +--- + +## Get a list of Team Memberships for a user + +:endpoint{method="GET" path="/api/\{spaceId\}/teammembership"} + +Also reachable at `/api/spaces/{spaceIdentifier}/teammembership`, `/api/spaces/{spaceIdentifier}/users/{userId}/teams`, `/api/teammembership`, `/api/users/{userId}/teams`, `/api/{spaceId}/users/{userId}/teams`. + +Lists all Teams a user is a member of, including any from external auth-provider security groups. Memberships are filtered by userId. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resources. + +**Query Parameters** + +- **`userId`** :span[string]{.type-label} *(required)* + ID of the user. + +**Response** + +`200` — The requested Team Membership + +- **`ExternalSecurityGroups`** :span[array of object]{.type-label} + - **`DisplayIdAndName`** :span[boolean]{.type-label} + - **`DisplayName`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} +- **`IsDirectlyAssigned`** :span[boolean]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TeamId`** :span[string]{.type-label} +- **`TeamName`** :span[string]{.type-label} +- **`UserId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "ExternalSecurityGroups": [ + { + "DisplayIdAndName": true, + "DisplayName": "string", + "Id": "string" + } + ], + "IsDirectlyAssigned": true, + "SpaceId": "string", + "TeamId": "string", + "TeamName": "string", + "UserId": "string" + } +] +``` +::: + +## Preview Users that would belong to the specified Team + +:endpoint{method="POST" path="/api/\{spaceId\}/teammembership/previewteam"} + +Also reachable at `/api/spaces/{spaceIdentifier}/teammembership/previewteam`, `/api/teammembership/previewteam`. + +Lists all the Users that would belong to the specified Team, including information about whether they are directly assigned and/or indirectly assigned via external security groups. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`ExternalSecurityGroups`** :span[array of object]{.type-label} *(required)* + The externally-managed security groups (e.g., Active Directory groups) who belong to the team. + - **`DisplayIdAndName`** :span[boolean]{.type-label} + - **`DisplayName`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} +- **`MemberUserIds`** :span[array of string]{.type-label} *(required)* + The users who belong to the team. +- **`Name`** :span[string]{.type-label} *(required)* + Gets or sets the name of this team. Minimum length 1. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "ExternalSecurityGroups": [ + { + "DisplayIdAndName": true, + "DisplayName": "string", + "Id": "string" + } + ], + "Id": "string", + "MemberUserIds": [ + "string" + ], + "Name": "string", + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — The requested Preview of Team Membership + +- **`ExternalSecurityGroups`** :span[array of object]{.type-label} + - **`DisplayIdAndName`** :span[boolean]{.type-label} + - **`DisplayName`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} +- **`IsDirectlyAssigned`** :span[boolean]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TeamId`** :span[string]{.type-label} +- **`TeamName`** :span[string]{.type-label} +- **`UserId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "ExternalSecurityGroups": [ + { + "DisplayIdAndName": true, + "DisplayName": "string", + "Id": "string" + } + ], + "IsDirectlyAssigned": true, + "SpaceId": "string", + "TeamId": "string", + "TeamName": "string", + "UserId": "string" + } +] +``` +::: diff --git a/src/pages/docs/api/teams.md b/src/pages/docs/api/teams.md new file mode 100644 index 0000000000..6d162ef752 --- /dev/null +++ b/src/pages/docs/api/teams.md @@ -0,0 +1,633 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Teams +--- + +## Get a list of Teams + +:endpoint{method="GET" path="/api/\{spaceId\}/teams"} + +Also reachable at `/api/spaces/{spaceIdentifier}/teams`, `/api/teams`. + +Lists all of the Teams in the system or Octopus Deploy Space (if provided). The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resources. + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + A list of Team IDs, to limit the matching of Teams to those with a particular ID. Example: ["Teams-1", "Teams-2"]. +- **`name`** :span[string]{.type-label} + The exact name of a Team to be matched. +- **`partialName`** :span[string]{.type-label} + A partial name, to limit the set of Teams to those with a name that includes the partial name. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Requested list of Teams + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`CanBeDeleted`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team can be deleted. The built-in teams provided by Octopus generally cannot be deleted. + - **`CanBeRenamed`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team can be renamed. The built-in teams provided by Octopus generally cannot be renamed. + - **`CanChangeMembers`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the members of this team can be changed. The built-in Everyone team provided by Octopus cannot have its members changed, as it will always contain all users. + - **`CanChangeRoles`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team's roles can be changed. The built-in Octopus Administrators team provided by Octopus cannot have its roles modified; all other teams can. + - **`Description`** :span[string]{.type-label} + - **`ExternalSecurityGroups`** :span[array of object]{.type-label} + The externally-managed security groups (e.g., Active Directory groups) who belong to the team. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MemberUserIds`** :span[array of string]{.type-label} + The users who belong to the team. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this team. + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "CanBeDeleted": true, + "CanBeRenamed": true, + "CanChangeMembers": true, + "CanChangeRoles": true, + "Description": "string", + "ExternalSecurityGroups": [ + {} + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MemberUserIds": [ + "string" + ], + "Name": "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 +} +``` +::: + +## Create a new team + +:endpoint{method="POST" path="/api/\{spaceId\}/teams"} + +Also reachable at `/api/spaces/{spaceIdentifier}/teams`, `/api/teams`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The space in which to create the team. + +**Request Body** + +- **`Description`** :span[string]{.type-label} + The description for the team. +- **`ExternalSecurityGroups`** :span[array of object]{.type-label} *(required)* + The externally-managed security groups (e.g., Active Directory groups) who will belong to the team. + - **`DisplayIdAndName`** :span[boolean]{.type-label} + - **`DisplayName`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} +- **`MemberUserIds`** :span[array of string]{.type-label} *(required)* + The users who will belong to the team. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the team. Minimum length 1. Maximum length 200. +- **`Slug`** :span[string]{.type-label} + The slug of the team. +- **`SpaceId`** :span[string]{.type-label} + The space in which to create the team. + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "ExternalSecurityGroups": [ + { + "DisplayIdAndName": true, + "DisplayName": "string", + "Id": "string" + } + ], + "MemberUserIds": [ + "string" + ], + "Name": "string", + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`CanBeDeleted`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team can be deleted. The built-in teams provided by Octopus generally cannot be deleted. +- **`CanBeRenamed`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team can be renamed. The built-in teams provided by Octopus generally cannot be renamed. +- **`CanChangeMembers`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the members of this team can be changed. The built-in Everyone team provided by Octopus cannot have its members changed, as it will always contain all users. +- **`CanChangeRoles`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team's roles can be changed. The built-in Octopus Administrators team provided by Octopus cannot have its roles modified; all other teams can. +- **`Description`** :span[string]{.type-label} +- **`ExternalSecurityGroups`** :span[array of object]{.type-label} + The externally-managed security groups (e.g., Active Directory groups) who belong to the team. + - **`DisplayIdAndName`** :span[boolean]{.type-label} + - **`DisplayName`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MemberUserIds`** :span[array of string]{.type-label} + The users who belong to the team. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this team. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CanBeDeleted": true, + "CanBeRenamed": true, + "CanChangeMembers": true, + "CanChangeRoles": true, + "Description": "string", + "ExternalSecurityGroups": [ + { + "DisplayIdAndName": true, + "DisplayName": "string", + "Id": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MemberUserIds": [ + "string" + ], + "Name": "string", + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +## Get a list of Teams + +:endpoint{method="GET" path="/api/\{spaceId\}/teams/all"} + +Also reachable at `/api/spaces/{spaceIdentifier}/teams/all`, `/api/teams/all`. + +Lists all of the Teams in the supplied Octopus Deploy Space. The results will be sorted by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested list of Teams + +- **`CanBeDeleted`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team can be deleted. The built-in teams provided by Octopus generally cannot be deleted. +- **`CanBeRenamed`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team can be renamed. The built-in teams provided by Octopus generally cannot be renamed. +- **`CanChangeMembers`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the members of this team can be changed. The built-in Everyone team provided by Octopus cannot have its members changed, as it will always contain all users. +- **`CanChangeRoles`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team's roles can be changed. The built-in Octopus Administrators team provided by Octopus cannot have its roles modified; all other teams can. +- **`Description`** :span[string]{.type-label} +- **`ExternalSecurityGroups`** :span[array of object]{.type-label} + The externally-managed security groups (e.g., Active Directory groups) who belong to the team. + - **`DisplayIdAndName`** :span[boolean]{.type-label} + - **`DisplayName`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MemberUserIds`** :span[array of string]{.type-label} + The users who belong to the team. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this team. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "CanBeDeleted": true, + "CanBeRenamed": true, + "CanChangeMembers": true, + "CanChangeRoles": true, + "Description": "string", + "ExternalSecurityGroups": [ + { + "DisplayIdAndName": true, + "DisplayName": "string", + "Id": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MemberUserIds": [ + "string" + ], + "Name": "string", + "Slug": "string", + "SpaceId": "string" + } +] +``` +::: + +## Get a Team by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/teams/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/teams/{id}`, `/api/teams/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the team. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resources. + +**Response** + +`200` — The requested Team + +- **`CanBeDeleted`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team can be deleted. The built-in teams provided by Octopus generally cannot be deleted. +- **`CanBeRenamed`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team can be renamed. The built-in teams provided by Octopus generally cannot be renamed. +- **`CanChangeMembers`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the members of this team can be changed. The built-in Everyone team provided by Octopus cannot have its members changed, as it will always contain all users. +- **`CanChangeRoles`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team's roles can be changed. The built-in Octopus Administrators team provided by Octopus cannot have its roles modified; all other teams can. +- **`Description`** :span[string]{.type-label} +- **`ExternalSecurityGroups`** :span[array of object]{.type-label} + The externally-managed security groups (e.g., Active Directory groups) who belong to the team. + - **`DisplayIdAndName`** :span[boolean]{.type-label} + - **`DisplayName`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MemberUserIds`** :span[array of string]{.type-label} + The users who belong to the team. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this team. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CanBeDeleted": true, + "CanBeRenamed": true, + "CanChangeMembers": true, + "CanChangeRoles": true, + "Description": "string", + "ExternalSecurityGroups": [ + { + "DisplayIdAndName": true, + "DisplayName": "string", + "Id": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MemberUserIds": [ + "string" + ], + "Name": "string", + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +## Modify an existing Team + +:endpoint{method="PUT" path="/api/\{spaceId\}/teams/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/teams/{id}`, `/api/teams/{id}`. + +The Everyone Team is treated as a special case and its members and external groups may not be changed. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Gets or sets a unique identifier for this resource. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`ExternalSecurityGroups`** :span[array of object]{.type-label} + The externally-managed security groups (e.g., Active Directory groups) who belong to the team. + - **`DisplayIdAndName`** :span[boolean]{.type-label} + - **`DisplayName`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* + Gets or sets a unique identifier for this resource. +- **`MemberUserIds`** :span[array of string]{.type-label} + The users who belong to the team. +- **`Name`** :span[string]{.type-label} *(required)* + Gets or sets the name of this team. Minimum length 1. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "ExternalSecurityGroups": [ + { + "DisplayIdAndName": true, + "DisplayName": "string", + "Id": "string" + } + ], + "Id": "string", + "MemberUserIds": [ + "string" + ], + "Name": "string", + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Indicates the team was modified, containing the updated Team + +- **`CanBeDeleted`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team can be deleted. The built-in teams provided by Octopus generally cannot be deleted. +- **`CanBeRenamed`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team can be renamed. The built-in teams provided by Octopus generally cannot be renamed. +- **`CanChangeMembers`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the members of this team can be changed. The built-in Everyone team provided by Octopus cannot have its members changed, as it will always contain all users. +- **`CanChangeRoles`** :span[boolean]{.type-label} + Gets or sets a flag indicating whether the team's roles can be changed. The built-in Octopus Administrators team provided by Octopus cannot have its roles modified; all other teams can. +- **`Description`** :span[string]{.type-label} +- **`ExternalSecurityGroups`** :span[array of object]{.type-label} + The externally-managed security groups (e.g., Active Directory groups) who belong to the team. + - **`DisplayIdAndName`** :span[boolean]{.type-label} + - **`DisplayName`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MemberUserIds`** :span[array of string]{.type-label} + The users who belong to the team. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this team. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CanBeDeleted": true, + "CanBeRenamed": true, + "CanChangeMembers": true, + "CanChangeRoles": true, + "Description": "string", + "ExternalSecurityGroups": [ + { + "DisplayIdAndName": true, + "DisplayName": "string", + "Id": "string" + } + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MemberUserIds": [ + "string" + ], + "Name": "string", + "Slug": "string", + "SpaceId": "string" +} +``` +::: + +## Delete an existing Team + +:endpoint{method="DELETE" path="/api/\{spaceId\}/teams/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/teams/{id}`, `/api/teams/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Team to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +## Get a list of a Team's Scoped User Roles + +:endpoint{method="GET" path="/api/\{spaceId\}/teams/\{id\}/scopeduserroles"} + +Also reachable at `/api/spaces/{spaceIdentifier}/teams/{id}/scopeduserroles`, `/api/teams/{id}/scopeduserroles`. + +List all the Scoped User Roles for the Team. Results will be sorted by Space Id with System Teams being sorted before Space Teams. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — The requested list of Scoped User Roles + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`EnvironmentIds`** :span[array of string]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`ProjectGroupIds`** :span[array of string]{.type-label} + - **`ProjectIds`** :span[array of string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`TeamId`** :span[string]{.type-label} + - **`TenantIds`** :span[array of string]{.type-label} + - **`UserRoleId`** :span[string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "EnvironmentIds": [ + "string" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectGroupIds": [ + "string" + ], + "ProjectIds": [ + "string" + ], + "SpaceId": "string", + "TeamId": "string", + "TenantIds": [ + "string" + ], + "UserRoleId": "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 +} +``` +::: diff --git a/src/pages/docs/api/telemetry.md b/src/pages/docs/api/telemetry.md new file mode 100644 index 0000000000..d85e198539 --- /dev/null +++ b/src/pages/docs/api/telemetry.md @@ -0,0 +1,246 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Telemetry +--- + +## Get the latest telemetry data + +:endpoint{method="GET" path="/api/telemetry/download"} + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Get the last telemetry task + +:endpoint{method="GET" path="/api/telemetry/lastTask"} + +**Response** + +`200` — The requested last Telemetry Task + +- **`Arguments`** :span[object]{.type-label} + Gets or sets any arguments to the task. +- **`CanRerun`** :span[boolean]{.type-label} + If true, then the task can be used as the basis for a new task with the same effect. +- **`Completed`** :span[string]{.type-label} + Gets or sets a value indicating the completion status of the task. May be "Timed out", "Queued...", "Executing...", or the time at which the task completed for completed tasks. +- **`CompletedTime`** :span[string]{.type-label} + Gets or sets the date/time that the task completed. Will be null if the task has not yet completed. Format `date-time`. +- **`Description`** :span[string]{.type-label} + Gets or sets a short, human-understandable description of this task. An example might be "Manual database backup". This is the name that will be shown in the task list. +- **`Duration`** :span[string]{.type-label} + Gets or sets a string indicating how long the task took to run. +- **`ErrorMessage`** :span[string]{.type-label} + Gets or sets a short summary of the errors encountered when the task ran (if any). +- **`EstimatedRemainingQueueDurationSeconds`** :span[integer]{.type-label} +- **`FinishedSuccessfully`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task ran to completion successfully. +- **`HasBeenPickedUpByProcessor`** :span[boolean]{.type-label} + Gets or sets a boolean value indicating whether the Octopus Server is processing this task. +- **`HasPendingInterruptions`** :span[boolean]{.type-label} + True if the task has any pending interruptions. +- **`HasPendingPreconditions`** :span[boolean]{.type-label} + True if the task has any pending preconditions. +- **`HasWarningsOrErrors`** :span[boolean]{.type-label} + True if any warnings or non-fatal errors were recorded in the task log during execution. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsCompleted`** :span[boolean]{.type-label} + Gets or sets a value indicating whether the task has completed (that is, not queued, not running, and not paused; may have finished successfully or failed). +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastUpdatedTime`** :span[string]{.type-label} + Gets or sets the time that the Octopus server last updated the status of this task. For a running task this should happen at least every couple of minutes. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of the task to create. This name must be one of the list of possible names documented in the create API operation documentation. +- **`PendingInterruptionTypes`** :span[array of enum]{.type-label} + Contains a list of the types of any pending interruptions. + Allowed values: `ManualIntervention`, `GuidedFailure`, `PullRequestCompletion`, `ArgoCDApplicationSync`, `KubernetesResourceVerification`. +- **`PendingPreconditionTypes`** :span[array of string]{.type-label} + Contains a list of the types of any pending preconditions. +- **`ProjectId`** :span[string]{.type-label} + If the task belongs to a project (e.g. a deployment), the ID of the project it belongs to. +- **`QueueTime`** :span[string]{.type-label} + Gets or sets the time at which the task was queued. Format `date-time`. +- **`QueueTimeExpiry`** :span[string]{.type-label} + Gets or sets the time at which the task will timeout if it has not started executing. Format `date-time`. +- **`ServerNode`** :span[string]{.type-label} + Gets the ID of the Octopus server that created and will control this task. +- **`SpaceId`** :span[string]{.type-label} +- **`StartTime`** :span[string]{.type-label} + Gets or sets the time at which the task started executing. Format `date-time`. +- **`State`** :span[enum]{.type-label} + Gets or sets the current state of the task. + Allowed values: `Queued`, `Executing`, `Failed`, `Canceled`, `TimedOut`, `Success`, `Cancelling`. + +:::api-example{label="Response"} +```json +{ + "Arguments": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "CanRerun": true, + "Completed": "string", + "CompletedTime": "2020-01-01T00:00:00.000Z", + "Description": "string", + "Duration": "string", + "ErrorMessage": "string", + "EstimatedRemainingQueueDurationSeconds": 0, + "FinishedSuccessfully": true, + "HasBeenPickedUpByProcessor": true, + "HasPendingInterruptions": true, + "HasPendingPreconditions": true, + "HasWarningsOrErrors": true, + "Id": "string", + "IsCompleted": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastUpdatedTime": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "PendingInterruptionTypes": [ + "ManualIntervention" + ], + "PendingPreconditionTypes": [ + "string" + ], + "ProjectId": "string", + "QueueTime": "2020-01-01T00:00:00.000Z", + "QueueTimeExpiry": "2020-01-01T00:00:00.000Z", + "ServerNode": "string", + "SpaceId": "string", + "StartTime": "2020-01-01T00:00:00.000Z", + "State": "Queued" +} +``` +::: + +## Get the Telemetry configuration + +:endpoint{method="GET" path="/api/telemetryconfiguration"} + +**Response** + +`200` — The requested Telemetry Configuration + +- **`Enabled`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsTelemetryEnforced`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ShowAsNewUntil`** :span[string]{.type-label} + Format `date-time`. + +:::api-example{label="Response"} +```json +{ + "Enabled": true, + "Id": "string", + "IsTelemetryEnforced": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ShowAsNewUntil": "2020-01-01T00:00:00.000Z" +} +``` +::: + +## Update the Telemetry Configuration + +:endpoint{method="PUT" path="/api/telemetryconfiguration"} + +**Request Body** + +- **`Enabled`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsTelemetryEnforced`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ShowAsNewUntil`** :span[string]{.type-label} + Format `date-time`. + +:::api-example{label="Request"} +```json +{ + "Enabled": true, + "Id": "string", + "IsTelemetryEnforced": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ShowAsNewUntil": "2020-01-01T00:00:00.000Z" +} +``` +::: + +**Response** + +`200` — Confirmation that Telemetry Configuration was modified, containing the new configuration + +- **`Enabled`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsTelemetryEnforced`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ShowAsNewUntil`** :span[string]{.type-label} + Format `date-time`. + +:::api-example{label="Response"} +```json +{ + "Enabled": true, + "Id": "string", + "IsTelemetryEnforced": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ShowAsNewUntil": "2020-01-01T00:00:00.000Z" +} +``` +::: diff --git a/src/pages/docs/api/tenants.md b/src/pages/docs/api/tenants.md new file mode 100644 index 0000000000..1bf73a2174 --- /dev/null +++ b/src/pages/docs/api/tenants.md @@ -0,0 +1,2773 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Tenants +--- + +## Get a list of tenants + +:endpoint{method="GET" path="/api/\{spaceId\}/tenants"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants`, `/api/tenants`. + +Lists all of the tenants in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name, and returned 30 at a time. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`clonedFromTenantId`** :span[string]{.type-label} + A Tenant ID, to limit the included Tenants to those cloned from that Tenant. Example: Tenants-1. +- **`ids`** :span[array of string]{.type-label} + A list of Tenant IDs, to limit the matching of Tenants to those with a particular ID. Example: ["Tenants-1", "Tenants-2"]. +- **`isDisabled`** :span[boolean]{.type-label} + Disabled Status, to limit the set of retrieved Tenants to those with the specified disabled status. +- **`name`** :span[string]{.type-label} + (Obsolete) A partial or complete name to limit the set of retrieved Tenants to. This will perform a "contains" style match against the supplied name or name-fragment. Left for backwards compatibility. +- **`partialName`** :span[string]{.type-label} + A partial name, to limit the set of Tenants to those with a name that includes the partial name. +- **`projectId`** :span[string]{.type-label} + A Project ID, to limit the set of Tenants to those connected to a particular Project. Example: Projects-1. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`tags`** :span[array of string]{.type-label} + A set of Tenant Tags, to limit the set of retrieved Tenants to those which are tagged with the specific tags. Example: Alpha,Beta,Stable. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Requested list of Tenants + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`ClonedFromTenantId`** :span[string]{.type-label} + - **`CustomFields`** :span[array of string]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`Icon`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`ProjectEnvironments`** :span[object]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`TenantTags`** :span[array of string]{.type-label} + Tags are referenced by CanonicalName like {TagSetName}/{TagName}. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "ClonedFromTenantId": "string", + "CustomFields": [ + "string" + ], + "Description": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectEnvironments": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "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 +} +``` +::: + +## Create a new Tenant + +:endpoint{method="POST" path="/api/\{spaceId\}/tenants"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants`, `/api/tenants`. + +Creates a new Tenant, optionally cloning an existing tenant if the clone query string parameter is provided. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Clone`** :span[string]{.type-label} + The ID of the Tenant to clone. Example: Tenants-101. +- **`Description`** :span[string]{.type-label} +- **`IsDisabled`** :span[boolean]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ProjectEnvironments`** :span[object]{.type-label} + The projects the tenant is connected to, as an object keyed by project ID where each value is the array of environment IDs the tenant can deploy to for that project. Example: {"Projects-1": ["Environments-1", "Environments-2"]}. +- **`Slug`** :span[string]{.type-label} + A URL-friendly, unique identifier for the tenant. Generated from the name when omitted, which is usually what you want. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantTags`** :span[array of string]{.type-label} + Tags to apply to the tenant, as canonical tag names in the form 'TagSetName/TagName'. Example: ["Regions/EU-West", "Tier/Premium"]. Only tags from tenant-scoped tag sets are valid. + +:::api-example{label="Request"} +```json +{ + "Clone": "string", + "Description": "string", + "IsDisabled": true, + "Name": "string", + "ProjectEnvironments": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ] +} +``` +::: + +**Response** + +`201` — Created + +- **`ClonedFromTenantId`** :span[string]{.type-label} +- **`CustomFields`** :span[array of string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ProjectEnvironments`** :span[object]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} + Tags are referenced by CanonicalName like {TagSetName}/{TagName}. + +:::api-example{label="Response"} +```json +{ + "ClonedFromTenantId": "string", + "CustomFields": [ + "string" + ], + "Description": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectEnvironments": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ] +} +``` +::: + +## List all tenants + +:endpoint{method="GET" path="/api/\{spaceId\}/tenants/all"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/all`, `/api/tenants/all`. + +Lists all of the tenants in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + A set of Tenant IDs to retrieve Tenants for. +- **`isDisabled`** :span[boolean]{.type-label} + Disabled Status, to limit the set of retrieved Tenants to those with the specified disabled status. +- **`name`** :span[string]{.type-label} + (Obsolete) A partial or complete name to limit the set of retrieved Tenants to. This will perform a "contains" style match against the supplied name or name-fragment. Left for backwards compatibility. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to limit the set of retrieved Tenants to. This will perform a "contains" style match against the supplied name or name-fragment. +- **`projectId`** :span[string]{.type-label} + A Project ID, to limit the set of retrieved Tenants to those connected to a particular Project. +- **`tags`** :span[array of string]{.type-label} + A set of Tenant Tags, to limit the set of retrieved Tenants to those which are tagged with the specific tags. Example: Alpha,Beta,Stable. + +**Response** + +`200` — Requested list of Tenants + +- **`ClonedFromTenantId`** :span[string]{.type-label} +- **`CustomFields`** :span[array of string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ProjectEnvironments`** :span[object]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} + Tags are referenced by CanonicalName like {TagSetName}/{TagName}. + +:::api-example{label="Response"} +```json +[ + { + "ClonedFromTenantId": "string", + "CustomFields": [ + "string" + ], + "Description": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectEnvironments": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ] + } +] +``` +::: + +## Report back the status of multi-tenancy + +:endpoint{method="GET" path="/api/\{spaceId\}/tenants/status"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/status`, `/api/tenants/status`. + +If multi-tenancy is enabled, \"Enabled\" will be true, otherwise it will be false. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The status of multi-tenancy. + +- **`Enabled`** :span[boolean]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + +:::api-example{label="Response"} +```json +{ + "Enabled": true, + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +## Check tenants for matching tags + +:endpoint{method="GET" path="/api/\{spaceId\}/tenants/tag-test"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/tag-test`, `/api/tenants/tag-test`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`tags`** :span[array of string]{.type-label} + A list of Tenant Tags to limit the matching to. +- **`tenantIds`** :span[array of string]{.type-label} + A list of Tenant IDs to limit the matching to. + +**Response** + +`200` — Requested set of Tenants with matching Tags + +:::api-example{label="Response"} +```json +{ + "additionalProp1": { + "IsDisabled": true, + "IsMatched": true, + "MissingTags": [ + "string" + ], + "Reason": "string" + }, + "additionalProp2": { + "IsDisabled": true, + "IsMatched": true, + "MissingTags": [ + "string" + ], + "Reason": "string" + }, + "additionalProp3": { + "IsDisabled": true, + "IsMatched": true, + "MissingTags": [ + "string" + ], + "Reason": "string" + } +} +``` +::: + +## Return a list of tenants who are missing required variables + +:endpoint{method="GET" path="/api/\{spaceId\}/tenants/variables-missing"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/variables-missing`, `/api/tenants/variables-missing`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`environmentId`** :span[string]{.type-label} + An Environment ID, to limit the set of inspected Tenants to those connected to a particular Environment. Example: Environments-202. +- **`includeDetails`** :span[boolean]{.type-label} + A switch to indicate whether missing variable details should be returned along with names. When false, each result names only the tenant, which is enough to check whether a tenant is missing anything at all. +- **`projectId`** :span[string]{.type-label} + A Project ID, to limit the set of inspected Tenants to those connected to a particular Project. Example: Projects-202. +- **`tenantId`** :span[string]{.type-label} + An ID for a Tenant. If supplied, will limit the result to variables missing for the Tenant identified by the ID. Example: Tenants-101. + +**Response** + +`200` — List of tenants who are missing required variables. + +- **`Links`** :span[object]{.type-label} +- **`MissingVariables`** :span[array of object]{.type-label} + - **`EnvironmentId`** :span[string]{.type-label} + - **`LibraryVariableSetId`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`VariableTemplateId`** :span[string]{.type-label} + - **`VariableTemplateName`** :span[string]{.type-label} +- **`TenantId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MissingVariables": [ + { + "EnvironmentId": "string", + "LibraryVariableSetId": "string", + "Links": {}, + "ProjectId": "string", + "VariableTemplateId": "string", + "VariableTemplateName": "string" + } + ], + "TenantId": "string" + } +] +``` +::: + +## Get a tenant by it's Id + +:endpoint{method="GET" path="/api/\{spaceId\}/tenants/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/{id}`, `/api/tenants/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Tenant to load. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Returns a tenant + +- **`ClonedFromTenantId`** :span[string]{.type-label} +- **`CustomFields`** :span[array of string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ProjectEnvironments`** :span[object]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} + Tags are referenced by CanonicalName like {TagSetName}/{TagName}. + +:::api-example{label="Response"} +```json +{ + "ClonedFromTenantId": "string", + "CustomFields": [ + "string" + ], + "Description": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectEnvironments": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ] +} +``` +::: + +## Modify an existing Tenant + +:endpoint{method="PUT" path="/api/\{spaceId\}/tenants/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/{id}`, `/api/tenants/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Tenant to modify. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* + ID of the Tenant to modify. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`ProjectEnvironments`** :span[object]{.type-label} + The complete set of projects the tenant is connected to, as an object keyed by project ID where each value is the array of environment IDs the tenant can deploy to for that project. Example: {"Projects-1": ["Environments-1"]}. Replaces the tenant's current connections; omitting an existing project disconnects it and deletes the tenant's variable values for it. +- **`Slug`** :span[string]{.type-label} + A URL-friendly, unique identifier for the tenant. Resubmit the tenant's current slug unless you intend to change it; changing it breaks existing links that use the old slug. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantTags`** :span[array of string]{.type-label} + The complete set of tags for the tenant, as canonical tag names in the form 'TagSetName/TagName'. Example: ["Regions/EU-West", "Tier/Premium"]. Replaces the tenant's current tags; any existing tag omitted here is removed. + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Id": "string", + "IsDisabled": true, + "Name": "string", + "ProjectEnvironments": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ] +} +``` +::: + +**Response** + +`200` — Confirms that a Tenant has been modified, containing the updated Tenant + +- **`ClonedFromTenantId`** :span[string]{.type-label} +- **`CustomFields`** :span[array of string]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`Icon`** :span[object]{.type-label} + - **`Color`** :span[string]{.type-label} + Icon background colour, as a Hex string. + - **`Id`** :span[string]{.type-label} + Font Awesome Icon Id. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`ProjectEnvironments`** :span[object]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantTags`** :span[array of string]{.type-label} + Tags are referenced by CanonicalName like {TagSetName}/{TagName}. + +:::api-example{label="Response"} +```json +{ + "ClonedFromTenantId": "string", + "CustomFields": [ + "string" + ], + "Description": "string", + "Icon": { + "Color": "string", + "Id": "string" + }, + "Id": "string", + "IsDisabled": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "ProjectEnvironments": { + "additionalProp1": [ + "string" + ], + "additionalProp2": [ + "string" + ], + "additionalProp3": [ + "string" + ] + }, + "Slug": "string", + "SpaceId": "string", + "TenantTags": [ + "string" + ] +} +``` +::: + +## Delete an existing Tenant + +:endpoint{method="DELETE" path="/api/\{spaceId\}/tenants/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/{id}`, `/api/tenants/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Tenant to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +## Get the logo associated with the Tenant + +:endpoint{method="GET" path="/api/\{spaceId\}/tenants/\{id\}/logo"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/{id}/logo`, `/api/tenants/{id}/logo`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Tenant to retrieve the logo for. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: + +## Modify the logo associated with the tenant + +:endpoint{method="POST" path="/api/\{spaceId\}/tenants/\{id\}/logo"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/{id}/logo`, `/api/tenants/{id}/logo`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Tenant to update the logo for. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +## Modify the logo associated with the tenant + +:endpoint{method="PUT" path="/api/\{spaceId\}/tenants/\{id\}/logo"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Tenant to update the logo for. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +## Modify the logo associated with the tenant + +:endpoint{method="PUT" path="/api/spaces/\{spaceIdentifier\}/tenants/\{id\}/logo"} + +Also reachable at `/api/tenants/{id}/logo`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Tenant to update the logo for. +- **`spaceIdentifier`** :span[string]{.type-label} *(required)* + Identifier (ID or slug) of the space. + +**Response** + +`200` — Success + +## Get variables associated with the provided tenant ID + +:endpoint{method="GET" path="/api/\{spaceId\}/tenants/\{id\}/variables"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/{id}/variables`, `/api/tenants/{id}/variables`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the Tenant to retrieve variables for. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Variables associated with the provided tenant ID. + +- **`ConcurrencyToken`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariables`** :span[object]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectVariables`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`TenantName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConcurrencyToken": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariables": { + "additionalProp1": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp2": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp3": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + } + }, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectVariables": { + "additionalProp1": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp2": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp3": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + } + }, + "SpaceId": "string", + "TenantId": "string", + "TenantName": "string" +} +``` +::: + +## Create or Update the variables associated with the tenant + +:endpoint{method="POST" path="/api/\{spaceId\}/tenants/\{id\}/variables"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/{id}/variables`, `/api/tenants/{id}/variables`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Tenant to modify. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ConcurrencyToken`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* + ID of the Tenant to modify. +- **`LibraryVariables`** :span[object]{.type-label} +- **`ProjectVariables`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantName`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "ConcurrencyToken": "string", + "Id": "string", + "LibraryVariables": { + "additionalProp1": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp2": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp3": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + } + }, + "ProjectVariables": { + "additionalProp1": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp2": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp3": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + } + }, + "SpaceId": "string", + "TenantName": "string" +} +``` +::: + +**Response** + +`200` — The variables associated with the tenant. + +- **`ConcurrencyToken`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariables`** :span[object]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectVariables`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`TenantName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConcurrencyToken": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariables": { + "additionalProp1": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp2": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp3": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + } + }, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectVariables": { + "additionalProp1": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp2": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp3": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + } + }, + "SpaceId": "string", + "TenantId": "string", + "TenantName": "string" +} +``` +::: + +## Create or Update the variables associated with the tenant + +:endpoint{method="PUT" path="/api/\{spaceId\}/tenants/\{id\}/variables"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Tenant to modify. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ConcurrencyToken`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* + ID of the Tenant to modify. +- **`LibraryVariables`** :span[object]{.type-label} +- **`ProjectVariables`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantName`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "ConcurrencyToken": "string", + "Id": "string", + "LibraryVariables": { + "additionalProp1": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp2": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp3": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + } + }, + "ProjectVariables": { + "additionalProp1": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp2": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp3": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + } + }, + "SpaceId": "string", + "TenantName": "string" +} +``` +::: + +**Response** + +`200` — The variables associated with the tenant. + +- **`ConcurrencyToken`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariables`** :span[object]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectVariables`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`TenantName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConcurrencyToken": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariables": { + "additionalProp1": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp2": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp3": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + } + }, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectVariables": { + "additionalProp1": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp2": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp3": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + } + }, + "SpaceId": "string", + "TenantId": "string", + "TenantName": "string" +} +``` +::: + +## Create or Update the variables associated with the tenant + +:endpoint{method="PUT" path="/api/spaces/\{spaceIdentifier\}/tenants/\{id\}/variables"} + +Also reachable at `/api/tenants/{id}/variables`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Tenant to modify. +- **`spaceIdentifier`** :span[string]{.type-label} *(required)* + Identifier (ID or slug) of the space. + +**Request Body** + +- **`ConcurrencyToken`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* + ID of the Tenant to modify. +- **`LibraryVariables`** :span[object]{.type-label} +- **`ProjectVariables`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantName`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "ConcurrencyToken": "string", + "Id": "string", + "LibraryVariables": { + "additionalProp1": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp2": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp3": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + } + }, + "ProjectVariables": { + "additionalProp1": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp2": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp3": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + } + }, + "SpaceId": "string", + "TenantName": "string" +} +``` +::: + +**Response** + +`200` — The variables associated with the tenant. + +- **`ConcurrencyToken`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariables`** :span[object]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectVariables`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`TenantName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConcurrencyToken": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariables": { + "additionalProp1": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp2": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp3": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + } + }, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectVariables": { + "additionalProp1": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp2": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + }, + "additionalProp3": { + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + } + } + }, + "SpaceId": "string", + "TenantId": "string", + "TenantName": "string" +} +``` +::: + +## Get the common variables associated with the tenant + +:endpoint{method="GET" path="/api/\{spaceId\}/tenants/\{tenantId\}/commonvariables"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/{tenantId}/commonvariables`, `/api/tenants/{tenantId}/commonvariables`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* +- **`tenantId`** :span[string]{.type-label} *(required)* + The ID of the tenant to read common variable values for. Example: Tenants-101. + +**Query Parameters** + +- **`includeMissingVariables`** :span[boolean]{.type-label} + When true, the response also lists the library variable set templates the tenant is required to supply a value for but has not, along with each template's default value. + +**Response** + +`200` — The common variables associated with a tenant. + +- **`ConcurrencyToken`** :span[string]{.type-label} + Minimum length 1. +- **`MissingVariables`** :span[array of object]{.type-label} + - **`LibraryVariableSetId`** :span[string]{.type-label} + - **`LibraryVariableSetName`** :span[string]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Template`** :span[object]{.type-label} + - **`TemplateId`** :span[string]{.type-label} + Minimum length 1. + - **`Value`** :span[object]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`LibraryVariableSetId`** :span[string]{.type-label} + - **`LibraryVariableSetName`** :span[string]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Template`** :span[object]{.type-label} + - **`TemplateId`** :span[string]{.type-label} + Minimum length 1. + - **`Value`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConcurrencyToken": "string", + "MissingVariables": [ + { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "Template": { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ], + "TenantId": "string", + "Variables": [ + { + "Id": "string", + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "Template": { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ] +} +``` +::: + +## Create or Update the common variables associated with the tenant + +:endpoint{method="POST" path="/api/\{spaceId\}/tenants/\{tenantId\}/commonvariables"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/{tenantId}/commonvariables`, `/api/tenants/{tenantId}/commonvariables`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* +- **`tenantId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ConcurrencyToken`** :span[string]{.type-label} + The concurrency token returned when reading the tenant's variables. Always pass it back so the write is rejected if someone else changed the variables since your read; omitting it skips the check and risks silently overwriting their changes. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantId`** :span[string]{.type-label} *(required)* +- **`Variables`** :span[array of object]{.type-label} *(required)* + The complete set of common variable values for the tenant; existing values omitted here are deleted. Each item is an object: 'Id' (the existing value's ID when updating; omit when adding), 'OwnerId' (the library variable set ID), 'TemplateId' (the variable template ID), 'Value' (a plain string for non-sensitive values, or {"HasValue": true, "NewValue": "secret"} for sensitive ones), and 'Scope' ({"EnvironmentIds": [...]} limiting the value to those environments; empty applies to all). + - **`Id`** :span[string]{.type-label} + - **`OwnerId`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`Scope`** :span[object]{.type-label} *(required)* + - **`TemplateId`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`Value`** :span[object]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "ConcurrencyToken": "string", + "SpaceId": "string", + "TenantId": "string", + "Variables": [ + { + "Id": "string", + "OwnerId": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ] +} +``` +::: + +**Response** + +`200` — The common variables associated with a tenant. + +- **`ConcurrencyToken`** :span[string]{.type-label} + Minimum length 1. +- **`TenantId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`LibraryVariableSetId`** :span[string]{.type-label} + - **`LibraryVariableSetName`** :span[string]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Template`** :span[object]{.type-label} + - **`TemplateId`** :span[string]{.type-label} + Minimum length 1. + - **`Value`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConcurrencyToken": "string", + "TenantId": "string", + "Variables": [ + { + "Id": "string", + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "Template": { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ] +} +``` +::: + +## Create or Update the common variables associated with the tenant + +:endpoint{method="PUT" path="/api/\{spaceId\}/tenants/\{tenantId\}/commonvariables"} + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* +- **`tenantId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ConcurrencyToken`** :span[string]{.type-label} + The concurrency token returned when reading the tenant's variables. Always pass it back so the write is rejected if someone else changed the variables since your read; omitting it skips the check and risks silently overwriting their changes. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantId`** :span[string]{.type-label} *(required)* +- **`Variables`** :span[array of object]{.type-label} *(required)* + The complete set of common variable values for the tenant; existing values omitted here are deleted. Each item is an object: 'Id' (the existing value's ID when updating; omit when adding), 'OwnerId' (the library variable set ID), 'TemplateId' (the variable template ID), 'Value' (a plain string for non-sensitive values, or {"HasValue": true, "NewValue": "secret"} for sensitive ones), and 'Scope' ({"EnvironmentIds": [...]} limiting the value to those environments; empty applies to all). + - **`Id`** :span[string]{.type-label} + - **`OwnerId`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`Scope`** :span[object]{.type-label} *(required)* + - **`TemplateId`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`Value`** :span[object]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "ConcurrencyToken": "string", + "SpaceId": "string", + "TenantId": "string", + "Variables": [ + { + "Id": "string", + "OwnerId": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ] +} +``` +::: + +**Response** + +`200` — The common variables associated with a tenant. + +- **`ConcurrencyToken`** :span[string]{.type-label} + Minimum length 1. +- **`TenantId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`LibraryVariableSetId`** :span[string]{.type-label} + - **`LibraryVariableSetName`** :span[string]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Template`** :span[object]{.type-label} + - **`TemplateId`** :span[string]{.type-label} + Minimum length 1. + - **`Value`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConcurrencyToken": "string", + "TenantId": "string", + "Variables": [ + { + "Id": "string", + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "Template": { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ] +} +``` +::: + +## Create or Update the common variables associated with the tenant + +:endpoint{method="PUT" path="/api/spaces/\{spaceIdentifier\}/tenants/\{tenantId\}/commonvariables"} + +Also reachable at `/api/tenants/{tenantId}/commonvariables`. + +**Path Parameters** + +- **`spaceIdentifier`** :span[string]{.type-label} *(required)* + Identifier (ID or slug) of the space. +- **`tenantId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ConcurrencyToken`** :span[string]{.type-label} + The concurrency token returned when reading the tenant's variables. Always pass it back so the write is rejected if someone else changed the variables since your read; omitting it skips the check and risks silently overwriting their changes. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantId`** :span[string]{.type-label} *(required)* +- **`Variables`** :span[array of object]{.type-label} *(required)* + The complete set of common variable values for the tenant; existing values omitted here are deleted. Each item is an object: 'Id' (the existing value's ID when updating; omit when adding), 'OwnerId' (the library variable set ID), 'TemplateId' (the variable template ID), 'Value' (a plain string for non-sensitive values, or {"HasValue": true, "NewValue": "secret"} for sensitive ones), and 'Scope' ({"EnvironmentIds": [...]} limiting the value to those environments; empty applies to all). + - **`Id`** :span[string]{.type-label} + - **`OwnerId`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`Scope`** :span[object]{.type-label} *(required)* + - **`TemplateId`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`Value`** :span[object]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "ConcurrencyToken": "string", + "SpaceId": "string", + "TenantId": "string", + "Variables": [ + { + "Id": "string", + "OwnerId": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ] +} +``` +::: + +**Response** + +`200` — The common variables associated with a tenant. + +- **`ConcurrencyToken`** :span[string]{.type-label} + Minimum length 1. +- **`TenantId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`LibraryVariableSetId`** :span[string]{.type-label} + - **`LibraryVariableSetName`** :span[string]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Template`** :span[object]{.type-label} + - **`TemplateId`** :span[string]{.type-label} + Minimum length 1. + - **`Value`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConcurrencyToken": "string", + "TenantId": "string", + "Variables": [ + { + "Id": "string", + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "Template": { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ] +} +``` +::: + +## Get the project variables associated with the tenant + +:endpoint{method="GET" path="/api/\{spaceId\}/tenants/\{tenantId\}/projectvariables"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/{tenantId}/projectvariables`, `/api/tenants/{tenantId}/projectvariables`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* +- **`tenantId`** :span[string]{.type-label} *(required)* + The ID of the tenant to read project variable values for. Example: Tenants-101. + +**Query Parameters** + +- **`includeMissingVariables`** :span[boolean]{.type-label} + When true, the response also lists the project variable templates the tenant is required to supply a value for but has not, along with each template's default value. + +**Response** + +`200` — The project variables associated with a tenant. + +- **`ConcurrencyToken`** :span[string]{.type-label} + Minimum length 1. +- **`MissingVariables`** :span[array of object]{.type-label} + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Template`** :span[object]{.type-label} + - **`TemplateId`** :span[string]{.type-label} + Minimum length 1. + - **`Value`** :span[object]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Template`** :span[object]{.type-label} + - **`TemplateId`** :span[string]{.type-label} + Minimum length 1. + - **`Value`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConcurrencyToken": "string", + "MissingVariables": [ + { + "ProjectId": "string", + "ProjectName": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "Template": { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ], + "TenantId": "string", + "Variables": [ + { + "Id": "string", + "ProjectId": "string", + "ProjectName": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "Template": { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ] +} +``` +::: + +## Create or Update the project variables associated with the tenant + +:endpoint{method="POST" path="/api/\{spaceId\}/tenants/\{tenantId\}/projectvariables"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenants/{tenantId}/projectvariables`, `/api/tenants/{tenantId}/projectvariables`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* +- **`tenantId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ConcurrencyToken`** :span[string]{.type-label} + The concurrency token returned when reading the tenant's variables. Always pass it back so the write is rejected if someone else changed the variables since your read; omitting it skips the check and risks silently overwriting their changes. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantId`** :span[string]{.type-label} *(required)* +- **`Variables`** :span[array of object]{.type-label} *(required)* + The complete set of project variable values for the tenant; existing values omitted here are deleted. Each item is an object: 'Id' (the existing value's ID when updating; omit when adding), 'OwnerId' (the project ID), 'TemplateId' (the variable template ID), 'Value' (a plain string for non-sensitive values, or {"HasValue": true, "NewValue": "secret"} for sensitive ones), and 'Scope' ({"EnvironmentIds": [...]} limiting the value to those environments; empty applies to all). + - **`Id`** :span[string]{.type-label} + - **`OwnerId`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`Scope`** :span[object]{.type-label} *(required)* + - **`TemplateId`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`Value`** :span[object]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "ConcurrencyToken": "string", + "SpaceId": "string", + "TenantId": "string", + "Variables": [ + { + "Id": "string", + "OwnerId": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ] +} +``` +::: + +**Response** + +`200` — The project variables associated with a tenant. + +- **`ConcurrencyToken`** :span[string]{.type-label} + Minimum length 1. +- **`TenantId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Template`** :span[object]{.type-label} + - **`TemplateId`** :span[string]{.type-label} + Minimum length 1. + - **`Value`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConcurrencyToken": "string", + "TenantId": "string", + "Variables": [ + { + "Id": "string", + "ProjectId": "string", + "ProjectName": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "Template": { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ] +} +``` +::: + +## Create or Update the project variables associated with the tenant + +:endpoint{method="PUT" path="/api/\{spaceId\}/tenants/\{tenantId\}/projectvariables"} + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* +- **`tenantId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ConcurrencyToken`** :span[string]{.type-label} + The concurrency token returned when reading the tenant's variables. Always pass it back so the write is rejected if someone else changed the variables since your read; omitting it skips the check and risks silently overwriting their changes. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantId`** :span[string]{.type-label} *(required)* +- **`Variables`** :span[array of object]{.type-label} *(required)* + The complete set of project variable values for the tenant; existing values omitted here are deleted. Each item is an object: 'Id' (the existing value's ID when updating; omit when adding), 'OwnerId' (the project ID), 'TemplateId' (the variable template ID), 'Value' (a plain string for non-sensitive values, or {"HasValue": true, "NewValue": "secret"} for sensitive ones), and 'Scope' ({"EnvironmentIds": [...]} limiting the value to those environments; empty applies to all). + - **`Id`** :span[string]{.type-label} + - **`OwnerId`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`Scope`** :span[object]{.type-label} *(required)* + - **`TemplateId`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`Value`** :span[object]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "ConcurrencyToken": "string", + "SpaceId": "string", + "TenantId": "string", + "Variables": [ + { + "Id": "string", + "OwnerId": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ] +} +``` +::: + +**Response** + +`200` — The project variables associated with a tenant. + +- **`ConcurrencyToken`** :span[string]{.type-label} + Minimum length 1. +- **`TenantId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Template`** :span[object]{.type-label} + - **`TemplateId`** :span[string]{.type-label} + Minimum length 1. + - **`Value`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConcurrencyToken": "string", + "TenantId": "string", + "Variables": [ + { + "Id": "string", + "ProjectId": "string", + "ProjectName": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "Template": { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ] +} +``` +::: + +## Create or Update the project variables associated with the tenant + +:endpoint{method="PUT" path="/api/spaces/\{spaceIdentifier\}/tenants/\{tenantId\}/projectvariables"} + +Also reachable at `/api/tenants/{tenantId}/projectvariables`. + +**Path Parameters** + +- **`spaceIdentifier`** :span[string]{.type-label} *(required)* + Identifier (ID or slug) of the space. +- **`tenantId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`ConcurrencyToken`** :span[string]{.type-label} + The concurrency token returned when reading the tenant's variables. Always pass it back so the write is rejected if someone else changed the variables since your read; omitting it skips the check and risks silently overwriting their changes. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`TenantId`** :span[string]{.type-label} *(required)* +- **`Variables`** :span[array of object]{.type-label} *(required)* + The complete set of project variable values for the tenant; existing values omitted here are deleted. Each item is an object: 'Id' (the existing value's ID when updating; omit when adding), 'OwnerId' (the project ID), 'TemplateId' (the variable template ID), 'Value' (a plain string for non-sensitive values, or {"HasValue": true, "NewValue": "secret"} for sensitive ones), and 'Scope' ({"EnvironmentIds": [...]} limiting the value to those environments; empty applies to all). + - **`Id`** :span[string]{.type-label} + - **`OwnerId`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`Scope`** :span[object]{.type-label} *(required)* + - **`TemplateId`** :span[string]{.type-label} *(required)* + Minimum length 1. + - **`Value`** :span[object]{.type-label} *(required)* + +:::api-example{label="Request"} +```json +{ + "ConcurrencyToken": "string", + "SpaceId": "string", + "TenantId": "string", + "Variables": [ + { + "Id": "string", + "OwnerId": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ] +} +``` +::: + +**Response** + +`200` — The project variables associated with a tenant. + +- **`ConcurrencyToken`** :span[string]{.type-label} + Minimum length 1. +- **`TenantId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + Minimum length 1. + - **`ProjectId`** :span[string]{.type-label} + - **`ProjectName`** :span[string]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Template`** :span[object]{.type-label} + - **`TemplateId`** :span[string]{.type-label} + Minimum length 1. + - **`Value`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "ConcurrencyToken": "string", + "TenantId": "string", + "Variables": [ + { + "Id": "string", + "ProjectId": "string", + "ProjectName": "string", + "Scope": { + "EnvironmentIds": [ + "string" + ] + }, + "Template": { + "DefaultValue": {}, + "DisplaySettings": {}, + "HelpText": "string", + "Id": "string", + "Label": "string", + "Name": "string" + }, + "TemplateId": "string", + "Value": { + "IsSensitive": true, + "SensitiveValue": {}, + "Value": "string" + } + } + ] +} +``` +::: + +## List all of the tenant variables in the supplied Octopus Deploy Space. The results will be sorted alphabetically by id + +:endpoint{method="GET" path="/api/\{spaceId\}/tenantvariables/all"} + +Also reachable at `/api/spaces/{spaceIdentifier}/tenantvariables/all`, `/api/tenantvariables/all`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`projectId`** :span[string]{.type-label} + ID of a project that tenants must be connected to, to be included in the result set. For matching tenants, variables from all projects are still returned. + +**Response** + +`200` — All of the tenant variables in the supplied Octopus Deploy Space (sorted alphabetically by id). + +- **`ConcurrencyToken`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LibraryVariables`** :span[object]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`ProjectVariables`** :span[object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`TenantId`** :span[string]{.type-label} +- **`TenantName`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "ConcurrencyToken": "string", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LibraryVariables": { + "additionalProp1": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": {}, + "Templates": [ + {} + ], + "Variables": {} + }, + "additionalProp2": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": {}, + "Templates": [ + {} + ], + "Variables": {} + }, + "additionalProp3": { + "LibraryVariableSetId": "string", + "LibraryVariableSetName": "string", + "Links": {}, + "Templates": [ + {} + ], + "Variables": {} + } + }, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ProjectVariables": { + "additionalProp1": { + "Links": {}, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": {} + }, + "additionalProp2": { + "Links": {}, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": {} + }, + "additionalProp3": { + "Links": {}, + "ProjectId": "string", + "ProjectName": "string", + "Templates": [ + {} + ], + "Variables": {} + } + }, + "SpaceId": "string", + "TenantId": "string", + "TenantName": "string" + } +] +``` +::: diff --git a/src/pages/docs/api/token-exchange.md b/src/pages/docs/api/token-exchange.md new file mode 100644 index 0000000000..abe648acd9 --- /dev/null +++ b/src/pages/docs/api/token-exchange.md @@ -0,0 +1,36 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Token Exchange +--- + +## Exchange an Oidc token for an access token that allows access to the API + +:endpoint{method="POST" path="/api/token/v1"} + +**Request Body** + +- **`audience`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`grant_type`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`subject_token`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`subject_token_type`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "audience": "string", + "grant_type": "string", + "subject_token": "string", + "subject_token_type": "string" +} +``` +::: + +**Response** + +`200` — OK diff --git a/src/pages/docs/api/upgrade.md b/src/pages/docs/api/upgrade.md new file mode 100644 index 0000000000..7c79e4dace --- /dev/null +++ b/src/pages/docs/api/upgrade.md @@ -0,0 +1,110 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Upgrade +--- + +## Get information about the upgrade configuration in use by the Octopus Server + +:endpoint{method="GET" path="/api/upgradeconfiguration"} + +**Response** + +`200` — The current upgrade configuration + +- **`AllowChecking`** :span[boolean]{.type-label} + Whether to check octopus.com to see if a new version is available. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IncludeStatistics`** :span[boolean]{.type-label} + Deprecated: please use the [dedicated telemetry page](" + OctoLink.BaseAddress + "telemetry) to determine whether octopus sends usage statistics. See [our documentation](" + OctoLink.BaseAddress + "WhatIsIncludedInUsageStatistics) for information about what is included. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NotificationMode`** :span[enum]{.type-label} + Controls which notifications are shown in the portal when an upgrade is available. + Allowed values: `AlwaysShow`, `ShowOnlyMajorMinor`, `NeverShow`. + +:::api-example{label="Response"} +```json +{ + "AllowChecking": true, + "Id": "string", + "IncludeStatistics": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NotificationMode": "AlwaysShow" +} +``` +::: + +## Update the upgrade configuration used by the Octopus Server + +:endpoint{method="PUT" path="/api/upgradeconfiguration"} + +**Request Body** + +- **`AllowChecking`** :span[boolean]{.type-label} *(required)* + Whether to check octopus.com to see if a new version is available. +- **`IncludeStatistics`** :span[boolean]{.type-label} *(required)* + Deprecated: please use the [dedicated telemetry page](https://oc.to/telemetry) to determine whether octopus sends usage statistics. See [our documentation](https://oc.to/WhatIsIncludedInUsageStatistics) for information about what is included. +- **`NotificationMode`** :span[enum]{.type-label} *(required)* + Controls which notifications are shown in the portal when an upgrade is available. + Allowed values: `AlwaysShow`, `ShowOnlyMajorMinor`, `NeverShow`. + +:::api-example{label="Request"} +```json +{ + "AllowChecking": true, + "IncludeStatistics": true, + "NotificationMode": "AlwaysShow" +} +``` +::: + +**Response** + +`200` — The updated upgrade configuration + +- **`AllowChecking`** :span[boolean]{.type-label} + Whether to check octopus.com to see if a new version is available. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IncludeStatistics`** :span[boolean]{.type-label} + Deprecated: please use the [dedicated telemetry page](" + OctoLink.BaseAddress + "telemetry) to determine whether octopus sends usage statistics. See [our documentation](" + OctoLink.BaseAddress + "WhatIsIncludedInUsageStatistics) for information about what is included. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NotificationMode`** :span[enum]{.type-label} + Controls which notifications are shown in the portal when an upgrade is available. + Allowed values: `AlwaysShow`, `ShowOnlyMajorMinor`, `NeverShow`. + +:::api-example{label="Response"} +```json +{ + "AllowChecking": true, + "Id": "string", + "IncludeStatistics": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NotificationMode": "AlwaysShow" +} +``` +::: diff --git a/src/pages/docs/api/user-permissions.md b/src/pages/docs/api/user-permissions.md new file mode 100644 index 0000000000..e4bd98a2c0 --- /dev/null +++ b/src/pages/docs/api/user-permissions.md @@ -0,0 +1,5197 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: User Permissions +--- + +## Get the user's permission information + +:endpoint{method="GET" path="/api/\{spaceId\}/users/\{id\}/permissions"} + +Also reachable at `/api/spaces/{spaceIdentifier}/users/{id}/permissions`, `/api/users/{id}/permissions`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the user. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space to get permissions for. + +**Query Parameters** + +- **`includeSystem`** :span[boolean]{.type-label} + Whether to include permission information from the system context. + +**Response** + +`200` — The user's exported permissions + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsPermissionsComplete`** :span[boolean]{.type-label} + If the requesting user had sufficient access to see a complete view of the permissions. +- **`IsTeamsComplete`** :span[boolean]{.type-label} + If the requesting user had sufficient access to see a complete view of the teams that may drive permissions. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`SpacePermissions`** :span[object]{.type-label} + Lists individual permissions granted, including restrictions where applicable. + - **`AccountCreate`** :span[array of object]{.type-label} + - **`AccountDelete`** :span[array of object]{.type-label} + - **`AccountEdit`** :span[array of object]{.type-label} + - **`AccountView`** :span[array of object]{.type-label} + - **`ActionTemplateCreate`** :span[array of object]{.type-label} + - **`ActionTemplateDelete`** :span[array of object]{.type-label} + - **`ActionTemplateEdit`** :span[array of object]{.type-label} + - **`ActionTemplateView`** :span[array of object]{.type-label} + - **`AdministerSystem`** :span[array of object]{.type-label} + - **`AiAgentTranscriptView`** :span[array of object]{.type-label} + - **`ApprovalPolicyAdminister`** :span[array of object]{.type-label} + - **`ArtifactCreate`** :span[array of object]{.type-label} + - **`ArtifactDelete`** :span[array of object]{.type-label} + - **`ArtifactEdit`** :span[array of object]{.type-label} + - **`ArtifactView`** :span[array of object]{.type-label} + - **`BuildInformationAdminister`** :span[array of object]{.type-label} + - **`BuildInformationPush`** :span[array of object]{.type-label} + - **`BuiltInFeedAdminister`** :span[array of object]{.type-label} + - **`BuiltInFeedDownload`** :span[array of object]{.type-label} + - **`BuiltInFeedPush`** :span[array of object]{.type-label} + - **`CertificateCreate`** :span[array of object]{.type-label} + - **`CertificateDelete`** :span[array of object]{.type-label} + - **`CertificateEdit`** :span[array of object]{.type-label} + - **`CertificateExportPrivateKey`** :span[array of object]{.type-label} + - **`CertificateView`** :span[array of object]{.type-label} + - **`ConfigureServer`** :span[array of object]{.type-label} + - **`DefectReport`** :span[array of object]{.type-label} + - **`DefectResolve`** :span[array of object]{.type-label} + - **`DeployedResourceAdminister`** :span[array of object]{.type-label} + - **`DeploymentCreate`** :span[array of object]{.type-label} + - **`DeploymentDelete`** :span[array of object]{.type-label} + - **`DeploymentFreezeAdminister`** :span[array of object]{.type-label} + - **`DeploymentView`** :span[array of object]{.type-label} + - **`EnvironmentCreate`** :span[array of object]{.type-label} + - **`EnvironmentDelete`** :span[array of object]{.type-label} + - **`EnvironmentEdit`** :span[array of object]{.type-label} + - **`EnvironmentView`** :span[array of object]{.type-label} + - **`EventRetentionDelete`** :span[array of object]{.type-label} + - **`EventRetentionView`** :span[array of object]{.type-label} + - **`EventView`** :span[array of object]{.type-label} + - **`FeatureToggleEdit`** :span[array of object]{.type-label} + - **`FeedEdit`** :span[array of object]{.type-label} + - **`FeedView`** :span[array of object]{.type-label} + - **`GitCredentialEdit`** :span[array of object]{.type-label} + - **`GitCredentialView`** :span[array of object]{.type-label} + - **`InsightsReportCreate`** :span[array of object]{.type-label} + - **`InsightsReportDelete`** :span[array of object]{.type-label} + - **`InsightsReportEdit`** :span[array of object]{.type-label} + - **`InsightsReportView`** :span[array of object]{.type-label} + - **`InterruptionSubmit`** :span[array of object]{.type-label} + - **`InterruptionView`** :span[array of object]{.type-label} + - **`InterruptionViewSubmitResponsible`** :span[array of object]{.type-label} + - **`LibraryVariableSetCreate`** :span[array of object]{.type-label} + - **`LibraryVariableSetDelete`** :span[array of object]{.type-label} + - **`LibraryVariableSetEdit`** :span[array of object]{.type-label} + - **`LibraryVariableSetView`** :span[array of object]{.type-label} + - **`LifecycleCreate`** :span[array of object]{.type-label} + - **`LifecycleDelete`** :span[array of object]{.type-label} + - **`LifecycleEdit`** :span[array of object]{.type-label} + - **`LifecycleView`** :span[array of object]{.type-label} + - **`MachineCreate`** :span[array of object]{.type-label} + - **`MachineDelete`** :span[array of object]{.type-label} + - **`MachineEdit`** :span[array of object]{.type-label} + - **`MachinePolicyCreate`** :span[array of object]{.type-label} + - **`MachinePolicyDelete`** :span[array of object]{.type-label} + - **`MachinePolicyEdit`** :span[array of object]{.type-label} + - **`MachinePolicyView`** :span[array of object]{.type-label} + - **`MachineView`** :span[array of object]{.type-label} + - **`PlatformHubEdit`** :span[array of object]{.type-label} + - **`PlatformHubView`** :span[array of object]{.type-label} + - **`ProcessEdit`** :span[array of object]{.type-label} + - **`ProcessView`** :span[array of object]{.type-label} + - **`ProjectCreate`** :span[array of object]{.type-label} + - **`ProjectDelete`** :span[array of object]{.type-label} + - **`ProjectEdit`** :span[array of object]{.type-label} + - **`ProjectGroupCreate`** :span[array of object]{.type-label} + - **`ProjectGroupDelete`** :span[array of object]{.type-label} + - **`ProjectGroupEdit`** :span[array of object]{.type-label} + - **`ProjectGroupView`** :span[array of object]{.type-label} + - **`ProjectView`** :span[array of object]{.type-label} + - **`ProxyCreate`** :span[array of object]{.type-label} + - **`ProxyDelete`** :span[array of object]{.type-label} + - **`ProxyEdit`** :span[array of object]{.type-label} + - **`ProxyView`** :span[array of object]{.type-label} + - **`ReleaseCreate`** :span[array of object]{.type-label} + - **`ReleaseDelete`** :span[array of object]{.type-label} + - **`ReleaseEdit`** :span[array of object]{.type-label} + - **`ReleaseView`** :span[array of object]{.type-label} + - **`RetentionAdminister`** :span[array of object]{.type-label} + - **`RunbookEdit`** :span[array of object]{.type-label} + - **`RunbookRunCreate`** :span[array of object]{.type-label} + - **`RunbookRunDelete`** :span[array of object]{.type-label} + - **`RunbookRunView`** :span[array of object]{.type-label} + - **`RunbookSnapshotCreate`** :span[array of object]{.type-label} + - **`RunbookView`** :span[array of object]{.type-label} + - **`SpaceCreate`** :span[array of object]{.type-label} + - **`SpaceDelete`** :span[array of object]{.type-label} + - **`SpaceEdit`** :span[array of object]{.type-label} + - **`SpaceView`** :span[array of object]{.type-label} + - **`SshKnownHostsAdminister`** :span[array of object]{.type-label} + - **`SshKnownHostsView`** :span[array of object]{.type-label} + - **`SubscriptionCreate`** :span[array of object]{.type-label} + - **`SubscriptionDelete`** :span[array of object]{.type-label} + - **`SubscriptionEdit`** :span[array of object]{.type-label} + - **`SubscriptionView`** :span[array of object]{.type-label} + - **`TagSetCreate`** :span[array of object]{.type-label} + - **`TagSetDelete`** :span[array of object]{.type-label} + - **`TagSetEdit`** :span[array of object]{.type-label} + - **`TargetTagAdminister`** :span[array of object]{.type-label} + - **`TargetTagView`** :span[array of object]{.type-label} + - **`TaskCancel`** :span[array of object]{.type-label} + - **`TaskCreate`** :span[array of object]{.type-label} + - **`TaskEdit`** :span[array of object]{.type-label} + - **`TaskPrioritize`** :span[array of object]{.type-label} + - **`TaskView`** :span[array of object]{.type-label} + - **`TeamCreate`** :span[array of object]{.type-label} + - **`TeamDelete`** :span[array of object]{.type-label} + - **`TeamEdit`** :span[array of object]{.type-label} + - **`TeamView`** :span[array of object]{.type-label} + - **`TelemetryView`** :span[array of object]{.type-label} + - **`TenantCreate`** :span[array of object]{.type-label} + - **`TenantDelete`** :span[array of object]{.type-label} + - **`TenantEdit`** :span[array of object]{.type-label} + - **`TenantView`** :span[array of object]{.type-label} + - **`TriggerCreate`** :span[array of object]{.type-label} + - **`TriggerDelete`** :span[array of object]{.type-label} + - **`TriggerEdit`** :span[array of object]{.type-label} + - **`TriggerView`** :span[array of object]{.type-label} + - **`UserEdit`** :span[array of object]{.type-label} + - **`UserInvite`** :span[array of object]{.type-label} + - **`UserRoleEdit`** :span[array of object]{.type-label} + - **`UserRoleView`** :span[array of object]{.type-label} + - **`UserView`** :span[array of object]{.type-label} + - **`VariableEdit`** :span[array of object]{.type-label} + - **`VariableEditUnscoped`** :span[array of object]{.type-label} + - **`VariableView`** :span[array of object]{.type-label} + - **`VariableViewUnscoped`** :span[array of object]{.type-label} + - **`WorkerEdit`** :span[array of object]{.type-label} + - **`WorkerView`** :span[array of object]{.type-label} +- **`SystemPermissions`** :span[array of enum]{.type-label} + Lists individual system permissions granted, these do not have restrictions. + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. +- **`Teams`** :span[array of object]{.type-label} + Gets the teams that the user is a member of. + - **`ExternalSecurityGroups`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsDirectlyAssigned`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "IsPermissionsComplete": true, + "IsTeamsComplete": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "SpacePermissions": { + "AccountCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "AccountDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "AccountEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "AccountView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ActionTemplateCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ActionTemplateDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ActionTemplateEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ActionTemplateView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "AdministerSystem": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "AiAgentTranscriptView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ApprovalPolicyAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ArtifactCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ArtifactDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ArtifactEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ArtifactView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "BuildInformationAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "BuildInformationPush": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "BuiltInFeedAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "BuiltInFeedDownload": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "BuiltInFeedPush": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "CertificateCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "CertificateDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "CertificateEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "CertificateExportPrivateKey": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "CertificateView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ConfigureServer": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "DefectReport": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "DefectResolve": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "DeployedResourceAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "DeploymentCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "DeploymentDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "DeploymentFreezeAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "DeploymentView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "EnvironmentCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "EnvironmentDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "EnvironmentEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "EnvironmentView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "EventRetentionDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "EventRetentionView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "EventView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "FeatureToggleEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "FeedEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "FeedView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "GitCredentialEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "GitCredentialView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "InsightsReportCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "InsightsReportDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "InsightsReportEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "InsightsReportView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "InterruptionSubmit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "InterruptionView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "InterruptionViewSubmitResponsible": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LibraryVariableSetCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LibraryVariableSetDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LibraryVariableSetEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LibraryVariableSetView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LifecycleCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LifecycleDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LifecycleEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LifecycleView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachineCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachineDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachineEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachinePolicyCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachinePolicyDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachinePolicyEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachinePolicyView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachineView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "PlatformHubEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "PlatformHubView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProcessEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProcessView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectGroupCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectGroupDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectGroupEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectGroupView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProxyCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProxyDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProxyEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProxyView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ReleaseCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ReleaseDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ReleaseEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ReleaseView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "RetentionAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "RunbookEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "RunbookRunCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "RunbookRunDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "RunbookRunView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "RunbookSnapshotCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "RunbookView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SpaceCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SpaceDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SpaceEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SpaceView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SshKnownHostsAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SshKnownHostsView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SubscriptionCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SubscriptionDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SubscriptionEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SubscriptionView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TagSetCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TagSetDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TagSetEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TargetTagAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TargetTagView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TaskCancel": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TaskCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TaskEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TaskPrioritize": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TaskView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TeamCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TeamDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TeamEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TeamView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TelemetryView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TenantCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TenantDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TenantEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TenantView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TriggerCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TriggerDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TriggerEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TriggerView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "UserEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "UserInvite": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "UserRoleEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "UserRoleView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "UserView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "VariableEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "VariableEditUnscoped": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "VariableView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "VariableViewUnscoped": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "WorkerEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "WorkerView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ] + }, + "SystemPermissions": [ + "AdministerSystem" + ], + "Teams": [ + { + "ExternalSecurityGroups": [ + {} + ], + "Id": "string", + "IsDirectlyAssigned": true, + "Name": "string", + "SpaceId": "string" + } + ] +} +``` +::: + +## Get the user's permission information + +:endpoint{method="GET" path="/api/\{spaceId\}/users/\{id\}/permissions/configuration"} + +Also reachable at `/api/spaces/{spaceIdentifier}/users/{id}/permissions/configuration`, `/api/users/{id}/permissions/configuration`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the user. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space to get permissions for. + +**Query Parameters** + +- **`apiKeyId`** :span[string]{.type-label} + When supplied, computes the permission set as it would apply through this existing API key. The key must belong to the user. +- **`includeSystem`** :span[boolean]{.type-label} + Whether to include permission information from the system context. +- **`previewReadOnly`** :span[boolean]{.type-label} + When supplied, previews the permission set of a hypothetical new API key with the given read-only flag. Mutually exclusive with ApiKeyId. + +**Response** + +`200` — The user's exported permissions + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsPermissionsComplete`** :span[boolean]{.type-label} + If the requesting user had sufficient access to see a complete view of the permissions. +- **`IsTeamsComplete`** :span[boolean]{.type-label} + If the requesting user had sufficient access to see a complete view of the teams that may drive permissions. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`SpacePermissions`** :span[object]{.type-label} + Lists individual permissions granted, including restrictions where applicable. + - **`AccountCreate`** :span[array of object]{.type-label} + - **`AccountDelete`** :span[array of object]{.type-label} + - **`AccountEdit`** :span[array of object]{.type-label} + - **`AccountView`** :span[array of object]{.type-label} + - **`ActionTemplateCreate`** :span[array of object]{.type-label} + - **`ActionTemplateDelete`** :span[array of object]{.type-label} + - **`ActionTemplateEdit`** :span[array of object]{.type-label} + - **`ActionTemplateView`** :span[array of object]{.type-label} + - **`AdministerSystem`** :span[array of object]{.type-label} + - **`AiAgentTranscriptView`** :span[array of object]{.type-label} + - **`ApprovalPolicyAdminister`** :span[array of object]{.type-label} + - **`ArtifactCreate`** :span[array of object]{.type-label} + - **`ArtifactDelete`** :span[array of object]{.type-label} + - **`ArtifactEdit`** :span[array of object]{.type-label} + - **`ArtifactView`** :span[array of object]{.type-label} + - **`BuildInformationAdminister`** :span[array of object]{.type-label} + - **`BuildInformationPush`** :span[array of object]{.type-label} + - **`BuiltInFeedAdminister`** :span[array of object]{.type-label} + - **`BuiltInFeedDownload`** :span[array of object]{.type-label} + - **`BuiltInFeedPush`** :span[array of object]{.type-label} + - **`CertificateCreate`** :span[array of object]{.type-label} + - **`CertificateDelete`** :span[array of object]{.type-label} + - **`CertificateEdit`** :span[array of object]{.type-label} + - **`CertificateExportPrivateKey`** :span[array of object]{.type-label} + - **`CertificateView`** :span[array of object]{.type-label} + - **`ConfigureServer`** :span[array of object]{.type-label} + - **`DefectReport`** :span[array of object]{.type-label} + - **`DefectResolve`** :span[array of object]{.type-label} + - **`DeployedResourceAdminister`** :span[array of object]{.type-label} + - **`DeploymentCreate`** :span[array of object]{.type-label} + - **`DeploymentDelete`** :span[array of object]{.type-label} + - **`DeploymentFreezeAdminister`** :span[array of object]{.type-label} + - **`DeploymentView`** :span[array of object]{.type-label} + - **`EnvironmentCreate`** :span[array of object]{.type-label} + - **`EnvironmentDelete`** :span[array of object]{.type-label} + - **`EnvironmentEdit`** :span[array of object]{.type-label} + - **`EnvironmentView`** :span[array of object]{.type-label} + - **`EventRetentionDelete`** :span[array of object]{.type-label} + - **`EventRetentionView`** :span[array of object]{.type-label} + - **`EventView`** :span[array of object]{.type-label} + - **`FeatureToggleEdit`** :span[array of object]{.type-label} + - **`FeedEdit`** :span[array of object]{.type-label} + - **`FeedView`** :span[array of object]{.type-label} + - **`GitCredentialEdit`** :span[array of object]{.type-label} + - **`GitCredentialView`** :span[array of object]{.type-label} + - **`InsightsReportCreate`** :span[array of object]{.type-label} + - **`InsightsReportDelete`** :span[array of object]{.type-label} + - **`InsightsReportEdit`** :span[array of object]{.type-label} + - **`InsightsReportView`** :span[array of object]{.type-label} + - **`InterruptionSubmit`** :span[array of object]{.type-label} + - **`InterruptionView`** :span[array of object]{.type-label} + - **`InterruptionViewSubmitResponsible`** :span[array of object]{.type-label} + - **`LibraryVariableSetCreate`** :span[array of object]{.type-label} + - **`LibraryVariableSetDelete`** :span[array of object]{.type-label} + - **`LibraryVariableSetEdit`** :span[array of object]{.type-label} + - **`LibraryVariableSetView`** :span[array of object]{.type-label} + - **`LifecycleCreate`** :span[array of object]{.type-label} + - **`LifecycleDelete`** :span[array of object]{.type-label} + - **`LifecycleEdit`** :span[array of object]{.type-label} + - **`LifecycleView`** :span[array of object]{.type-label} + - **`MachineCreate`** :span[array of object]{.type-label} + - **`MachineDelete`** :span[array of object]{.type-label} + - **`MachineEdit`** :span[array of object]{.type-label} + - **`MachinePolicyCreate`** :span[array of object]{.type-label} + - **`MachinePolicyDelete`** :span[array of object]{.type-label} + - **`MachinePolicyEdit`** :span[array of object]{.type-label} + - **`MachinePolicyView`** :span[array of object]{.type-label} + - **`MachineView`** :span[array of object]{.type-label} + - **`PlatformHubEdit`** :span[array of object]{.type-label} + - **`PlatformHubView`** :span[array of object]{.type-label} + - **`ProcessEdit`** :span[array of object]{.type-label} + - **`ProcessView`** :span[array of object]{.type-label} + - **`ProjectCreate`** :span[array of object]{.type-label} + - **`ProjectDelete`** :span[array of object]{.type-label} + - **`ProjectEdit`** :span[array of object]{.type-label} + - **`ProjectGroupCreate`** :span[array of object]{.type-label} + - **`ProjectGroupDelete`** :span[array of object]{.type-label} + - **`ProjectGroupEdit`** :span[array of object]{.type-label} + - **`ProjectGroupView`** :span[array of object]{.type-label} + - **`ProjectView`** :span[array of object]{.type-label} + - **`ProxyCreate`** :span[array of object]{.type-label} + - **`ProxyDelete`** :span[array of object]{.type-label} + - **`ProxyEdit`** :span[array of object]{.type-label} + - **`ProxyView`** :span[array of object]{.type-label} + - **`ReleaseCreate`** :span[array of object]{.type-label} + - **`ReleaseDelete`** :span[array of object]{.type-label} + - **`ReleaseEdit`** :span[array of object]{.type-label} + - **`ReleaseView`** :span[array of object]{.type-label} + - **`RetentionAdminister`** :span[array of object]{.type-label} + - **`RunbookEdit`** :span[array of object]{.type-label} + - **`RunbookRunCreate`** :span[array of object]{.type-label} + - **`RunbookRunDelete`** :span[array of object]{.type-label} + - **`RunbookRunView`** :span[array of object]{.type-label} + - **`RunbookSnapshotCreate`** :span[array of object]{.type-label} + - **`RunbookView`** :span[array of object]{.type-label} + - **`SpaceCreate`** :span[array of object]{.type-label} + - **`SpaceDelete`** :span[array of object]{.type-label} + - **`SpaceEdit`** :span[array of object]{.type-label} + - **`SpaceView`** :span[array of object]{.type-label} + - **`SshKnownHostsAdminister`** :span[array of object]{.type-label} + - **`SshKnownHostsView`** :span[array of object]{.type-label} + - **`SubscriptionCreate`** :span[array of object]{.type-label} + - **`SubscriptionDelete`** :span[array of object]{.type-label} + - **`SubscriptionEdit`** :span[array of object]{.type-label} + - **`SubscriptionView`** :span[array of object]{.type-label} + - **`TagSetCreate`** :span[array of object]{.type-label} + - **`TagSetDelete`** :span[array of object]{.type-label} + - **`TagSetEdit`** :span[array of object]{.type-label} + - **`TargetTagAdminister`** :span[array of object]{.type-label} + - **`TargetTagView`** :span[array of object]{.type-label} + - **`TaskCancel`** :span[array of object]{.type-label} + - **`TaskCreate`** :span[array of object]{.type-label} + - **`TaskEdit`** :span[array of object]{.type-label} + - **`TaskPrioritize`** :span[array of object]{.type-label} + - **`TaskView`** :span[array of object]{.type-label} + - **`TeamCreate`** :span[array of object]{.type-label} + - **`TeamDelete`** :span[array of object]{.type-label} + - **`TeamEdit`** :span[array of object]{.type-label} + - **`TeamView`** :span[array of object]{.type-label} + - **`TelemetryView`** :span[array of object]{.type-label} + - **`TenantCreate`** :span[array of object]{.type-label} + - **`TenantDelete`** :span[array of object]{.type-label} + - **`TenantEdit`** :span[array of object]{.type-label} + - **`TenantView`** :span[array of object]{.type-label} + - **`TriggerCreate`** :span[array of object]{.type-label} + - **`TriggerDelete`** :span[array of object]{.type-label} + - **`TriggerEdit`** :span[array of object]{.type-label} + - **`TriggerView`** :span[array of object]{.type-label} + - **`UserEdit`** :span[array of object]{.type-label} + - **`UserInvite`** :span[array of object]{.type-label} + - **`UserRoleEdit`** :span[array of object]{.type-label} + - **`UserRoleView`** :span[array of object]{.type-label} + - **`UserView`** :span[array of object]{.type-label} + - **`VariableEdit`** :span[array of object]{.type-label} + - **`VariableEditUnscoped`** :span[array of object]{.type-label} + - **`VariableView`** :span[array of object]{.type-label} + - **`VariableViewUnscoped`** :span[array of object]{.type-label} + - **`WorkerEdit`** :span[array of object]{.type-label} + - **`WorkerView`** :span[array of object]{.type-label} +- **`SystemPermissions`** :span[array of enum]{.type-label} + Lists individual system permissions granted, these do not have restrictions. + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. +- **`Teams`** :span[array of object]{.type-label} + Gets the teams that the user is a member of. + - **`ExternalSecurityGroups`** :span[array of object]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsDirectlyAssigned`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "IsPermissionsComplete": true, + "IsTeamsComplete": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "SpacePermissions": { + "AccountCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "AccountDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "AccountEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "AccountView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ActionTemplateCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ActionTemplateDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ActionTemplateEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ActionTemplateView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "AdministerSystem": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "AiAgentTranscriptView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ApprovalPolicyAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ArtifactCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ArtifactDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ArtifactEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ArtifactView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "BuildInformationAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "BuildInformationPush": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "BuiltInFeedAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "BuiltInFeedDownload": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "BuiltInFeedPush": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "CertificateCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "CertificateDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "CertificateEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "CertificateExportPrivateKey": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "CertificateView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ConfigureServer": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "DefectReport": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "DefectResolve": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "DeployedResourceAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "DeploymentCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "DeploymentDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "DeploymentFreezeAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "DeploymentView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "EnvironmentCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "EnvironmentDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "EnvironmentEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "EnvironmentView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "EventRetentionDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "EventRetentionView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "EventView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "FeatureToggleEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "FeedEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "FeedView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "GitCredentialEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "GitCredentialView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "InsightsReportCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "InsightsReportDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "InsightsReportEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "InsightsReportView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "InterruptionSubmit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "InterruptionView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "InterruptionViewSubmitResponsible": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LibraryVariableSetCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LibraryVariableSetDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LibraryVariableSetEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LibraryVariableSetView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LifecycleCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LifecycleDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LifecycleEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "LifecycleView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachineCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachineDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachineEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachinePolicyCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachinePolicyDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachinePolicyEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachinePolicyView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "MachineView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "PlatformHubEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "PlatformHubView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProcessEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProcessView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectGroupCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectGroupDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectGroupEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectGroupView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProjectView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProxyCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProxyDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProxyEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ProxyView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ReleaseCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ReleaseDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ReleaseEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "ReleaseView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "RetentionAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "RunbookEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "RunbookRunCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "RunbookRunDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "RunbookRunView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "RunbookSnapshotCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "RunbookView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SpaceCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SpaceDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SpaceEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SpaceView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SshKnownHostsAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SshKnownHostsView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SubscriptionCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SubscriptionDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SubscriptionEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "SubscriptionView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TagSetCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TagSetDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TagSetEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TargetTagAdminister": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TargetTagView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TaskCancel": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TaskCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TaskEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TaskPrioritize": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TaskView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TeamCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TeamDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TeamEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TeamView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TelemetryView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TenantCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TenantDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TenantEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TenantView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TriggerCreate": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TriggerDelete": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TriggerEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "TriggerView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "UserEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "UserInvite": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "UserRoleEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "UserRoleView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "UserView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "VariableEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "VariableEditUnscoped": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "VariableView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "VariableViewUnscoped": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "WorkerEdit": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ], + "WorkerView": [ + { + "RestrictedToEnvironmentIds": [ + "string" + ], + "RestrictedToProjectGroupIds": [ + "string" + ], + "RestrictedToProjectIds": [ + "string" + ], + "RestrictedToTenantIds": [ + "string" + ], + "SpaceId": "string" + } + ] + }, + "SystemPermissions": [ + "AdministerSystem" + ], + "Teams": [ + { + "ExternalSecurityGroups": [ + {} + ], + "Id": "string", + "IsDirectlyAssigned": true, + "Name": "string", + "SpaceId": "string" + } + ] +} +``` +::: + +## Get a list of permissions for the currently authenticated user + +:endpoint{method="GET" path="/api/\{spaceId\}/users/\{id\}/permissions/export"} + +Also reachable at `/api/spaces/{spaceIdentifier}/users/{id}/permissions/export`, `/api/users/{id}/permissions/export`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the user. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +:::api-example{label="Response"} +```json +"string" +``` +::: diff --git a/src/pages/docs/api/user-roles.md b/src/pages/docs/api/user-roles.md new file mode 100644 index 0000000000..a31071c56f --- /dev/null +++ b/src/pages/docs/api/user-roles.md @@ -0,0 +1,429 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: User Roles +--- + +## Get a list of User Roles + +:endpoint{method="GET" path="/api/userroles"} + +Lists all of the User Roles in the current Octopus Deploy instance. The results will be sorted alphabetically by name. + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + A list of User Role IDs, to limit the result to those with a particular ID. Example: ["UserRoles-1", "UserRoles-2"]. +- **`partialName`** :span[string]{.type-label} + A partial name, to limit the result to those with a name that includes the partial name. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Request list of user roles. + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`CanBeDeleted`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + - **`GrantedSpacePermissions`** :span[array of enum]{.type-label} + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. + - **`GrantedSystemPermissions`** :span[array of enum]{.type-label} + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + - **`SpacePermissionDescriptions`** :span[array of string]{.type-label} + - **`SupportedRestrictions`** :span[array of string]{.type-label} + - **`SystemPermissionDescriptions`** :span[array of string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "CanBeDeleted": true, + "Description": "string", + "GrantedSpacePermissions": [ + "AdministerSystem" + ], + "GrantedSystemPermissions": [ + "AdministerSystem" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpacePermissionDescriptions": [ + "string" + ], + "SupportedRestrictions": [ + "string" + ], + "SystemPermissionDescriptions": [ + "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 +} +``` +::: + +## Create a custom user role definition + +:endpoint{method="POST" path="/api/userroles"} + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`GrantedSpacePermissions`** :span[array of enum]{.type-label} + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. +- **`GrantedSystemPermissions`** :span[array of enum]{.type-label} + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. +- **`Name`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "GrantedSpacePermissions": [ + "AdministerSystem" + ], + "GrantedSystemPermissions": [ + "AdministerSystem" + ], + "Name": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`CanBeDeleted`** :span[boolean]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GrantedSpacePermissions`** :span[array of enum]{.type-label} + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. +- **`GrantedSystemPermissions`** :span[array of enum]{.type-label} + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`SpacePermissionDescriptions`** :span[array of string]{.type-label} +- **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`SystemPermissionDescriptions`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CanBeDeleted": true, + "Description": "string", + "GrantedSpacePermissions": [ + "AdministerSystem" + ], + "GrantedSystemPermissions": [ + "AdministerSystem" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpacePermissionDescriptions": [ + "string" + ], + "SupportedRestrictions": [ + "string" + ], + "SystemPermissionDescriptions": [ + "string" + ] +} +``` +::: + +## Get a list of User Roles + +:endpoint{method="GET" path="/api/userroles/all"} + +Lists all of the User Roles in the current Octopus Deploy instance. The results will be sorted alphabetically by name. + +**Response** + +`200` — The requested list of user roles. + +- **`CanBeDeleted`** :span[boolean]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GrantedSpacePermissions`** :span[array of enum]{.type-label} + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. +- **`GrantedSystemPermissions`** :span[array of enum]{.type-label} + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`SpacePermissionDescriptions`** :span[array of string]{.type-label} +- **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`SystemPermissionDescriptions`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "CanBeDeleted": true, + "Description": "string", + "GrantedSpacePermissions": [ + "AdministerSystem" + ], + "GrantedSystemPermissions": [ + "AdministerSystem" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpacePermissionDescriptions": [ + "string" + ], + "SupportedRestrictions": [ + "string" + ], + "SystemPermissionDescriptions": [ + "string" + ] + } +] +``` +::: + +## Get a User Role by ID + +:endpoint{method="GET" path="/api/userroles/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the UserRole to load. + +**Response** + +`200` — The requested user role. + +- **`CanBeDeleted`** :span[boolean]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GrantedSpacePermissions`** :span[array of enum]{.type-label} + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. +- **`GrantedSystemPermissions`** :span[array of enum]{.type-label} + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`SpacePermissionDescriptions`** :span[array of string]{.type-label} +- **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`SystemPermissionDescriptions`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CanBeDeleted": true, + "Description": "string", + "GrantedSpacePermissions": [ + "AdministerSystem" + ], + "GrantedSystemPermissions": [ + "AdministerSystem" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpacePermissionDescriptions": [ + "string" + ], + "SupportedRestrictions": [ + "string" + ], + "SystemPermissionDescriptions": [ + "string" + ] +} +``` +::: + +## Modify an existing User Role + +:endpoint{method="PUT" path="/api/userroles/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Id of the User Role to modify. + +**Request Body** + +- **`Description`** :span[string]{.type-label} +- **`GrantedSpacePermissions`** :span[array of enum]{.type-label} + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. +- **`GrantedSystemPermissions`** :span[array of enum]{.type-label} + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. +- **`Id`** :span[string]{.type-label} *(required)* + Id of the User Role to modify. +- **`Name`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "GrantedSpacePermissions": [ + "AdministerSystem" + ], + "GrantedSystemPermissions": [ + "AdministerSystem" + ], + "Id": "string", + "Name": "string" +} +``` +::: + +**Response** + +`200` — Successful modify operation. + +- **`CanBeDeleted`** :span[boolean]{.type-label} +- **`Description`** :span[string]{.type-label} +- **`GrantedSpacePermissions`** :span[array of enum]{.type-label} + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. +- **`GrantedSystemPermissions`** :span[array of enum]{.type-label} + Allowed values: `AdministerSystem`, `ProjectEdit`, `ProjectView`, `ProjectCreate`, `ProjectDelete`, `ProcessView`, `ProcessEdit`, `VariableEdit`, `VariableEditUnscoped`, `VariableView`, `VariableViewUnscoped`, `ReleaseCreate`, `ReleaseView`, `ReleaseEdit`, `ReleaseDelete`, `DefectReport`, `DefectResolve`, `DeploymentCreate`, `DeploymentDelete`, `DeploymentView`, `EnvironmentView`, `EnvironmentCreate`, `EnvironmentEdit`, `EnvironmentDelete`, `MachineCreate`, `MachineEdit`, `MachineView`, `MachineDelete`, `ArtifactView`, `ArtifactCreate`, `ArtifactEdit`, `ArtifactDelete`, `FeedView`, `EventView`, `LibraryVariableSetView`, `LibraryVariableSetCreate`, `LibraryVariableSetEdit`, `LibraryVariableSetDelete`, `ProjectGroupView`, `ProjectGroupCreate`, `ProjectGroupEdit`, `ProjectGroupDelete`, `TeamCreate`, `TeamView`, `TeamEdit`, `TeamDelete`, `UserView`, `UserInvite`, `UserRoleView`, `UserRoleEdit`, `TaskView`, `TaskCreate`, `TaskCancel`, `TaskEdit`, `TaskPrioritize`, `InterruptionView`, `InterruptionSubmit`, `InterruptionViewSubmitResponsible`, `BuiltInFeedPush`, `BuiltInFeedAdminister`, `BuiltInFeedDownload`, `ActionTemplateView`, `ActionTemplateCreate`, `ActionTemplateEdit`, `ActionTemplateDelete`, `LifecycleCreate`, `LifecycleView`, `LifecycleEdit`, `LifecycleDelete`, `AccountView`, `AccountEdit`, `AccountCreate`, `AccountDelete`, `TenantCreate`, `TenantEdit`, `TenantView`, `TenantDelete`, `TagSetCreate`, `TagSetEdit`, `TagSetDelete`, `TelemetryView`, `MachinePolicyCreate`, `MachinePolicyView`, `MachinePolicyEdit`, `MachinePolicyDelete`, `ProxyCreate`, `ProxyView`, `ProxyEdit`, `ProxyDelete`, `SubscriptionCreate`, `SubscriptionView`, `SubscriptionEdit`, `SubscriptionDelete`, `TriggerCreate`, `TriggerView`, `TriggerEdit`, `TriggerDelete`, `CertificateView`, `CertificateCreate`, `CertificateEdit`, `CertificateDelete`, `CertificateExportPrivateKey`, `UserEdit`, `ConfigureServer`, `FeedEdit`, `WorkerView`, `WorkerEdit`, `SpaceEdit`, `SpaceView`, `SpaceDelete`, `SpaceCreate`, `BuildInformationPush`, `BuildInformationAdminister`, `RunbookView`, `RunbookEdit`, `RunbookSnapshotCreate`, `RunbookRunView`, `RunbookRunDelete`, `RunbookRunCreate`, `GitCredentialView`, `GitCredentialEdit`, `EventRetentionDelete`, `EventRetentionView`, `InsightsReportView`, `InsightsReportCreate`, `InsightsReportEdit`, `InsightsReportDelete`, `DeploymentFreezeAdminister`, `TargetTagView`, `TargetTagAdminister`, `PlatformHubView`, `PlatformHubEdit`, `RetentionAdminister`, `FeatureToggleEdit`, `ApprovalPolicyAdminister`, `SshKnownHostsAdminister`, `SshKnownHostsView`, `AiAgentTranscriptView`, `DeployedResourceAdminister`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} +- **`SpacePermissionDescriptions`** :span[array of string]{.type-label} +- **`SupportedRestrictions`** :span[array of string]{.type-label} +- **`SystemPermissionDescriptions`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CanBeDeleted": true, + "Description": "string", + "GrantedSpacePermissions": [ + "AdministerSystem" + ], + "GrantedSystemPermissions": [ + "AdministerSystem" + ], + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "SpacePermissionDescriptions": [ + "string" + ], + "SupportedRestrictions": [ + "string" + ], + "SystemPermissionDescriptions": [ + "string" + ] +} +``` +::: + +## Delete an existing User Role + +:endpoint{method="DELETE" path="/api/userroles/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the User Role to delete. + +**Response** + +`200` — Success diff --git a/src/pages/docs/api/users.md b/src/pages/docs/api/users.md new file mode 100644 index 0000000000..007201af15 --- /dev/null +++ b/src/pages/docs/api/users.md @@ -0,0 +1,944 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Users +--- + +## Get a list of Users + +:endpoint{method="GET" path="/api/users"} + +Lists all of the Users in the current Octopus Deploy instance, from all Teams. The results will be sorted alphabetically by username. + +**Query Parameters** + +- **`filter`** :span[string]{.type-label} + Filters the Users by Username/DisplayName/EmailAddress/IdentificationToken using the specified `filter` fragment. +- **`isActive`** :span[boolean]{.type-label} + A filter to return only active (true) or disabled (false) users. Omit to return both. +- **`isServiceAccount`** :span[boolean]{.type-label} + A filter to return only service account users. +- **`serviceAccountType`** :span[enum]{.type-label} + A filter to return only service accounts of the specified type. + Allowed values: `Standard`, `Agent`. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. + +**Response** + +`200` — Users that meet the filter conditions + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`CanPasswordBeEdited`** :span[boolean]{.type-label} + - **`Created`** :span[string]{.type-label} + Format `date-time`. + - **`DisplayName`** :span[string]{.type-label} + Maximum length 64. + - **`EmailAddress`** :span[string]{.type-label} + Format `email`. Maximum length 256. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`Identities`** :span[array of object]{.type-label} + - **`IsActive`** :span[boolean]{.type-label} + - **`IsRequestor`** :span[boolean]{.type-label} + Gets or sets a value indicating whether this user resource represents the user who requested it. + - **`IsService`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Password`** :span[string]{.type-label} + - **`ServiceAccountType`** :span[enum]{.type-label} + Allowed values: `Standard`, `Agent`. + - **`Username`** :span[string]{.type-label} + Maximum length 64. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "CanPasswordBeEdited": true, + "Created": "2020-01-01T00:00:00.000Z", + "DisplayName": "string", + "EmailAddress": "user@example.com", + "Id": "string", + "Identities": [ + {} + ], + "IsActive": true, + "IsRequestor": true, + "IsService": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Password": "string", + "ServiceAccountType": "Standard", + "Username": "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 +} +``` +::: + +## Create a new user + +:endpoint{method="POST" path="/api/users"} + +**Request Body** + +- **`DisplayName`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`EmailAddress`** :span[string]{.type-label} +- **`Identities`** :span[array of object]{.type-label} + - **`Claims`** :span[object]{.type-label} + - **`IdentityProviderName`** :span[string]{.type-label} +- **`IsActive`** :span[boolean]{.type-label} +- **`IsService`** :span[boolean]{.type-label} +- **`Password`** :span[string]{.type-label} +- **`ServiceAccountType`** :span[enum]{.type-label} + Allowed values: `Standard`, `Agent`. +- **`Username`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "DisplayName": "string", + "EmailAddress": "string", + "Identities": [ + { + "Claims": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "IdentityProviderName": "string" + } + ], + "IsActive": true, + "IsService": true, + "Password": "string", + "ServiceAccountType": "Standard", + "Username": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`CanPasswordBeEdited`** :span[boolean]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DisplayName`** :span[string]{.type-label} + Maximum length 64. +- **`EmailAddress`** :span[string]{.type-label} + Format `email`. Maximum length 256. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`Identities`** :span[array of object]{.type-label} + - **`Claims`** :span[object]{.type-label} + - **`IdentityProviderName`** :span[string]{.type-label} +- **`IsActive`** :span[boolean]{.type-label} +- **`IsRequestor`** :span[boolean]{.type-label} + Gets or sets a value indicating whether this user resource represents the user who requested it. +- **`IsService`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Password`** :span[string]{.type-label} +- **`ServiceAccountType`** :span[enum]{.type-label} + Allowed values: `Standard`, `Agent`. +- **`Username`** :span[string]{.type-label} + Maximum length 64. + +:::api-example{label="Response"} +```json +{ + "CanPasswordBeEdited": true, + "Created": "2020-01-01T00:00:00.000Z", + "DisplayName": "string", + "EmailAddress": "user@example.com", + "Id": "string", + "Identities": [ + { + "Claims": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "IdentityProviderName": "string" + } + ], + "IsActive": true, + "IsRequestor": true, + "IsService": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Password": "string", + "ServiceAccountType": "Standard", + "Username": "string" +} +``` +::: + +## Get a list of Users + +:endpoint{method="GET" path="/api/users/all"} + +Lists all the Users in the System. The results will be sorted alphabetically by `Username`. + +**Response** + +`200` — A list of all the users + +- **`CanPasswordBeEdited`** :span[boolean]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DisplayName`** :span[string]{.type-label} + Maximum length 64. +- **`EmailAddress`** :span[string]{.type-label} + Format `email`. Maximum length 256. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`Identities`** :span[array of object]{.type-label} + - **`Claims`** :span[object]{.type-label} + - **`IdentityProviderName`** :span[string]{.type-label} +- **`IsActive`** :span[boolean]{.type-label} +- **`IsRequestor`** :span[boolean]{.type-label} + Gets or sets a value indicating whether this user resource represents the user who requested it. +- **`IsService`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Password`** :span[string]{.type-label} +- **`ServiceAccountType`** :span[enum]{.type-label} + Allowed values: `Standard`, `Agent`. +- **`Username`** :span[string]{.type-label} + Maximum length 64. + +:::api-example{label="Response"} +```json +[ + { + "CanPasswordBeEdited": true, + "Created": "2020-01-01T00:00:00.000Z", + "DisplayName": "string", + "EmailAddress": "user@example.com", + "Id": "string", + "Identities": [ + { + "Claims": {}, + "IdentityProviderName": "string" + } + ], + "IsActive": true, + "IsRequestor": true, + "IsService": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Password": "string", + "ServiceAccountType": "Standard", + "Username": "string" + } +] +``` +::: + +## Provide the details of the enabled authentication providers and whether the current user can edit logins for the given user + +:endpoint{method="GET" path="/api/users/authentication/\{userId\}"} + +Also reachable at `/api/users/authentication`. + +**Path Parameters** + +- **`userId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The currently enabled authentication providers + +- **`AuthenticationProviders`** :span[array of object]{.type-label} + - **`CSSLinks`** :span[array of string]{.type-label} + - **`DisplayName`** :span[string]{.type-label} + - **`FormsLoginEnabled`** :span[boolean]{.type-label} + - **`IdentityType`** :span[enum]{.type-label} + Allowed values: `Guest`, `UsernamePassword`, `ActiveDirectory`, `OAuth`. + - **`JavascriptLinks`** :span[array of string]{.type-label} + - **`Links`** :span[object]{.type-label} + - **`Name`** :span[string]{.type-label} +- **`CanCurrentUserEditIdentitiesForUser`** :span[boolean]{.type-label} +- **`Links`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "AuthenticationProviders": [ + { + "CSSLinks": [ + "string" + ], + "DisplayName": "string", + "FormsLoginEnabled": true, + "IdentityType": "Guest", + "JavascriptLinks": [ + "string" + ], + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string" + } + ], + "CanCurrentUserEditIdentitiesForUser": true, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` +::: + +## Search for users, using the authentication providers + +:endpoint{method="GET" path="/api/users/external-search"} + +**Query Parameters** + +- **`partialName`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The results of the external user provider search + +- **`Links`** :span[object]{.type-label} +- **`Results`** :span[array of object]{.type-label} + - **`Identities`** :span[array of object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Results": [ + { + "Identities": [ + {} + ] + } + ] +} +``` +::: + +## Get the metadata to describe the claims/fields used by authentication providers that support identities + +:endpoint{method="GET" path="/api/users/identity-metadata"} + +**Response** + +`200` — The user identity metadata + +- **`Links`** :span[object]{.type-label} +- **`Providers`** :span[array of object]{.type-label} + - **`ClaimDescriptors`** :span[array of object]{.type-label} + - **`IdentityProviderName`** :span[string]{.type-label} + - **`Links`** :span[object]{.type-label} + - **`ScimEnabled`** :span[boolean]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Providers": [ + { + "ClaimDescriptors": [ + {} + ], + "IdentityProviderName": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "ScimEnabled": true + } + ] +} +``` +::: + +## Log in + +:endpoint{method="POST" path="/api/users/login"} + +**Request Body** + +- **`Password`** :span[string]{.type-label} *(required)* + The password to log in with. Minimum length 1. +- **`RememberMe`** :span[boolean]{.type-label} + Whether the cookie should be persistent. +- **`RemoteIpAddress`** :span[string]{.type-label} + IP Address of the user. +- **`State`** :span[object]{.type-label} + - **`RedirectAfterLoginTo`** :span[string]{.type-label} + The Url, relative to the portal site, to redirect to post successful login. + - **`UsingSecureConnection`** :span[boolean]{.type-label} + Whether the client says it's using a secure connection. We need this because SSL offloading can obscure this and the server cannot tell whether the client initiated the call using a secure connection. +- **`Username`** :span[string]{.type-label} *(required)* + The username to log in with. Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "Password": "string", + "RememberMe": true, + "RemoteIpAddress": "string", + "State": { + "RedirectAfterLoginTo": "string", + "UsingSecureConnection": true + }, + "Username": "string" +} +``` +::: + +**Response** + +`200` — The details of a successful login + +- **`CanPasswordBeEdited`** :span[boolean]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DisplayName`** :span[string]{.type-label} + Maximum length 64. +- **`EmailAddress`** :span[string]{.type-label} + Format `email`. Maximum length 256. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`Identities`** :span[array of object]{.type-label} + - **`Claims`** :span[object]{.type-label} + - **`IdentityProviderName`** :span[string]{.type-label} +- **`IsActive`** :span[boolean]{.type-label} +- **`IsRequestor`** :span[boolean]{.type-label} + Gets or sets a value indicating whether this user resource represents the user who requested it. +- **`IsService`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Password`** :span[string]{.type-label} +- **`ServiceAccountType`** :span[enum]{.type-label} + Allowed values: `Standard`, `Agent`. +- **`Username`** :span[string]{.type-label} + Maximum length 64. + +:::api-example{label="Response"} +```json +{ + "CanPasswordBeEdited": true, + "Created": "2020-01-01T00:00:00.000Z", + "DisplayName": "string", + "EmailAddress": "user@example.com", + "Id": "string", + "Identities": [ + { + "Claims": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "IdentityProviderName": "string" + } + ], + "IsActive": true, + "IsRequestor": true, + "IsService": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Password": "string", + "ServiceAccountType": "Standard", + "Username": "string" +} +``` +::: + +## POST /api/users/logout + +:endpoint{method="POST" path="/api/users/logout"} + +Logs out the current user. + +**Response** + +`200` — Success + +## Get information about the current user + +:endpoint{method="GET" path="/api/users/me"} + +**Response** + +`200` — The current user's details + +- **`CanPasswordBeEdited`** :span[boolean]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DisplayName`** :span[string]{.type-label} + Maximum length 64. +- **`EmailAddress`** :span[string]{.type-label} + Format `email`. Maximum length 256. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`Identities`** :span[array of object]{.type-label} + - **`Claims`** :span[object]{.type-label} + - **`IdentityProviderName`** :span[string]{.type-label} +- **`IsActive`** :span[boolean]{.type-label} +- **`IsRequestor`** :span[boolean]{.type-label} + Gets or sets a value indicating whether this user resource represents the user who requested it. +- **`IsService`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Password`** :span[string]{.type-label} +- **`ServiceAccountType`** :span[enum]{.type-label} + Allowed values: `Standard`, `Agent`. +- **`Username`** :span[string]{.type-label} + Maximum length 64. + +:::api-example{label="Response"} +```json +{ + "CanPasswordBeEdited": true, + "Created": "2020-01-01T00:00:00.000Z", + "DisplayName": "string", + "EmailAddress": "user@example.com", + "Id": "string", + "Identities": [ + { + "Claims": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "IdentityProviderName": "string" + } + ], + "IsActive": true, + "IsRequestor": true, + "IsService": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Password": "string", + "ServiceAccountType": "Standard", + "Username": "string" +} +``` +::: + +## Register a new user and responds with an authentication cookie. Unless the first administrator user is being registered, an invitation code must be provided + +:endpoint{method="POST" path="/api/users/register"} + +**Request Body** + +- **`DisplayName`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`EmailAddress`** :span[string]{.type-label} +- **`Identities`** :span[array of object]{.type-label} + - **`Claims`** :span[object]{.type-label} + - **`IdentityProviderName`** :span[string]{.type-label} +- **`InvitationCode`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Password`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`Username`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "DisplayName": "string", + "EmailAddress": "string", + "Identities": [ + { + "Claims": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "IdentityProviderName": "string" + } + ], + "InvitationCode": "string", + "Password": "string", + "Username": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`CanPasswordBeEdited`** :span[boolean]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DisplayName`** :span[string]{.type-label} + Maximum length 64. +- **`EmailAddress`** :span[string]{.type-label} + Format `email`. Maximum length 256. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`Identities`** :span[array of object]{.type-label} + - **`Claims`** :span[object]{.type-label} + - **`IdentityProviderName`** :span[string]{.type-label} +- **`IsActive`** :span[boolean]{.type-label} +- **`IsRequestor`** :span[boolean]{.type-label} + Gets or sets a value indicating whether this user resource represents the user who requested it. +- **`IsService`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Password`** :span[string]{.type-label} +- **`ServiceAccountType`** :span[enum]{.type-label} + Allowed values: `Standard`, `Agent`. +- **`Username`** :span[string]{.type-label} + Maximum length 64. + +:::api-example{label="Response"} +```json +{ + "CanPasswordBeEdited": true, + "Created": "2020-01-01T00:00:00.000Z", + "DisplayName": "string", + "EmailAddress": "user@example.com", + "Id": "string", + "Identities": [ + { + "Claims": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "IdentityProviderName": "string" + } + ], + "IsActive": true, + "IsRequestor": true, + "IsService": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Password": "string", + "ServiceAccountType": "Standard", + "Username": "string" +} +``` +::: + +## Get a User by ID + +:endpoint{method="GET" path="/api/users/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the User to load. + +**Response** + +`200` — The user details + +- **`CanPasswordBeEdited`** :span[boolean]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DisplayName`** :span[string]{.type-label} + Maximum length 64. +- **`EmailAddress`** :span[string]{.type-label} + Format `email`. Maximum length 256. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`Identities`** :span[array of object]{.type-label} + - **`Claims`** :span[object]{.type-label} + - **`IdentityProviderName`** :span[string]{.type-label} +- **`IsActive`** :span[boolean]{.type-label} +- **`IsRequestor`** :span[boolean]{.type-label} + Gets or sets a value indicating whether this user resource represents the user who requested it. +- **`IsService`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Password`** :span[string]{.type-label} +- **`ServiceAccountType`** :span[enum]{.type-label} + Allowed values: `Standard`, `Agent`. +- **`Username`** :span[string]{.type-label} + Maximum length 64. + +:::api-example{label="Response"} +```json +{ + "CanPasswordBeEdited": true, + "Created": "2020-01-01T00:00:00.000Z", + "DisplayName": "string", + "EmailAddress": "user@example.com", + "Id": "string", + "Identities": [ + { + "Claims": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "IdentityProviderName": "string" + } + ], + "IsActive": true, + "IsRequestor": true, + "IsService": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Password": "string", + "ServiceAccountType": "Standard", + "Username": "string" +} +``` +::: + +## Modify an existing user + +:endpoint{method="PUT" path="/api/users/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`DisplayName`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`EmailAddress`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} *(required)* +- **`Identities`** :span[array of object]{.type-label} + - **`Claims`** :span[object]{.type-label} + - **`IdentityProviderName`** :span[string]{.type-label} +- **`IsActive`** :span[boolean]{.type-label} *(required)* +- **`Password`** :span[string]{.type-label} +- **`Username`** :span[string]{.type-label} *(required)* + Minimum length 1. + +:::api-example{label="Request"} +```json +{ + "DisplayName": "string", + "EmailAddress": "string", + "Id": "string", + "Identities": [ + { + "Claims": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "IdentityProviderName": "string" + } + ], + "IsActive": true, + "Password": "string", + "Username": "string" +} +``` +::: + +**Response** + +`200` — The updated user + +- **`CanPasswordBeEdited`** :span[boolean]{.type-label} +- **`Created`** :span[string]{.type-label} + Format `date-time`. +- **`DisplayName`** :span[string]{.type-label} + Maximum length 64. +- **`EmailAddress`** :span[string]{.type-label} + Format `email`. Maximum length 256. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`Identities`** :span[array of object]{.type-label} + - **`Claims`** :span[object]{.type-label} + - **`IdentityProviderName`** :span[string]{.type-label} +- **`IsActive`** :span[boolean]{.type-label} +- **`IsRequestor`** :span[boolean]{.type-label} + Gets or sets a value indicating whether this user resource represents the user who requested it. +- **`IsService`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Password`** :span[string]{.type-label} +- **`ServiceAccountType`** :span[enum]{.type-label} + Allowed values: `Standard`, `Agent`. +- **`Username`** :span[string]{.type-label} + Maximum length 64. + +:::api-example{label="Response"} +```json +{ + "CanPasswordBeEdited": true, + "Created": "2020-01-01T00:00:00.000Z", + "DisplayName": "string", + "EmailAddress": "user@example.com", + "Id": "string", + "Identities": [ + { + "Claims": { + "additionalProp1": {}, + "additionalProp2": {}, + "additionalProp3": {} + }, + "IdentityProviderName": "string" + } + ], + "IsActive": true, + "IsRequestor": true, + "IsService": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Password": "string", + "ServiceAccountType": "Standard", + "Username": "string" +} +``` +::: + +## Delete an existing User + +:endpoint{method="DELETE" path="/api/users/\{id\}"} + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the user to delete. + +**Response** + +`200` — Success + +## Revoke all sessions for a user + +:endpoint{method="PUT" path="/api/users/\{userId\}/revoke-sessions"} + +**Path Parameters** + +- **`userId`** :span[string]{.type-label} *(required)* + ID of the User to revoke. + +**Response** + +`200` — Empty response, indicating the sessions have been revoked + +:::api-example{label="Response"} +```json +{} +``` +::: diff --git a/src/pages/docs/api/variables.md b/src/pages/docs/api/variables.md new file mode 100644 index 0000000000..6a86f52381 --- /dev/null +++ b/src/pages/docs/api/variables.md @@ -0,0 +1,1993 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Variables +--- + +## Return a summary of the variables that will be migrated to Git + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/git/migrate-variables"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/migrate-variables`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + Id of the project to convert. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Confirmation that the requested Project Variables were converted to git + +- **`SensitiveVariableCount`** :span[integer]{.type-label} +- **`TextVariableCount`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "SensitiveVariableCount": 0, + "TextVariableCount": 0 +} +``` +::: + +## Convert all non-sensitive project variables to be stored in Git rather than the database + +:endpoint{method="POST" path="/api/\{spaceId\}/projects/\{projectId\}/git/migrate-variables"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/git/migrate-variables`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Branch`** :span[string]{.type-label} *(required)* +- **`CommitMessage`** :span[string]{.type-label} *(required)* + Minimum length 1. +- **`CreateBranch`** :span[boolean]{.type-label} +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +:::api-example{label="Request"} +```json +{ + "Branch": "string", + "CommitMessage": "string", + "CreateBranch": true, + "ProjectId": "string", + "SpaceId": "string" +} +``` +::: + +**Response** + +`200` — Empty response indicating the Project Variables were converted + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get variables for a project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/variables"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/variables`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Project Variable Set + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`OwnerId`** :span[string]{.type-label} + Gets or sets the ID of the document that owns these variables. +- **`ScopeValues`** :span[object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Channels`** :span[array of object]{.type-label} + - **`EnvironmentParameters`** :span[array of object]{.type-label} + - **`Environments`** :span[array of object]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`ProcessTemplateSteps`** :span[array of object]{.type-label} + - **`Processes`** :span[array of object]{.type-label} + - **`Roles`** :span[array of object]{.type-label} + - **`TargetTagParameters`** :span[array of object]{.type-label} + - **`TenantTagParameters`** :span[array of object]{.type-label} + - **`TenantTags`** :span[array of object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + Gets the collection of variables. + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsEditable`** :span[boolean]{.type-label} + - **`IsSensitive`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Prompt`** :span[object]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Type`** :span[string]{.type-label} + - **`Value`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "OwnerId": "string", + "ScopeValues": { + "Actions": [ + { + "Id": "string", + "Name": "string" + } + ], + "Channels": [ + { + "Id": "string", + "Name": "string" + } + ], + "EnvironmentParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "Environments": [ + { + "Id": "string", + "Name": "string" + } + ], + "Machines": [ + { + "Id": "string", + "Name": "string" + } + ], + "ProcessTemplateSteps": [ + { + "Id": "string", + "Name": "string" + } + ], + "Processes": [ + { + "Id": "string", + "Name": "string", + "ProcessType": "Deployment" + } + ], + "Roles": [ + { + "Id": "string", + "Name": "string" + } + ], + "TargetTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTags": [ + { + "Id": "string", + "Name": "string" + } + ] + }, + "SpaceId": "string", + "Variables": [ + { + "Description": "string", + "Id": "string", + "IsEditable": true, + "IsSensitive": true, + "Name": "string", + "Prompt": { + "Description": "string", + "DisplaySettings": {}, + "Label": "string", + "Required": true + }, + "Scope": { + "Action": [ + "string" + ], + "Channel": [ + "string" + ], + "Environment": [ + "string" + ], + "EnvironmentParameter": [ + "string" + ], + "Machine": [ + "string" + ], + "ParentDeployment": [ + "string" + ], + "Private": [ + "string" + ], + "ProcessOwner": [ + "string" + ], + "ProcessTemplateStep": [ + "string" + ], + "Project": [ + "string" + ], + "ProjectTemplate": [ + "string" + ], + "Role": [ + "string" + ], + "TargetRole": [ + "string" + ], + "TargetTagParameter": [ + "string" + ], + "TemplatedProject": [ + "string" + ], + "Tenant": [ + "string" + ], + "TenantTag": [ + "string" + ], + "TenantTagParameter": [ + "string" + ], + "Trigger": [ + "string" + ], + "User": [ + "string" + ] + }, + "Type": "string", + "Value": "string" + } + ], + "Version": 0 +} +``` +::: + +## Modify variables for the project + +:endpoint{method="PUT" path="/api/\{spaceId\}/projects/\{projectId\}/variables"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/variables`. + +**Path Parameters** + +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`ChangeDescription`** :span[string]{.type-label} +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`ScopeValues`** :span[object]{.type-label} *(required)* + - **`Actions`** :span[array of object]{.type-label} + - **`Channels`** :span[array of object]{.type-label} + - **`EnvironmentParameters`** :span[array of object]{.type-label} + - **`Environments`** :span[array of object]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`ProcessTemplateSteps`** :span[array of object]{.type-label} + - **`Processes`** :span[array of object]{.type-label} + - **`Roles`** :span[array of object]{.type-label} + - **`TargetTagParameters`** :span[array of object]{.type-label} + - **`TenantTagParameters`** :span[array of object]{.type-label} + - **`TenantTags`** :span[array of object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`Variables`** :span[array of object]{.type-label} *(required)* + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsEditable`** :span[boolean]{.type-label} + - **`IsSensitive`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Prompt`** :span[object]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Type`** :span[string]{.type-label} + - **`Value`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Request"} +```json +{ + "ChangeDescription": "string", + "ProjectId": "string", + "ScopeValues": { + "Actions": [ + { + "Id": "string", + "Name": "string" + } + ], + "Channels": [ + { + "Id": "string", + "Name": "string" + } + ], + "EnvironmentParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "Environments": [ + { + "Id": "string", + "Name": "string" + } + ], + "Machines": [ + { + "Id": "string", + "Name": "string" + } + ], + "ProcessTemplateSteps": [ + { + "Id": "string", + "Name": "string" + } + ], + "Processes": [ + { + "Id": "string", + "Name": "string", + "ProcessType": "Deployment" + } + ], + "Roles": [ + { + "Id": "string", + "Name": "string" + } + ], + "TargetTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTags": [ + { + "Id": "string", + "Name": "string" + } + ] + }, + "SpaceId": "string", + "Variables": [ + { + "Description": "string", + "Id": "string", + "IsEditable": true, + "IsSensitive": true, + "Name": "string", + "Prompt": { + "Description": "string", + "DisplaySettings": {}, + "Label": "string", + "Required": true + }, + "Scope": { + "Action": [ + "string" + ], + "Channel": [ + "string" + ], + "Environment": [ + "string" + ], + "EnvironmentParameter": [ + "string" + ], + "Machine": [ + "string" + ], + "ParentDeployment": [ + "string" + ], + "Private": [ + "string" + ], + "ProcessOwner": [ + "string" + ], + "ProcessTemplateStep": [ + "string" + ], + "Project": [ + "string" + ], + "ProjectTemplate": [ + "string" + ], + "Role": [ + "string" + ], + "TargetRole": [ + "string" + ], + "TargetTagParameter": [ + "string" + ], + "TemplatedProject": [ + "string" + ], + "Tenant": [ + "string" + ], + "TenantTag": [ + "string" + ], + "TenantTagParameter": [ + "string" + ], + "Trigger": [ + "string" + ], + "User": [ + "string" + ] + }, + "Type": "string", + "Value": "string" + } + ], + "Version": 0 +} +``` +::: + +**Response** + +`200` — Confirms that a Project Variable Set has been modified + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get variables for a project + +:endpoint{method="GET" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/variables"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/variables`. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Project Variable Set + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`OwnerId`** :span[string]{.type-label} + Gets or sets the ID of the document that owns these variables. +- **`ScopeValues`** :span[object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Channels`** :span[array of object]{.type-label} + - **`EnvironmentParameters`** :span[array of object]{.type-label} + - **`Environments`** :span[array of object]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`ProcessTemplateSteps`** :span[array of object]{.type-label} + - **`Processes`** :span[array of object]{.type-label} + - **`Roles`** :span[array of object]{.type-label} + - **`TargetTagParameters`** :span[array of object]{.type-label} + - **`TenantTagParameters`** :span[array of object]{.type-label} + - **`TenantTags`** :span[array of object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + Gets the collection of variables. + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsEditable`** :span[boolean]{.type-label} + - **`IsSensitive`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Prompt`** :span[object]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Type`** :span[string]{.type-label} + - **`Value`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "OwnerId": "string", + "ScopeValues": { + "Actions": [ + { + "Id": "string", + "Name": "string" + } + ], + "Channels": [ + { + "Id": "string", + "Name": "string" + } + ], + "EnvironmentParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "Environments": [ + { + "Id": "string", + "Name": "string" + } + ], + "Machines": [ + { + "Id": "string", + "Name": "string" + } + ], + "ProcessTemplateSteps": [ + { + "Id": "string", + "Name": "string" + } + ], + "Processes": [ + { + "Id": "string", + "Name": "string", + "ProcessType": "Deployment" + } + ], + "Roles": [ + { + "Id": "string", + "Name": "string" + } + ], + "TargetTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTags": [ + { + "Id": "string", + "Name": "string" + } + ] + }, + "SpaceId": "string", + "Variables": [ + { + "Description": "string", + "Id": "string", + "IsEditable": true, + "IsSensitive": true, + "Name": "string", + "Prompt": { + "Description": "string", + "DisplaySettings": {}, + "Label": "string", + "Required": true + }, + "Scope": { + "Action": [ + "string" + ], + "Channel": [ + "string" + ], + "Environment": [ + "string" + ], + "EnvironmentParameter": [ + "string" + ], + "Machine": [ + "string" + ], + "ParentDeployment": [ + "string" + ], + "Private": [ + "string" + ], + "ProcessOwner": [ + "string" + ], + "ProcessTemplateStep": [ + "string" + ], + "Project": [ + "string" + ], + "ProjectTemplate": [ + "string" + ], + "Role": [ + "string" + ], + "TargetRole": [ + "string" + ], + "TargetTagParameter": [ + "string" + ], + "TemplatedProject": [ + "string" + ], + "Tenant": [ + "string" + ], + "TenantTag": [ + "string" + ], + "TenantTagParameter": [ + "string" + ], + "Trigger": [ + "string" + ], + "User": [ + "string" + ] + }, + "Type": "string", + "Value": "string" + } + ], + "Version": 0 +} +``` +::: + +## Modify variables for the project + +:endpoint{method="PUT" path="/api/\{spaceId\}/projects/\{projectId\}/\{gitRef\}/variables"} + +Also reachable at `/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/variables`. + +**Path Parameters** + +- **`gitRef`** :span[string]{.type-label} *(required)* +- **`projectId`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`ChangeDescription`** :span[string]{.type-label} +- **`GitRef`** :span[string]{.type-label} *(required)* +- **`ProjectId`** :span[string]{.type-label} *(required)* +- **`ScopeValues`** :span[object]{.type-label} *(required)* + - **`Actions`** :span[array of object]{.type-label} + - **`Channels`** :span[array of object]{.type-label} + - **`EnvironmentParameters`** :span[array of object]{.type-label} + - **`Environments`** :span[array of object]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`ProcessTemplateSteps`** :span[array of object]{.type-label} + - **`Processes`** :span[array of object]{.type-label} + - **`Roles`** :span[array of object]{.type-label} + - **`TargetTagParameters`** :span[array of object]{.type-label} + - **`TenantTagParameters`** :span[array of object]{.type-label} + - **`TenantTags`** :span[array of object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`Variables`** :span[array of object]{.type-label} *(required)* + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsEditable`** :span[boolean]{.type-label} + - **`IsSensitive`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Prompt`** :span[object]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Type`** :span[string]{.type-label} + - **`Value`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + +:::api-example{label="Request"} +```json +{ + "ChangeDescription": "string", + "GitRef": "string", + "ProjectId": "string", + "ScopeValues": { + "Actions": [ + { + "Id": "string", + "Name": "string" + } + ], + "Channels": [ + { + "Id": "string", + "Name": "string" + } + ], + "EnvironmentParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "Environments": [ + { + "Id": "string", + "Name": "string" + } + ], + "Machines": [ + { + "Id": "string", + "Name": "string" + } + ], + "ProcessTemplateSteps": [ + { + "Id": "string", + "Name": "string" + } + ], + "Processes": [ + { + "Id": "string", + "Name": "string", + "ProcessType": "Deployment" + } + ], + "Roles": [ + { + "Id": "string", + "Name": "string" + } + ], + "TargetTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTags": [ + { + "Id": "string", + "Name": "string" + } + ] + }, + "SpaceId": "string", + "Variables": [ + { + "Description": "string", + "Id": "string", + "IsEditable": true, + "IsSensitive": true, + "Name": "string", + "Prompt": { + "Description": "string", + "DisplaySettings": {}, + "Label": "string", + "Required": true + }, + "Scope": { + "Action": [ + "string" + ], + "Channel": [ + "string" + ], + "Environment": [ + "string" + ], + "EnvironmentParameter": [ + "string" + ], + "Machine": [ + "string" + ], + "ParentDeployment": [ + "string" + ], + "Private": [ + "string" + ], + "ProcessOwner": [ + "string" + ], + "ProcessTemplateStep": [ + "string" + ], + "Project": [ + "string" + ], + "ProjectTemplate": [ + "string" + ], + "Role": [ + "string" + ], + "TargetRole": [ + "string" + ], + "TargetTagParameter": [ + "string" + ], + "TemplatedProject": [ + "string" + ], + "Tenant": [ + "string" + ], + "TenantTag": [ + "string" + ], + "TenantTagParameter": [ + "string" + ], + "Trigger": [ + "string" + ], + "User": [ + "string" + ] + }, + "Type": "string", + "Value": "string" + } + ], + "Version": 0 +} +``` +::: + +**Response** + +`200` — Confirms that a Project Variable Set has been modified + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Get a list of Variable Sets + +:endpoint{method="GET" path="/api/\{spaceId\}/variables/all"} + +Also reachable at `/api/spaces/{spaceIdentifier}/variables/all`, `/api/variables/all`. + +Lists all the Variable Sets in the supplied Space. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + A list of Variable Set resource IDs used to filter a query. + +**Response** + +`200` — The requested list of Variable Sets + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`OwnerId`** :span[string]{.type-label} + Gets or sets the ID of the document that owns these variables. +- **`ScopeValues`** :span[object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Channels`** :span[array of object]{.type-label} + - **`EnvironmentParameters`** :span[array of object]{.type-label} + - **`Environments`** :span[array of object]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`ProcessTemplateSteps`** :span[array of object]{.type-label} + - **`Processes`** :span[array of object]{.type-label} + - **`Roles`** :span[array of object]{.type-label} + - **`TargetTagParameters`** :span[array of object]{.type-label} + - **`TenantTagParameters`** :span[array of object]{.type-label} + - **`TenantTags`** :span[array of object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + Gets the collection of variables. + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsEditable`** :span[boolean]{.type-label} + - **`IsSensitive`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Prompt`** :span[object]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Type`** :span[string]{.type-label} + - **`Value`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +[ + { + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "OwnerId": "string", + "ScopeValues": { + "Actions": [ + {} + ], + "Channels": [ + {} + ], + "EnvironmentParameters": [ + {} + ], + "Environments": [ + {} + ], + "Machines": [ + {} + ], + "ProcessTemplateSteps": [ + {} + ], + "Processes": [ + {} + ], + "Roles": [ + {} + ], + "TargetTagParameters": [ + {} + ], + "TenantTagParameters": [ + {} + ], + "TenantTags": [ + {} + ] + }, + "SpaceId": "string", + "Variables": [ + { + "Description": "string", + "Id": "string", + "IsEditable": true, + "IsSensitive": true, + "Name": "string", + "Prompt": {}, + "Scope": {}, + "Type": "string", + "Value": "string" + } + ], + "Version": 0 + } +] +``` +::: + +## Get a list of Variable names + +:endpoint{method="GET" path="/api/\{spaceId\}/variables/names"} + +Also reachable at `/api/spaces/{spaceIdentifier}/variables/names`, `/api/variables/names`. + +List the names of variables that can be used in deployment actions. If a project is specified, this will include variables in that project. If a project environments filter is specified, project variables which are scoped to an unspecified environment will be excluded. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`gitRef`** :span[string]{.type-label} + GitRef for the project variables. +- **`project`** :span[string]{.type-label} + ID of the Project. +- **`projectEnvironmentsFilter`** :span[array of string]{.type-label} + ID of the Deployment Environments to filter on. +- **`runbook`** :span[string]{.type-label} + ID of the Runbook. + +**Response** + +`200` — The requested list of Variable names + +:::api-example{label="Response"} +```json +[ + "string" +] +``` +::: + +## Get a Variable Set preview + +:endpoint{method="GET" path="/api/\{spaceId\}/variables/preview"} + +Also reachable at `/api/spaces/{spaceIdentifier}/variables/preview`, `/api/variables/preview`. + +Lists the evaluated Variables for a deployment. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`action`** :span[string]{.type-label} + ID of the Action. +- **`channel`** :span[string]{.type-label} + ID of the Channel. +- **`environment`** :span[string]{.type-label} + ID of the Deployment Environment. +- **`gitRef`** :span[string]{.type-label} + GitRef for the project variables. +- **`machine`** :span[string]{.type-label} + ID of the Machine. +- **`project`** :span[string]{.type-label} *(required)* + ID of the Project. +- **`role`** :span[string]{.type-label} + Name of the Role. +- **`runbook`** :span[string]{.type-label} + ID of the Runbook. +- **`tenant`** :span[string]{.type-label} + ID of the Tenant. + +**Response** + +`200` — The requested Variable Set Preview + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`OwnerId`** :span[string]{.type-label} + Gets or sets the ID of the document that owns these variables. +- **`ScopeValues`** :span[object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Channels`** :span[array of object]{.type-label} + - **`EnvironmentParameters`** :span[array of object]{.type-label} + - **`Environments`** :span[array of object]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`ProcessTemplateSteps`** :span[array of object]{.type-label} + - **`Processes`** :span[array of object]{.type-label} + - **`Roles`** :span[array of object]{.type-label} + - **`TargetTagParameters`** :span[array of object]{.type-label} + - **`TenantTagParameters`** :span[array of object]{.type-label} + - **`TenantTags`** :span[array of object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + Gets the collection of variables. + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsEditable`** :span[boolean]{.type-label} + - **`IsSensitive`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Prompt`** :span[object]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Type`** :span[string]{.type-label} + - **`Value`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "OwnerId": "string", + "ScopeValues": { + "Actions": [ + { + "Id": "string", + "Name": "string" + } + ], + "Channels": [ + { + "Id": "string", + "Name": "string" + } + ], + "EnvironmentParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "Environments": [ + { + "Id": "string", + "Name": "string" + } + ], + "Machines": [ + { + "Id": "string", + "Name": "string" + } + ], + "ProcessTemplateSteps": [ + { + "Id": "string", + "Name": "string" + } + ], + "Processes": [ + { + "Id": "string", + "Name": "string", + "ProcessType": "Deployment" + } + ], + "Roles": [ + { + "Id": "string", + "Name": "string" + } + ], + "TargetTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTags": [ + { + "Id": "string", + "Name": "string" + } + ] + }, + "SpaceId": "string", + "Variables": [ + { + "Description": "string", + "Id": "string", + "IsEditable": true, + "IsSensitive": true, + "Name": "string", + "Prompt": { + "Description": "string", + "DisplaySettings": {}, + "Label": "string", + "Required": true + }, + "Scope": { + "Action": [ + "string" + ], + "Channel": [ + "string" + ], + "Environment": [ + "string" + ], + "EnvironmentParameter": [ + "string" + ], + "Machine": [ + "string" + ], + "ParentDeployment": [ + "string" + ], + "Private": [ + "string" + ], + "ProcessOwner": [ + "string" + ], + "ProcessTemplateStep": [ + "string" + ], + "Project": [ + "string" + ], + "ProjectTemplate": [ + "string" + ], + "Role": [ + "string" + ], + "TargetRole": [ + "string" + ], + "TargetTagParameter": [ + "string" + ], + "TemplatedProject": [ + "string" + ], + "Tenant": [ + "string" + ], + "TenantTag": [ + "string" + ], + "TenantTagParameter": [ + "string" + ], + "Trigger": [ + "string" + ], + "User": [ + "string" + ] + }, + "Type": "string", + "Value": "string" + } + ], + "Version": 0 +} +``` +::: + +## Get a Variable Set by Id + +:endpoint{method="GET" path="/api/\{spaceId\}/variables/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/variables/{id}`, `/api/variables/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Variable Set. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The requested Variable Set + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`OwnerId`** :span[string]{.type-label} + Gets or sets the ID of the document that owns these variables. +- **`ScopeValues`** :span[object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Channels`** :span[array of object]{.type-label} + - **`EnvironmentParameters`** :span[array of object]{.type-label} + - **`Environments`** :span[array of object]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`ProcessTemplateSteps`** :span[array of object]{.type-label} + - **`Processes`** :span[array of object]{.type-label} + - **`Roles`** :span[array of object]{.type-label} + - **`TargetTagParameters`** :span[array of object]{.type-label} + - **`TenantTagParameters`** :span[array of object]{.type-label} + - **`TenantTags`** :span[array of object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + Gets the collection of variables. + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsEditable`** :span[boolean]{.type-label} + - **`IsSensitive`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Prompt`** :span[object]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Type`** :span[string]{.type-label} + - **`Value`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "OwnerId": "string", + "ScopeValues": { + "Actions": [ + { + "Id": "string", + "Name": "string" + } + ], + "Channels": [ + { + "Id": "string", + "Name": "string" + } + ], + "EnvironmentParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "Environments": [ + { + "Id": "string", + "Name": "string" + } + ], + "Machines": [ + { + "Id": "string", + "Name": "string" + } + ], + "ProcessTemplateSteps": [ + { + "Id": "string", + "Name": "string" + } + ], + "Processes": [ + { + "Id": "string", + "Name": "string", + "ProcessType": "Deployment" + } + ], + "Roles": [ + { + "Id": "string", + "Name": "string" + } + ], + "TargetTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTags": [ + { + "Id": "string", + "Name": "string" + } + ] + }, + "SpaceId": "string", + "Variables": [ + { + "Description": "string", + "Id": "string", + "IsEditable": true, + "IsSensitive": true, + "Name": "string", + "Prompt": { + "Description": "string", + "DisplaySettings": {}, + "Label": "string", + "Required": true + }, + "Scope": { + "Action": [ + "string" + ], + "Channel": [ + "string" + ], + "Environment": [ + "string" + ], + "EnvironmentParameter": [ + "string" + ], + "Machine": [ + "string" + ], + "ParentDeployment": [ + "string" + ], + "Private": [ + "string" + ], + "ProcessOwner": [ + "string" + ], + "ProcessTemplateStep": [ + "string" + ], + "Project": [ + "string" + ], + "ProjectTemplate": [ + "string" + ], + "Role": [ + "string" + ], + "TargetRole": [ + "string" + ], + "TargetTagParameter": [ + "string" + ], + "TemplatedProject": [ + "string" + ], + "Tenant": [ + "string" + ], + "TenantTag": [ + "string" + ], + "TenantTagParameter": [ + "string" + ], + "Trigger": [ + "string" + ], + "User": [ + "string" + ] + }, + "Type": "string", + "Value": "string" + } + ], + "Version": 0 +} +``` +::: + +## Update a Variable Set + +:endpoint{method="PUT" path="/api/\{spaceId\}/variables/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/variables/{id}`, `/api/variables/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + Gets or sets a unique identifier for this resource. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`OwnerId`** :span[string]{.type-label} + Gets or sets the ID of the document that owns these variables. +- **`ScopeValues`** :span[object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Channels`** :span[array of object]{.type-label} + - **`EnvironmentParameters`** :span[array of object]{.type-label} + - **`Environments`** :span[array of object]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`ProcessTemplateSteps`** :span[array of object]{.type-label} + - **`Processes`** :span[array of object]{.type-label} + - **`Roles`** :span[array of object]{.type-label} + - **`TargetTagParameters`** :span[array of object]{.type-label} + - **`TenantTagParameters`** :span[array of object]{.type-label} + - **`TenantTags`** :span[array of object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + Gets the collection of variables. + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsEditable`** :span[boolean]{.type-label} + - **`IsSensitive`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Prompt`** :span[object]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Type`** :span[string]{.type-label} + - **`Value`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Request"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "OwnerId": "string", + "ScopeValues": { + "Actions": [ + { + "Id": "string", + "Name": "string" + } + ], + "Channels": [ + { + "Id": "string", + "Name": "string" + } + ], + "EnvironmentParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "Environments": [ + { + "Id": "string", + "Name": "string" + } + ], + "Machines": [ + { + "Id": "string", + "Name": "string" + } + ], + "ProcessTemplateSteps": [ + { + "Id": "string", + "Name": "string" + } + ], + "Processes": [ + { + "Id": "string", + "Name": "string", + "ProcessType": "Deployment" + } + ], + "Roles": [ + { + "Id": "string", + "Name": "string" + } + ], + "TargetTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTags": [ + { + "Id": "string", + "Name": "string" + } + ] + }, + "SpaceId": "string", + "Variables": [ + { + "Description": "string", + "Id": "string", + "IsEditable": true, + "IsSensitive": true, + "Name": "string", + "Prompt": { + "Description": "string", + "DisplaySettings": {}, + "Label": "string", + "Required": true + }, + "Scope": { + "Action": [ + "string" + ], + "Channel": [ + "string" + ], + "Environment": [ + "string" + ], + "EnvironmentParameter": [ + "string" + ], + "Machine": [ + "string" + ], + "ParentDeployment": [ + "string" + ], + "Private": [ + "string" + ], + "ProcessOwner": [ + "string" + ], + "ProcessTemplateStep": [ + "string" + ], + "Project": [ + "string" + ], + "ProjectTemplate": [ + "string" + ], + "Role": [ + "string" + ], + "TargetRole": [ + "string" + ], + "TargetTagParameter": [ + "string" + ], + "TemplatedProject": [ + "string" + ], + "Tenant": [ + "string" + ], + "TenantTag": [ + "string" + ], + "TenantTagParameter": [ + "string" + ], + "Trigger": [ + "string" + ], + "User": [ + "string" + ] + }, + "Type": "string", + "Value": "string" + } + ], + "Version": 0 +} +``` +::: + +**Response** + +`200` — Confirms that a variable set has been modified, containing the updated variable set + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`OwnerId`** :span[string]{.type-label} + Gets or sets the ID of the document that owns these variables. +- **`ScopeValues`** :span[object]{.type-label} + - **`Actions`** :span[array of object]{.type-label} + - **`Channels`** :span[array of object]{.type-label} + - **`EnvironmentParameters`** :span[array of object]{.type-label} + - **`Environments`** :span[array of object]{.type-label} + - **`Machines`** :span[array of object]{.type-label} + - **`ProcessTemplateSteps`** :span[array of object]{.type-label} + - **`Processes`** :span[array of object]{.type-label} + - **`Roles`** :span[array of object]{.type-label} + - **`TargetTagParameters`** :span[array of object]{.type-label} + - **`TenantTagParameters`** :span[array of object]{.type-label} + - **`TenantTags`** :span[array of object]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`Variables`** :span[array of object]{.type-label} + Gets the collection of variables. + - **`Description`** :span[string]{.type-label} + - **`Id`** :span[string]{.type-label} + - **`IsEditable`** :span[boolean]{.type-label} + - **`IsSensitive`** :span[boolean]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`Prompt`** :span[object]{.type-label} + - **`Scope`** :span[object]{.type-label} + - **`Type`** :span[string]{.type-label} + - **`Value`** :span[string]{.type-label} +- **`Version`** :span[integer]{.type-label} + Gets or sets the version number. + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "OwnerId": "string", + "ScopeValues": { + "Actions": [ + { + "Id": "string", + "Name": "string" + } + ], + "Channels": [ + { + "Id": "string", + "Name": "string" + } + ], + "EnvironmentParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "Environments": [ + { + "Id": "string", + "Name": "string" + } + ], + "Machines": [ + { + "Id": "string", + "Name": "string" + } + ], + "ProcessTemplateSteps": [ + { + "Id": "string", + "Name": "string" + } + ], + "Processes": [ + { + "Id": "string", + "Name": "string", + "ProcessType": "Deployment" + } + ], + "Roles": [ + { + "Id": "string", + "Name": "string" + } + ], + "TargetTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTagParameters": [ + { + "Id": "string", + "Name": "string" + } + ], + "TenantTags": [ + { + "Id": "string", + "Name": "string" + } + ] + }, + "SpaceId": "string", + "Variables": [ + { + "Description": "string", + "Id": "string", + "IsEditable": true, + "IsSensitive": true, + "Name": "string", + "Prompt": { + "Description": "string", + "DisplaySettings": {}, + "Label": "string", + "Required": true + }, + "Scope": { + "Action": [ + "string" + ], + "Channel": [ + "string" + ], + "Environment": [ + "string" + ], + "EnvironmentParameter": [ + "string" + ], + "Machine": [ + "string" + ], + "ParentDeployment": [ + "string" + ], + "Private": [ + "string" + ], + "ProcessOwner": [ + "string" + ], + "ProcessTemplateStep": [ + "string" + ], + "Project": [ + "string" + ], + "ProjectTemplate": [ + "string" + ], + "Role": [ + "string" + ], + "TargetRole": [ + "string" + ], + "TargetTagParameter": [ + "string" + ], + "TemplatedProject": [ + "string" + ], + "Tenant": [ + "string" + ], + "TenantTag": [ + "string" + ], + "TenantTagParameter": [ + "string" + ], + "Trigger": [ + "string" + ], + "User": [ + "string" + ] + }, + "Type": "string", + "Value": "string" + } + ], + "Version": 0 +} +``` +::: diff --git a/src/pages/docs/api/version-control.md b/src/pages/docs/api/version-control.md new file mode 100644 index 0000000000..8571e82939 --- /dev/null +++ b/src/pages/docs/api/version-control.md @@ -0,0 +1,34 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Version Control +--- + +## Clear the local Git cache + +:endpoint{method="POST" path="/api/configuration/versioncontrol/clear-cache"} + +**Response** + +`200` — Confirmation that the Git Cache was cleared + +:::api-example{label="Response"} +```json +{} +``` +::: + +## Clear the local Git cache + +:endpoint{method="POST" path="/api/configuration/versioncontrol/clear-cache/v1"} + +**Response** + +`200` — Confirmation that the Git Cache was cleared + +:::api-example{label="Response"} +```json +{} +``` +::: diff --git a/src/pages/docs/api/web.md b/src/pages/docs/api/web.md new file mode 100644 index 0000000000..91277386da --- /dev/null +++ b/src/pages/docs/api/web.md @@ -0,0 +1,62 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Web +--- + +## POST /api/jiraservicemanagement-integration/connectivity-test + +:endpoint{method="POST" path="/api/jiraservicemanagement-integration/connectivity-test"} + +**Request Body** + +- **`BaseUrl`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} +- **`Token`** :span[string]{.type-label} +- **`Username`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "BaseUrl": "string", + "Id": "string", + "Token": "string", + "Username": "string" +} +``` +::: + +**Response** + +`200` — OK + +## POST /api/servicenow-integration/connectivity-test + +:endpoint{method="POST" path="/api/servicenow-integration/connectivity-test"} + +**Request Body** + +- **`BaseUrl`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} +- **`OAuthClientId`** :span[string]{.type-label} +- **`OAuthClientSecret`** :span[string]{.type-label} +- **`UserPassword`** :span[string]{.type-label} +- **`Username`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "BaseUrl": "string", + "Id": "string", + "OAuthClientId": "string", + "OAuthClientSecret": "string", + "UserPassword": "string", + "Username": "string" +} +``` +::: + +**Response** + +`200` — OK diff --git a/src/pages/docs/api/worker-pools.md b/src/pages/docs/api/worker-pools.md new file mode 100644 index 0000000000..4328be0b83 --- /dev/null +++ b/src/pages/docs/api/worker-pools.md @@ -0,0 +1,804 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Worker Pools +--- + +## Get a list of Worker Pools + +:endpoint{method="GET" path="/api/\{spaceId\}/workerpools"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workerpools`, `/api/workerpools`. + +Lists the name and ID of of the Worker Pools in the supplied Octopus Deploy Space. The results will be sorted by the `SortOrder` field on each Worker Pool. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + List of Worker Pool IDs which if specified, filters the result to only include Worker Pools with matching IDs. +- **`name`** :span[string]{.type-label} + The exact name of a Worker Pool to be matched. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 10. Minimum `0`. + +**Response** + +`200` — The requested list of Worker Pools + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`CanAddWorkers`** :span[boolean]{.type-label} + - **`Description`** :span[string]{.type-label} + Gets or sets a short description of this pool that can be used to explain the purpose of the pool to other users. May describe the kinds of machines in the pool. This field may contain markdown. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDefault`** :span[boolean]{.type-label} + Is this the default pool. The default pool is used for steps that don't specify a worker pool. The default pool, if empty, uses the builtin worker to run steps. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`Name`** :span[string]{.type-label} + Gets or sets the name of this pool. This should be short, preferably 5-20 characters. + - **`Slug`** :span[string]{.type-label} + - **`SortOrder`** :span[integer]{.type-label} + Gets or sets a number indicating the priority of this pool in sort order. Pools with a lower sort order will appear in the UI before items with a higher sort order. + - **`SpaceId`** :span[string]{.type-label} + - **`WorkerPoolType`** :span[enum]{.type-label} + Allowed values: `StaticWorkerPool`, `DynamicWorkerPool`. +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "CanAddWorkers": true, + "Description": "string", + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SortOrder": 0, + "SpaceId": "string", + "WorkerPoolType": "StaticWorkerPool" + } + ], + "ItemsPerPage": 0, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "LastPageNumber": 0, + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "NumberOfPages": 0, + "TotalResults": 0 +} +``` +::: + +## Create a new Worker Pool + +:endpoint{method="POST" path="/api/\{spaceId\}/workerpools"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workerpools`, `/api/workerpools`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +- **`Description`** :span[string]{.type-label} + Gets or sets a short description of this pool that can be used to explain the purpose of the pool to other users. May describe the kinds of machines in the pool. This field may contain markdown. +- **`IsDefault`** :span[boolean]{.type-label} + Is this the default pool. The default pool is used for steps that don't specify a worker pool. The default pool, if empty, uses the builtin worker to run steps. +- **`Name`** :span[string]{.type-label} *(required)* + Gets or sets the name of this pool. This should be short, preferably 5-20 characters. Minimum length 1. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} + Gets or sets a number indicating the priority of this pool in sort order. Pools with a lower sort order will appear in the UI before items with a higher sort order. +- **`SpaceId`** :span[string]{.type-label} *(required)* +- **`WorkerPoolType`** :span[enum]{.type-label} *(required)* + Allowed values: `StaticWorkerPool`, `DynamicWorkerPool`. +- **`WorkerType`** :span[string]{.type-label} + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "IsDefault": true, + "Name": "string", + "Slug": "string", + "SortOrder": 0, + "SpaceId": "string", + "WorkerPoolType": "StaticWorkerPool", + "WorkerType": "string" +} +``` +::: + +**Response** + +`201` — Created + +- **`CanAddWorkers`** :span[boolean]{.type-label} +- **`Description`** :span[string]{.type-label} + Gets or sets a short description of this pool that can be used to explain the purpose of the pool to other users. May describe the kinds of machines in the pool. This field may contain markdown. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} + Is this the default pool. The default pool is used for steps that don't specify a worker pool. The default pool, if empty, uses the builtin worker to run steps. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this pool. This should be short, preferably 5-20 characters. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} + Gets or sets a number indicating the priority of this pool in sort order. Pools with a lower sort order will appear in the UI before items with a higher sort order. +- **`SpaceId`** :span[string]{.type-label} +- **`WorkerPoolType`** :span[enum]{.type-label} + Allowed values: `StaticWorkerPool`, `DynamicWorkerPool`. + +:::api-example{label="Response"} +```json +{ + "CanAddWorkers": true, + "Description": "string", + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SortOrder": 0, + "SpaceId": "string", + "WorkerPoolType": "StaticWorkerPool" +} +``` +::: + +## Get a list of Worker Pools + +:endpoint{method="GET" path="/api/\{spaceId\}/workerpools/all"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workerpools/all`, `/api/workerpools/all`. + +Lists the name and ID of of the Worker Pools in the supplied Octopus Deploy Space. The results will be sorted by the `SortOrder` field on each Worker Pool. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + List of Worker Pool IDs which if specified, filters the result to only include Worker Pools with matching IDs. + +**Response** + +`200` — The list of requested Worker Pools + +- **`CanAddWorkers`** :span[boolean]{.type-label} +- **`Description`** :span[string]{.type-label} + Gets or sets a short description of this pool that can be used to explain the purpose of the pool to other users. May describe the kinds of machines in the pool. This field may contain markdown. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} + Is this the default pool. The default pool is used for steps that don't specify a worker pool. The default pool, if empty, uses the builtin worker to run steps. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this pool. This should be short, preferably 5-20 characters. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} + Gets or sets a number indicating the priority of this pool in sort order. Pools with a lower sort order will appear in the UI before items with a higher sort order. +- **`SpaceId`** :span[string]{.type-label} +- **`WorkerPoolType`** :span[enum]{.type-label} + Allowed values: `StaticWorkerPool`, `DynamicWorkerPool`. + +:::api-example{label="Response"} +```json +[ + { + "CanAddWorkers": true, + "Description": "string", + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SortOrder": 0, + "SpaceId": "string", + "WorkerPoolType": "StaticWorkerPool" + } +] +``` +::: + +## List the available Worker Types for the Dynamic Worker Pool + +:endpoint{method="GET" path="/api/\{spaceId\}/workerpools/dynamicworkertypes"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workerpools/dynamicworkertypes`, `/api/workerpools/dynamicworkertypes`. + +Returns a list of the available Worker Types for the Dynamic Worker Pool + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested Dynamic Worker Types + +- **`Id`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} +- **`WorkerTypes`** :span[array of object]{.type-label} + - **`DeprecationDateUtc`** :span[string]{.type-label} + Format `date-time`. + - **`Description`** :span[string]{.type-label} + - **`EndOfLifeDateUtc`** :span[string]{.type-label} + Format `date-time`. + - **`Id`** :span[string]{.type-label} + - **`StartDateUtc`** :span[string]{.type-label} + Format `date-time`. + - **`Type`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "WorkerTypes": [ + { + "DeprecationDateUtc": "2020-01-01T00:00:00.000Z", + "Description": "string", + "EndOfLifeDateUtc": "2020-01-01T00:00:00.000Z", + "Id": "string", + "StartDateUtc": "2020-01-01T00:00:00.000Z", + "Type": "string" + } + ] +} +``` +::: + +**Error Responses** + +- **`500`** `internal_server_error` — Unable to connect to the Dynamic Worker service + +## PUT /api/{spaceId}/workerpools/sortorder + +:endpoint{method="PUT" path="/api/\{spaceId\}/workerpools/sortorder"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workerpools/sortorder`, `/api/workerpools/sortorder`. + +Takes an array of work pool IDs as the request body, uses the order of items in the array to sort the worker pools on the server. The ID of every worker pool must be specified. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Request Body** + +A `array of string` payload. + +:::api-example{label="Request"} +```json +[ + "string" +] +``` +::: + +**Response** + +`200` — Success + +## List all worker pools, including a summary of worker information + +:endpoint{method="GET" path="/api/\{spaceId\}/workerpools/summary"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workerpools/summary`, `/api/workerpools/summary`. + +Lists all worker pools, including a summary of machine information. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`commStyles`** :span[array of string]{.type-label} +- **`healthStatuses`** :span[array of string]{.type-label} +- **`hideEmptyWorkerPools`** :span[boolean]{.type-label} +- **`ids`** :span[array of string]{.type-label} +- **`isDisabled`** :span[boolean]{.type-label} +- **`machinePartialName`** :span[string]{.type-label} +- **`partialName`** :span[string]{.type-label} +- **`shellNames`** :span[array of string]{.type-label} + +**Response** + +`200` — The requested Worker Pool Summary + +- **`MachineEndpointSummaries`** :span[object]{.type-label} +- **`MachineHealthStatusSummaries`** :span[object]{.type-label} +- **`MachineIdsForCalamariUpgrade`** :span[array of string]{.type-label} +- **`MachineIdsForTentacleUpgrade`** :span[array of string]{.type-label} +- **`TentacleUpgradesRequired`** :span[boolean]{.type-label} +- **`TotalDisabledMachines`** :span[integer]{.type-label} +- **`TotalMachines`** :span[integer]{.type-label} +- **`WorkerPoolSummaries`** :span[array of object]{.type-label} + - **`MachineEndpointSummaries`** :span[object]{.type-label} + - **`MachineHealthStatusSummaries`** :span[object]{.type-label} + - **`MachineIdsForCalamariUpgrade`** :span[array of string]{.type-label} + - **`MachineIdsForTentacleUpgrade`** :span[array of string]{.type-label} + - **`TentacleUpgradesRequired`** :span[boolean]{.type-label} + - **`TotalDisabledMachines`** :span[integer]{.type-label} + - **`TotalMachines`** :span[integer]{.type-label} + - **`WorkerPool`** :span[object]{.type-label} + +:::api-example{label="Response"} +```json +{ + "MachineEndpointSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineHealthStatusSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineIdsForCalamariUpgrade": [ + "string" + ], + "MachineIdsForTentacleUpgrade": [ + "string" + ], + "TentacleUpgradesRequired": true, + "TotalDisabledMachines": 0, + "TotalMachines": 0, + "WorkerPoolSummaries": [ + { + "MachineEndpointSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineHealthStatusSummaries": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "MachineIdsForCalamariUpgrade": [ + "string" + ], + "MachineIdsForTentacleUpgrade": [ + "string" + ], + "TentacleUpgradesRequired": true, + "TotalDisabledMachines": 0, + "TotalMachines": 0, + "WorkerPool": { + "CanAddWorkers": true, + "Description": "string", + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {}, + "Name": "string", + "Slug": "string", + "SortOrder": 0, + "SpaceId": "string", + "WorkerPoolType": "StaticWorkerPool" + } + } + ] +} +``` +::: + +## Get the available Worker Pool types + +:endpoint{method="GET" path="/api/\{spaceId\}/workerpools/supportedtypes"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workerpools/supportedtypes`, `/api/workerpools/supportedtypes`. + +Lists the available Worker Pool types. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The list of Supported Worker Pool Types + +- **`Id`** :span[string]{.type-label} +- **`Links`** :span[object]{.type-label} +- **`SupportedPoolTypes`** :span[array of enum]{.type-label} + Allowed values: `StaticWorkerPool`, `DynamicWorkerPool`. + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "SupportedPoolTypes": [ + "StaticWorkerPool" + ] +} +``` +::: + +## Get a Worker Pool by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/workerpools/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workerpools/{id}`, `/api/workerpools/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The requested Worker Pool. + +- **`CanAddWorkers`** :span[boolean]{.type-label} +- **`Description`** :span[string]{.type-label} + Gets or sets a short description of this pool that can be used to explain the purpose of the pool to other users. May describe the kinds of machines in the pool. This field may contain markdown. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} + Is this the default pool. The default pool is used for steps that don't specify a worker pool. The default pool, if empty, uses the builtin worker to run steps. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this pool. This should be short, preferably 5-20 characters. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} + Gets or sets a number indicating the priority of this pool in sort order. Pools with a lower sort order will appear in the UI before items with a higher sort order. +- **`SpaceId`** :span[string]{.type-label} +- **`WorkerPoolType`** :span[enum]{.type-label} + Allowed values: `StaticWorkerPool`, `DynamicWorkerPool`. + +:::api-example{label="Response"} +```json +{ + "CanAddWorkers": true, + "Description": "string", + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SortOrder": 0, + "SpaceId": "string", + "WorkerPoolType": "StaticWorkerPool" +} +``` +::: + +## Modify an existing worker pool + +:endpoint{method="PUT" path="/api/\{spaceId\}/workerpools/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workerpools/{id}`, `/api/workerpools/{id}`. + +Updates an existing worker pool. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the worker pool. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Description`** :span[string]{.type-label} + The description of the worker pool. +- **`Id`** :span[string]{.type-label} *(required)* + The ID of the worker pool. +- **`IsDefault`** :span[boolean]{.type-label} *(required)* + Whether the worker pool is the default or not. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the worker pool. Minimum length 1. +- **`Slug`** :span[string]{.type-label} + The slug of the worker pool. +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`WorkerType`** :span[string]{.type-label} + The worker image. + +:::api-example{label="Request"} +```json +{ + "Description": "string", + "Id": "string", + "IsDefault": true, + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "WorkerType": "string" +} +``` +::: + +**Response** + +`200` — Confirms that a Worker Pool was modified, containing the updated Worker Pool + +- **`CanAddWorkers`** :span[boolean]{.type-label} +- **`Description`** :span[string]{.type-label} + Gets or sets a short description of this pool that can be used to explain the purpose of the pool to other users. May describe the kinds of machines in the pool. This field may contain markdown. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDefault`** :span[boolean]{.type-label} + Is this the default pool. The default pool is used for steps that don't specify a worker pool. The default pool, if empty, uses the builtin worker to run steps. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Name`** :span[string]{.type-label} + Gets or sets the name of this pool. This should be short, preferably 5-20 characters. +- **`Slug`** :span[string]{.type-label} +- **`SortOrder`** :span[integer]{.type-label} + Gets or sets a number indicating the priority of this pool in sort order. Pools with a lower sort order will appear in the UI before items with a higher sort order. +- **`SpaceId`** :span[string]{.type-label} +- **`WorkerPoolType`** :span[enum]{.type-label} + Allowed values: `StaticWorkerPool`, `DynamicWorkerPool`. + +:::api-example{label="Response"} +```json +{ + "CanAddWorkers": true, + "Description": "string", + "Id": "string", + "IsDefault": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Name": "string", + "Slug": "string", + "SortOrder": 0, + "SpaceId": "string", + "WorkerPoolType": "StaticWorkerPool" +} +``` +::: + +## Delete an existing Worker Pool + +:endpoint{method="DELETE" path="/api/\{spaceId\}/workerpools/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workerpools/{id}`, `/api/workerpools/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the Worker Pool to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — Success + +## Get a list of WorkerResources for the given WorkerPoolResource + +:endpoint{method="GET" path="/api/\{spaceId\}/workerpools/\{id\}/workers"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workerpools/{id}/workers`, `/api/workerpools/{id}/workers`. + +Lists all of the machines that belong to the given worker pool. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + ID of the WorkerPool. +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`commStyles`** :span[array of string]{.type-label} +- **`deploymentTargetTypes`** :span[array of string]{.type-label} +- **`healthStatuses`** :span[array of string]{.type-label} +- **`isDisabled`** :span[boolean]{.type-label} +- **`operatingSystemNames`** :span[array of string]{.type-label} +- **`partialName`** :span[string]{.type-label} +- **`shellNames`** :span[array of string]{.type-label} +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 20. Minimum `0`. + +**Response** + +`200` — The requested list of Workers within a Worker Pool + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Architecture`** :span[string]{.type-label} + - **`Endpoint`** :span[object]{.type-label} + - **`HasLatestCalamari`** :span[boolean]{.type-label} + - **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`IsInProcess`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MachinePolicyId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OperatingSystem`** :span[string]{.type-label} + - **`OperatingSystemVersion`** :span[string]{.type-label} + - **`ShellName`** :span[string]{.type-label} + - **`ShellVersion`** :span[string]{.type-label} + - **`SkipInitialHealthCheck`** :span[boolean]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`StatusSummary`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Uri`** :span[string]{.type-label} + - **`WorkerPoolIds`** :span[array of string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {} + }, + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "Thumbprint": "string", + "Uri": "string", + "WorkerPoolIds": [ + "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 +} +``` +::: diff --git a/src/pages/docs/api/worker-task-leases.md b/src/pages/docs/api/worker-task-leases.md new file mode 100644 index 0000000000..2bf642f740 --- /dev/null +++ b/src/pages/docs/api/worker-task-leases.md @@ -0,0 +1,80 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Worker Task Leases +--- + +## Get WorkerTaskLeases + +:endpoint{method="GET" path="/api/\{spaceId\}/workertaskleases"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workertaskleases`. + +Gets a paginated set of WorkerTaskLeases. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The id of the space for the WorkerTaskLease. + +**Query Parameters** + +- **`skip`** :span[integer]{.type-label} *(required)* + Number of items to skip. Minimum `0`. +- **`take`** :span[integer]{.type-label} *(required)* + Number of items to take. Minimum `0`. + +**Response** + +`200` — Rseponse to getting set of WorkerTaskLeases + +- **`WorkerTaskLeases`** :span[object]{.type-label} + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`ItemType`** :span[string]{.type-label} + - **`Items`** :span[array of object]{.type-label} + - **`ItemsPerPage`** :span[integer]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`LastPageNumber`** :span[integer]{.type-label} + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`NumberOfPages`** :span[integer]{.type-label} + - **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "WorkerTaskLeases": { + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Exclusive": true, + "Id": "string", + "Name": "string", + "ServerTaskId": "string", + "SpaceId": "string", + "TakenAt": "2020-01-01T00:00:00.000Z", + "WorkerId": "string", + "WorkerPoolId": "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 + } +} +``` +::: diff --git a/src/pages/docs/api/workers.md b/src/pages/docs/api/workers.md new file mode 100644 index 0000000000..ebad21b67b --- /dev/null +++ b/src/pages/docs/api/workers.md @@ -0,0 +1,1014 @@ +--- +layout: src/layouts/Api.astro +pubDate: 2026-08-11 +modDate: 2026-08-11 +title: Workers +--- + +## List all of the registered worker machines in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name + +:endpoint{method="GET" path="/api/\{spaceId\}/workers"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workers`, `/api/workers`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`commStyles`** :span[array of string]{.type-label} + List of communication styles which if specified, filters the result to only include Workers with matching communication styles. +- **`healthStatuses`** :span[array of string]{.type-label} + List of health statuses which if specified, filters the result to only include Deployment Targets with matching health statuses. +- **`ids`** :span[array of string]{.type-label} + List of Worker IDs which if specified, filters the result to only include Workers with matching IDs. +- **`isDisabled`** :span[boolean]{.type-label} + A filter to return only disabled/enabled Workers. +- **`name`** :span[string]{.type-label} + The exact name of a Worker to be matched. +- **`operatingSystemNames`** :span[array of string]{.type-label} + List of operating system names which if specified, filters the result to only include Workers with matching operating systems. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`shellNames`** :span[array of string]{.type-label} + List of shell names which if specified, filters the result to only include Workers with matching shells. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`workerPoolIds`** :span[array of string]{.type-label} + List of Worker Pool IDs which if specified, filters the result to only include Workers belonging to these Worker Pools. + +**Response** + +`200` — A paginated list of Workers + +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`ItemType`** :span[string]{.type-label} +- **`Items`** :span[array of object]{.type-label} + - **`Architecture`** :span[string]{.type-label} + - **`Endpoint`** :span[object]{.type-label} + - **`HasLatestCalamari`** :span[boolean]{.type-label} + - **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`IsDisabled`** :span[boolean]{.type-label} + - **`IsInProcess`** :span[boolean]{.type-label} + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. + - **`MachinePolicyId`** :span[string]{.type-label} + - **`Name`** :span[string]{.type-label} + - **`OperatingSystem`** :span[string]{.type-label} + - **`OperatingSystemVersion`** :span[string]{.type-label} + - **`ShellName`** :span[string]{.type-label} + - **`ShellVersion`** :span[string]{.type-label} + - **`SkipInitialHealthCheck`** :span[boolean]{.type-label} + - **`Slug`** :span[string]{.type-label} + - **`SpaceId`** :span[string]{.type-label} + - **`StatusSummary`** :span[string]{.type-label} + - **`Thumbprint`** :span[string]{.type-label} + - **`Uri`** :span[string]{.type-label} + - **`WorkerPoolIds`** :span[array of string]{.type-label} +- **`ItemsPerPage`** :span[integer]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`LastPageNumber`** :span[integer]{.type-label} +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`NumberOfPages`** :span[integer]{.type-label} +- **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Id": "string", + "ItemType": "string", + "Items": [ + { + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {} + }, + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "Thumbprint": "string", + "Uri": "string", + "WorkerPoolIds": [ + "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 +} +``` +::: + +## Create a new worker + +:endpoint{method="POST" path="/api/\{spaceId\}/workers"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workers`, `/api/workers`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Endpoint`** :span[object]{.type-label} *(required)* + - **`CommunicationStyle`** :span[enum]{.type-label} + This is for legacy support in client. Server no longer uses this for determining endpoint types, it uses DeploymentTargetType. + Allowed values: `None`, `TentaclePassive`, `TentacleActive`, `Ssh`, `OfflineDrop`, `AzureWebApp`, `Ftp`, `AzureCloudService`, `AzureServiceFabricCluster`, `Kubernetes`, `StepPackage`, `KubernetesTentacle`, `AwsEcsCluster`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`IsDisabled`** :span[boolean]{.type-label} *(required)* + Whether the worker is disabled or not. +- **`MachinePolicyId`** :span[string]{.type-label} + The policy the worker must adhere to. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the worker. Minimum length 1. +- **`SkipInitialHealthCheck`** :span[boolean]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`WorkerPoolIds`** :span[array of string]{.type-label} *(required)* + The worker pools the worker belongs to. + +:::api-example{label="Request"} +```json +{ + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "IsDisabled": true, + "MachinePolicyId": "string", + "Name": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "WorkerPoolIds": [ + "string" + ] +} +``` +::: + +**Response** + +`201` — Created + +- **`Architecture`** :span[string]{.type-label} +- **`Endpoint`** :span[object]{.type-label} + - **`CommunicationStyle`** :span[enum]{.type-label} + This is for legacy support in client. Server no longer uses this for determining endpoint types, it uses DeploymentTargetType. + Allowed values: `None`, `TentaclePassive`, `TentacleActive`, `Ssh`, `OfflineDrop`, `AzureWebApp`, `Ftp`, `AzureCloudService`, `AzureServiceFabricCluster`, `Kubernetes`, `StepPackage`, `KubernetesTentacle`, `AwsEcsCluster`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`HasLatestCalamari`** :span[boolean]{.type-label} +- **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsInProcess`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachinePolicyId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`OperatingSystem`** :span[string]{.type-label} +- **`OperatingSystemVersion`** :span[string]{.type-label} +- **`ShellName`** :span[string]{.type-label} +- **`ShellVersion`** :span[string]{.type-label} +- **`SkipInitialHealthCheck`** :span[boolean]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`StatusSummary`** :span[string]{.type-label} +- **`Thumbprint`** :span[string]{.type-label} +- **`Uri`** :span[string]{.type-label} +- **`WorkerPoolIds`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "Thumbprint": "string", + "Uri": "string", + "WorkerPoolIds": [ + "string" + ] +} +``` +::: + +## Get a list of Workers + +:endpoint{method="GET" path="/api/\{spaceId\}/workers/all"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workers/all`, `/api/workers/all`. + +Lists all of the Workers in the supplied Space. The results will be sorted alphabetically by name. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`ids`** :span[array of string]{.type-label} + A list of Worker resource IDs used to filter a query. +- **`thumbprint`** :span[string]{.type-label} + A thumbprint used to filter a query. + +**Response** + +`200` — The requested list of Workers + +- **`Architecture`** :span[string]{.type-label} +- **`Endpoint`** :span[object]{.type-label} + - **`CommunicationStyle`** :span[enum]{.type-label} + This is for legacy support in client. Server no longer uses this for determining endpoint types, it uses DeploymentTargetType. + Allowed values: `None`, `TentaclePassive`, `TentacleActive`, `Ssh`, `OfflineDrop`, `AzureWebApp`, `Ftp`, `AzureCloudService`, `AzureServiceFabricCluster`, `Kubernetes`, `StepPackage`, `KubernetesTentacle`, `AwsEcsCluster`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`HasLatestCalamari`** :span[boolean]{.type-label} +- **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsInProcess`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachinePolicyId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`OperatingSystem`** :span[string]{.type-label} +- **`OperatingSystemVersion`** :span[string]{.type-label} +- **`ShellName`** :span[string]{.type-label} +- **`ShellVersion`** :span[string]{.type-label} +- **`SkipInitialHealthCheck`** :span[boolean]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`StatusSummary`** :span[string]{.type-label} +- **`Thumbprint`** :span[string]{.type-label} +- **`Uri`** :span[string]{.type-label} +- **`WorkerPoolIds`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +[ + { + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "Thumbprint": "string", + "Uri": "string", + "WorkerPoolIds": [ + "string" + ] + } +] +``` +::: + +## Interrogate a machine for communication details so that it may be added to the installation + +:endpoint{method="GET" path="/api/\{spaceId\}/workers/discover"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workers/discover`, `/api/workers/discover`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Query Parameters** + +- **`host`** :span[string]{.type-label} *(required)* + The hostname of the machine to discover. +- **`port`** :span[integer]{.type-label} + The port of the machine to discover. +- **`proxyId`** :span[string]{.type-label} + The ID of the proxy to go through. +- **`type`** :span[enum]{.type-label} + The type of endpoint on the machine. + Allowed values: `TentaclePassive`, `TentacleActive`, `Ssh`. + +**Response** + +`200` — The worker which was discovered + +- **`Architecture`** :span[string]{.type-label} +- **`Endpoint`** :span[object]{.type-label} + - **`CommunicationStyle`** :span[enum]{.type-label} + This is for legacy support in client. Server no longer uses this for determining endpoint types, it uses DeploymentTargetType. + Allowed values: `None`, `TentaclePassive`, `TentacleActive`, `Ssh`, `OfflineDrop`, `AzureWebApp`, `Ftp`, `AzureCloudService`, `AzureServiceFabricCluster`, `Kubernetes`, `StepPackage`, `KubernetesTentacle`, `AwsEcsCluster`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`HasLatestCalamari`** :span[boolean]{.type-label} +- **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsInProcess`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachinePolicyId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`OperatingSystem`** :span[string]{.type-label} +- **`OperatingSystemVersion`** :span[string]{.type-label} +- **`ShellName`** :span[string]{.type-label} +- **`ShellVersion`** :span[string]{.type-label} +- **`SkipInitialHealthCheck`** :span[boolean]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`StatusSummary`** :span[string]{.type-label} +- **`Thumbprint`** :span[string]{.type-label} +- **`Uri`** :span[string]{.type-label} +- **`WorkerPoolIds`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "Thumbprint": "string", + "Uri": "string", + "WorkerPoolIds": [ + "string" + ] +} +``` +::: + +## Get all operating system names for workers. The result will be a string array + +:endpoint{method="GET" path="/api/\{spaceId\}/workers/operatingsystem/names/all"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workers/operatingsystem/names/all`, `/api/workers/operatingsystem/names/all`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The operating system names for workers. + +:::api-example{label="Response"} +```json +[ + "string" +] +``` +::: + +## Get all operating system shell names for workers. The result will be a string array + +:endpoint{method="GET" path="/api/\{spaceId\}/workers/operatingsystem/shells/all"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workers/operatingsystem/shells/all`, `/api/workers/operatingsystem/shells/all`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Response** + +`200` — The operating system shell names for workers. + +:::api-example{label="Response"} +```json +[ + "string" +] +``` +::: + +## List all of the registered worker machines in the supplied Octopus Deploy Space. The results will be sorted alphabetically by name + +:endpoint{method="GET" path="/api/\{spaceId\}/workers/v2"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workers/v2`, `/api/workers/v2`. + +**Path Parameters** + +- **`spaceId`** :span[string]{.type-label} *(required)* + +**Query Parameters** + +- **`commStyles`** :span[array of string]{.type-label} + List of communication styles which if specified, filters the result to only include Workers with matching communication styles. +- **`healthStatuses`** :span[array of string]{.type-label} + List of health statuses which if specified, filters the result to only include Workers with matching health statuses. +- **`ids`** :span[array of string]{.type-label} + List of Worker IDs which if specified, filters the result to only include Workers with matching IDs. +- **`isDisabled`** :span[boolean]{.type-label} + A filter to return only disabled/enabled Workers. +- **`name`** :span[string]{.type-label} + The exact name of a Worker to be matched. +- **`operatingSystemNames`** :span[array of string]{.type-label} + List of operating system names which if specified, filters the result to only include Workers with matching operating systems. +- **`partialName`** :span[string]{.type-label} + A partial or complete name to search on. This will perform a "contains" style match against the supplied name or name-fragment. +- **`shellNames`** :span[array of string]{.type-label} + List of shell names which if specified, filters the result to only include Workers with matching shells. +- **`skip`** :span[integer]{.type-label} + Number of items to skip. Defaults to zero. Minimum `0`. +- **`take`** :span[integer]{.type-label} + Number of items to take. Defaults to 30. Minimum `0`. +- **`workerPoolIds`** :span[array of string]{.type-label} + List of Worker Pool IDs which if specified, filters the result to only include Workers belonging to these Worker Pools. + +**Response** + +`200` — The list of alphabetically sorted workers that matched the request. + +- **`WorkerCountPerHealthStatus`** :span[object]{.type-label} +- **`Workers`** :span[object]{.type-label} + - **`ItemType`** :span[string]{.type-label} + - **`Items`** :span[array of object]{.type-label} + - **`ItemsPerPage`** :span[integer]{.type-label} + - **`LastPageNumber`** :span[integer]{.type-label} + - **`NumberOfPages`** :span[integer]{.type-label} + - **`TotalResults`** :span[integer]{.type-label} + +:::api-example{label="Response"} +```json +{ + "WorkerCountPerHealthStatus": { + "additionalProp1": 0, + "additionalProp2": 0, + "additionalProp3": 0 + }, + "Workers": { + "ItemType": "string", + "Items": [ + { + "Architecture": "string", + "Endpoint": {}, + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": {}, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "Thumbprint": "string", + "Uri": "string", + "WorkerPoolIds": [ + "string" + ] + } + ], + "ItemsPerPage": 0, + "LastPageNumber": 0, + "NumberOfPages": 0, + "TotalResults": 0 + } +} +``` +::: + +## Get a Worker by ID + +:endpoint{method="GET" path="/api/\{spaceId\}/workers/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workers/{id}`, `/api/workers/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the Worker to retrieve. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Return the Worker Resource + +- **`Architecture`** :span[string]{.type-label} +- **`Endpoint`** :span[object]{.type-label} + - **`CommunicationStyle`** :span[enum]{.type-label} + This is for legacy support in client. Server no longer uses this for determining endpoint types, it uses DeploymentTargetType. + Allowed values: `None`, `TentaclePassive`, `TentacleActive`, `Ssh`, `OfflineDrop`, `AzureWebApp`, `Ftp`, `AzureCloudService`, `AzureServiceFabricCluster`, `Kubernetes`, `StepPackage`, `KubernetesTentacle`, `AwsEcsCluster`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`HasLatestCalamari`** :span[boolean]{.type-label} +- **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsInProcess`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachinePolicyId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`OperatingSystem`** :span[string]{.type-label} +- **`OperatingSystemVersion`** :span[string]{.type-label} +- **`ShellName`** :span[string]{.type-label} +- **`ShellVersion`** :span[string]{.type-label} +- **`SkipInitialHealthCheck`** :span[boolean]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`StatusSummary`** :span[string]{.type-label} +- **`Thumbprint`** :span[string]{.type-label} +- **`Uri`** :span[string]{.type-label} +- **`WorkerPoolIds`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "Thumbprint": "string", + "Uri": "string", + "WorkerPoolIds": [ + "string" + ] +} +``` +::: + +## Modify an existing worker machine + +:endpoint{method="PUT" path="/api/\{spaceId\}/workers/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workers/{id}`, `/api/workers/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the worker. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Request Body** + +- **`Endpoint`** :span[object]{.type-label} *(required)* + - **`CommunicationStyle`** :span[enum]{.type-label} + This is for legacy support in client. Server no longer uses this for determining endpoint types, it uses DeploymentTargetType. + Allowed values: `None`, `TentaclePassive`, `TentacleActive`, `Ssh`, `OfflineDrop`, `AzureWebApp`, `Ftp`, `AzureCloudService`, `AzureServiceFabricCluster`, `Kubernetes`, `StepPackage`, `KubernetesTentacle`, `AwsEcsCluster`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Id`** :span[string]{.type-label} *(required)* + The ID of the worker. +- **`IsDisabled`** :span[boolean]{.type-label} *(required)* + Whether the worker is disabled or not. +- **`MachinePolicyId`** :span[string]{.type-label} + The policy the worker must adhere to. +- **`Name`** :span[string]{.type-label} *(required)* + The name of the worker. Minimum length 1. +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). +- **`WorkerPoolIds`** :span[array of string]{.type-label} *(required)* + The worker pools the worker belongs to. + +:::api-example{label="Request"} +```json +{ + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "Id": "string", + "IsDisabled": true, + "MachinePolicyId": "string", + "Name": "string", + "Slug": "string", + "SpaceId": "string", + "WorkerPoolIds": [ + "string" + ] +} +``` +::: + +**Response** + +`200` — The modified worker + +- **`Architecture`** :span[string]{.type-label} +- **`Endpoint`** :span[object]{.type-label} + - **`CommunicationStyle`** :span[enum]{.type-label} + This is for legacy support in client. Server no longer uses this for determining endpoint types, it uses DeploymentTargetType. + Allowed values: `None`, `TentaclePassive`, `TentacleActive`, `Ssh`, `OfflineDrop`, `AzureWebApp`, `Ftp`, `AzureCloudService`, `AzureServiceFabricCluster`, `Kubernetes`, `StepPackage`, `KubernetesTentacle`, `AwsEcsCluster`. + - **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. + - **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. + - **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. + - **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`HasLatestCalamari`** :span[boolean]{.type-label} +- **`HealthStatus`** :span[enum]{.type-label} + Allowed values: `Healthy`, `Unavailable`, `Unknown`, `HasWarnings`, `Unhealthy`. +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`IsDisabled`** :span[boolean]{.type-label} +- **`IsInProcess`** :span[boolean]{.type-label} +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`MachinePolicyId`** :span[string]{.type-label} +- **`Name`** :span[string]{.type-label} +- **`OperatingSystem`** :span[string]{.type-label} +- **`OperatingSystemVersion`** :span[string]{.type-label} +- **`ShellName`** :span[string]{.type-label} +- **`ShellVersion`** :span[string]{.type-label} +- **`SkipInitialHealthCheck`** :span[boolean]{.type-label} +- **`Slug`** :span[string]{.type-label} +- **`SpaceId`** :span[string]{.type-label} +- **`StatusSummary`** :span[string]{.type-label} +- **`Thumbprint`** :span[string]{.type-label} +- **`Uri`** :span[string]{.type-label} +- **`WorkerPoolIds`** :span[array of string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "Architecture": "string", + "Endpoint": { + "CommunicationStyle": "None", + "Id": "string", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } + }, + "HasLatestCalamari": true, + "HealthStatus": "Healthy", + "Id": "string", + "IsDisabled": true, + "IsInProcess": true, + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "MachinePolicyId": "string", + "Name": "string", + "OperatingSystem": "string", + "OperatingSystemVersion": "string", + "ShellName": "string", + "ShellVersion": "string", + "SkipInitialHealthCheck": true, + "Slug": "string", + "SpaceId": "string", + "StatusSummary": "string", + "Thumbprint": "string", + "Uri": "string", + "WorkerPoolIds": [ + "string" + ] +} +``` +::: + +## Delete an existing Worker + +:endpoint{method="DELETE" path="/api/\{spaceId\}/workers/\{id\}"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workers/{id}`, `/api/workers/{id}`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the Worker to delete. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — Success + +## Get the status of the network connection between the Octopus server and a worker + +:endpoint{method="GET" path="/api/\{spaceId\}/workers/\{id\}/connection"} + +Also reachable at `/api/spaces/{spaceIdentifier}/workers/{id}/connection`, `/api/workers/{id}/connection`. + +**Path Parameters** + +- **`id`** :span[string]{.type-label} *(required)* + The ID of the worker. +- **`spaceId`** :span[string]{.type-label} *(required)* + The ID of the space containing the resource(s). + +**Response** + +`200` — The connection status of the worker + +- **`CurrentTentacleVersion`** :span[string]{.type-label} +- **`Id`** :span[string]{.type-label} + Gets or sets a unique identifier for this resource. +- **`LastChecked`** :span[string]{.type-label} + Format `date-time`. +- **`LastModifiedBy`** :span[string]{.type-label} + Gets or sets the username of the user who last modified this resource. +- **`LastModifiedOn`** :span[string]{.type-label} + Gets or sets the date/time that this resource was last modified. Format `date-time`. +- **`Links`** :span[object]{.type-label} + Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server. +- **`Logs`** :span[array of object]{.type-label} + - **`Category`** :span[string]{.type-label} + - **`Detail`** :span[string]{.type-label} + - **`GapLastNumber`** :span[integer]{.type-label} + - **`MessageText`** :span[string]{.type-label} + - **`Number`** :span[integer]{.type-label} + - **`OccurredAt`** :span[string]{.type-label} + Format `date-time`. +- **`MachineId`** :span[string]{.type-label} +- **`Status`** :span[string]{.type-label} + +:::api-example{label="Response"} +```json +{ + "CurrentTentacleVersion": "string", + "Id": "string", + "LastChecked": "2020-01-01T00:00:00.000Z", + "LastModifiedBy": "string", + "LastModifiedOn": "2020-01-01T00:00:00.000Z", + "Links": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + }, + "Logs": [ + { + "Category": "string", + "Detail": "string", + "GapLastNumber": 0, + "MessageText": "string", + "Number": 0, + "OccurredAt": "2020-01-01T00:00:00.000Z" + } + ], + "MachineId": "string", + "Status": "string" +} +``` +::: diff --git a/src/pages/docs/search.json.ts b/src/pages/docs/search.json.ts index cdbdc847cb..6ef6c53a15 100644 --- a/src/pages/docs/search.json.ts +++ b/src/pages/docs/search.json.ts @@ -8,6 +8,7 @@ import type { MarkdownInstance } from 'astro'; import { SITE } from '@config'; import { convert } from 'html-to-text'; import keywordExtractor from 'keyword-extractor'; +import { isUnderConstruction } from '@lib/underConstruction'; const getData = async () => { //@ts-ignore @@ -15,7 +16,14 @@ const getData = async () => { const items = []; for (const path in allPages) { - const page = (await allPages[path]()) as MarkdownInstance>; + // Temporary - see src/lib/underConstruction.ts. + if (isUnderConstruction(path)) { + continue; + } + + const page = (await allPages[path]()) as MarkdownInstance< + Record + >; if (!PostFiltering.showInSearch(page)) { continue; @@ -28,7 +36,9 @@ const getData = async () => { } const headings = await page.getHeadings(); - const title = await accelerator.markdown.getTextFrom(page.frontmatter?.title); + const title = await accelerator.markdown.getTextFrom( + page.frontmatter?.title + ); const content = page.compiledContent ? await page.compiledContent() : ''; let counted: { word: string; count: number }[] = []; @@ -50,22 +60,22 @@ const getData = async () => { }); counted = words - .map(w => { + .map((w) => { return { word: w, - count: words.filter(wd => wd === w).length, + count: words.filter((wd) => wd === w).length, }; }) - .filter(e => e.word.replace(/[^a-z]+/g, '').length > 1); + .filter((e) => e.word.replace(/[^a-z]+/g, '').length > 1); } items.push({ title: title, - headings: headings.map(h => { + headings: headings.map((h) => { return { text: h.text, slug: h.slug }; }), description: page.frontmatter.description ?? '', - keywords: counted.map(c => c.word).join(' '), + keywords: counted.map((c) => c.word).join(' '), tags: page.frontmatter.tags ?? [], url: SITE.url + accelerator.urlFormatter.formatAddress(url), date: page.frontmatter.pubDate ?? '', diff --git a/src/pages/docs/sitemap.xml.ts b/src/pages/docs/sitemap.xml.ts index 697fcfcc5e..a35678c523 100644 --- a/src/pages/docs/sitemap.xml.ts +++ b/src/pages/docs/sitemap.xml.ts @@ -4,6 +4,7 @@ import { accelerator } from '@lib/accelerator'; import { SITE } from '@config'; import { PostFiltering } from 'astro-accelerator-utils'; +import { isUnderConstruction } from '@lib/underConstruction'; async function getData() { //@ts-ignore @@ -12,6 +13,11 @@ async function getData() { let pages = []; for (const path in allPages) { + // Temporary - see src/lib/underConstruction.ts. + if (isUnderConstruction(path)) { + continue; + } + const article: any = await allPages[path](); const addToSitemap = PostFiltering.showInSitemap(article); diff --git a/src/plugins/satteri-api-examples.js b/src/plugins/satteri-api-examples.js new file mode 100644 index 0000000000..4695275a64 --- /dev/null +++ b/src/plugins/satteri-api-examples.js @@ -0,0 +1,295 @@ +import { defineHastPlugin, defineMdastPlugin } from 'satteri'; +import { ENDPOINT_CLASS } from './satteri-endpoint.js'; + +// The API pages are written as a flat run of H2 sections, each with a request +// and response example somewhere inside it: +// +// ## Get a list of accounts +// ...parameters, response schema... +// :::api-example{label="Response"} +// ```json +// ``` +// ::: +// +// This regroups each of those sections into +// +//
+//

<- spans both columns +//
<- the prose under the heading +//
<- every api-example in the section +// +// so main.css can put the examples in a column beside the body. The heading +// stays out of both columns and takes a row of its own, which is what starts an +// example level with the bottom of the heading it belongs to. +// +// Anything before the first H2 is left where it is. +// +// Each section's endpoint is also collected here and left on the frontmatter as +// `apiMethods`, in heading order, for ApiNavigation.astro to badge the left nav +// with. It cannot be read from the headings Astro hands the layout: those carry +// text and slug only, and are collected after this plugin runs. The heading text +// is recorded beside the method so the nav can check the two lists still +// describe the same endpoints before it trusts the order. + +/** The container directive an example is written as, and the class it renders to. */ +const DIRECTIVE = 'api-example'; +const EXAMPLE_CLASS = 'api-example'; + +// Sätteri parses the directive but gives it no meaning, and never parses +// embedded HTML at all, so the example has to arrive as a directive to arrive as +// a single node: written as `
` it would reach hast as an opening and a +// closing `raw` node with the block loose between them. +// +// The body is left alone, so a fence inside is highlighted like any other — the +// examples are mostly ```json, but ```xml or ```yaml pass through just the same. +// +// MUST be registered after attributeMarkdown, whose generic handler renders +// every directive as a tag of its own name. Both write the node's `data`, each +// plugin runs its own pass in array order, and the later write is the one that +// survives — as `
` rather than ``. +export const apiExampleDirective = defineMdastPlugin({ + name: 'api-example-directive', + containerDirective(node, ctx) { + if (node.name !== DIRECTIVE) return; + + // An example with no label still lays out beside its section; it is the + // header below that goes without a name rather than the whole block. + const label = node.attributes?.label; + const properties = { class: EXAMPLE_CLASS }; + if (label) properties['data-example'] = label; + + ctx.setProperty(node, 'data', { hName: 'div', hProperties: properties }); + }, +}); + +// Sätteri has no root visitor, so the whole regroup hangs off the H2 filter and +// runs once, on the first H2 in the document. "First" is read off the tree +// rather than remembered in a closure: the later H2s see themselves preceded by +// one and bail, which keeps the plugin free of per-document state. +const HEADING = 'h2'; + +/** Whether a node is an element, optionally of a given tag. */ +function isElement(node, tagName) { + return ( + node?.type === 'element' && (tagName == null || node.tagName === tagName) + ); +} + +// Classes reach hast under either key: the ones this file and shiki-code-block.js +// build carry hast's own `className` array, while anything rendered from a +// directive — the wrapper above, a `:span[GET]{.api-get}` badge — is built from +// the attribute it was written with and carries a plain `class` string. Both +// spellings name the same class, so both are read. +function hasClass(node, className) { + const properties = node.properties ?? {}; + + return [properties.className, properties.class].some((value) => { + if (value == null) return false; + const list = Array.isArray(value) ? value : String(value).split(/\s+/); + return list.includes(className); + }); +} + +function isExample(node) { + return isElement(node, 'div') && hasClass(node, EXAMPLE_CLASS); +} + +/** What an example names its payload, e.g. "Response". */ +function exampleLabel(node) { + return node.properties?.['data-example'] ?? null; +} + +/** An element's text, the way a heading or a code span reads. */ +function text(node) { + if (node.type === 'text') return node.value; + return (node.children ?? []).map(text).join(''); +} + +/** The first `.api-endpoint` anywhere under `nodes`, or null. */ +function findEndpoint(nodes) { + for (const node of nodes) { + if (!isElement(node)) continue; + if (hasClass(node, ENDPOINT_CLASS)) return node; + + const nested = findEndpoint(node.children ?? []); + if (nested) return nested; + } + return null; +} + +/** + * The endpoint a section documents, read off the `:endpoint` directive under + * its heading. Written out by plugins/satteri-endpoint.js, which is the whole + * point of the directive: the method is stated rather than inferred from + * whatever inline markup happens to open the line. + * + * A section with no endpoint — a page of prose between the generated ones — + * simply has none. + */ +function endpoint(nodes) { + const node = findEndpoint(nodes); + if (!node) return { method: null, deprecated: false }; + + return { + method: node.properties?.['data-method'] ?? null, + deprecated: node.properties?.['data-deprecated'] === 'true', + }; +} + +function element(tagName, properties, children) { + return { type: 'element', tagName, properties, children }; +} + +// The pages this runs on: the ones the API layout renders. A handful of them +// document endpoints without giving an example of any of them, and they are +// still laid out as endpoints and still badged in the nav. +const API_LAYOUT = '/Api.astro'; + +function isApiPage(frontmatter) { + return (frontmatter?.layout ?? '').includes(API_LAYOUT); +} + +function hasExampleMarkup(children) { + return children.some(isExample); +} + +/** + * Labels an example with the value of its data-example attribute, reusing the + * code block's own header rather than adding a second one above it. + * + * The nodes are copied rather than edited: they are read out of Sätteri's arena + * and only take effect as the new content handed back to it, so an in-place + * edit would go nowhere. + */ +function labelBlock(node, label, done) { + if (done.value || !isElement(node)) return node; + + if (isElement(node, 'p') && hasClass(node, 'code-block__label')) { + // Set by shiki-code-block.js, hidden while it has nothing to show. + done.value = true; + return { + ...node, + properties: { ...node.properties, hidden: false }, + children: [{ type: 'text', value: label }], + }; + } + + let changed = false; + const children = (node.children ?? []).map((child) => { + const next = labelBlock(child, label, done); + if (next !== child) changed = true; + return next; + }); + + return changed ? { ...node, children } : node; +} + +/** + * Names the block inside an example after the example itself, leaving every + * other node — and an example with nothing to name — exactly as it was found. + */ +function labelExample(node) { + if (!isExample(node)) return node; + + const label = exampleLabel(node); + if (!label) return node; + + // The attribute names what the payload is; the header says what the block is. + const done = { value: false }; + const children = (node.children ?? []).map((child) => + labelBlock(child, `Example ${label}`, done) + ); + + return done.value ? { ...node, children } : node; +} + +/** + * Splits one H2 section into its heading, its body and its examples. + * + * @param {any} heading the H2 the section opens with + * @param {any[]} nodes everything under it, up to the next H2 + */ +function section(heading, nodes) { + const body = []; + const examples = []; + + for (const node of nodes) { + if (isExample(node)) { + examples.push(node); + } else { + body.push(node); + } + } + + const children = [ + heading, + element('div', { className: ['api-section__body'] }, body), + ]; + + // The examples column is left out rather than left empty, but the body keeps + // its width either way: endpoints with and without examples sit in the same + // grid, so the prose measure does not change down the page. + if (examples.length > 0) { + children.push( + element('div', { className: ['api-section__examples'] }, examples) + ); + } + + return element('section', { className: ['api-section'] }, children); +} + +export default defineHastPlugin({ + name: 'api-examples', + element: { + filter: [HEADING], + visit(node, ctx) { + const root = ctx.parent(node); + if (root?.type !== 'root') return; + + // Every H2 is visited, but only the first one does the work. + const index = ctx.indexOf(node) ?? 0; + if (root.children.slice(0, index).some((n) => isElement(n, HEADING))) { + return; + } + + const frontmatter = ctx.data.astro?.frontmatter; + if (!isApiPage(frontmatter) && !hasExampleMarkup(root.children)) return; + + const children = []; + /** One entry per section, in heading order, for the left nav. */ + const methods = []; + /** @type {{heading: any, nodes: any[]} | null} */ + let current = null; + + const close = () => { + if (!current) return; + + methods.push({ + text: text(current.heading).trim(), + ...endpoint(current.nodes), + }); + + children.push(section(current.heading, current.nodes)); + current = null; + }; + + for (const child of root.children.map(labelExample)) { + if (isElement(child, HEADING)) { + close(); + current = { heading: child, nodes: [] }; + } else if (current) { + current.nodes.push(child); + } else { + children.push(child); + } + } + close(); + + // Astro hands the frontmatter straight to the layout, which is the only + // route from here to the page's own nav. + if (frontmatter) frontmatter.apiMethods = methods; + + ctx.setProperty(root, 'children', children); + }, + }, +}); diff --git a/src/plugins/satteri-endpoint.js b/src/plugins/satteri-endpoint.js new file mode 100644 index 0000000000..f643426088 --- /dev/null +++ b/src/plugins/satteri-endpoint.js @@ -0,0 +1,110 @@ +import { defineMdastPlugin } from 'satteri'; + +// The request line of an endpoint on a generated API page: +// +// :endpoint{method="POST" path="/api/users/access-token"} +// +// renders as +// +// +// POST /api/users/access-token +// +// +// The generator used to write the badge and the route out by hand, as +// ``:span[POST]{.api-post} `/api/users/access-token` ``. It read the same, but +// it left the left nav recovering an endpoint's method from arbitrary inline +// markup — the first non-empty child of the first element under each heading, +// badge or code span. One directive states the method instead, and +// plugins/satteri-api-examples.js reads it off `data-method`. +// +// A deprecated endpoint adds the flag: +// +// :endpoint{method="GET" path="/api/\{spaceId\}/channels" deprecated=true} +// +// which sets `data-deprecated` on the line and marks the endpoint's row in the +// nav. The warning a reader sees is still written out as its own +// `:::div{.warning}` block, so the wording stays with the content. + +const DIRECTIVE = 'endpoint'; + +/** The class the endpoint line carries, and the hook the nav reads it by. */ +export const ENDPOINT_CLASS = 'api-endpoint'; + +// The methods api.css has a badge for. Anything else still renders, and still +// reaches the nav, but goes without a badge rather than with an unstyled one. +const METHODS = ['get', 'post', 'put', 'delete']; + +// A path is written inside a quoted directive attribute, and the directive +// parser ends the attribute block at the first unescaped `}` — which every +// route template has, in `/api/{spaceId}/channels`. So the generator escapes +// the braces and this puts them back. The backslash itself escapes too, so it +// is unescaped along with them. +function unescapePath(value) { + return value.replace(/\\([{}\\])/g, '$1'); +} + +function span(properties, children) { + // Any parent node type will do: it exists to carry hName/hProperties, and the + // type it is built from never reaches the output. + return { + type: 'paragraph', + data: { hName: 'span', hProperties: properties }, + children, + }; +} + +// MUST be registered after attributeMarkdown, whose generic handler renders +// every directive as a tag of its own name — `` here. This replaces +// the node outright, so it has to be the later of the two passes. +export const endpointDirective = defineMdastPlugin({ + name: 'endpoint-directive', + textDirective(node, ctx) { + if (node.name !== DIRECTIVE) return; + + const method = (node.attributes?.method ?? '').trim().toLowerCase(); + const path = unescapePath(node.attributes?.path ?? ''); + // `deprecated=true`, `deprecated="true"` and a bare `deprecated` all read + // as set; anything else, including `deprecated=false`, does not. + const flag = node.attributes?.deprecated; + const deprecated = flag === '' || flag === 'true'; + + if (!method || !path) { + ctx.report({ + message: `:${DIRECTIVE} needs both a method and a path`, + node, + severity: 'error', + }); + return; + } + + if (!METHODS.includes(method)) { + ctx.report({ + message: `:${DIRECTIVE} method "${method}" has no badge in src/styles/api.css`, + node, + severity: 'warning', + }); + } + + const badge = METHODS.includes(method) + ? [ + span({ class: `api-${method}` }, [ + { type: 'text', value: method.toUpperCase() }, + ]), + { type: 'text', value: ' ' }, + ] + : [{ type: 'text', value: `${method.toUpperCase()} ` }]; + + return span( + { + class: ENDPOINT_CLASS, + 'data-method': method, + // Sätteri drops undefined properties, so the attribute is absent + // rather than present and false. + 'data-deprecated': deprecated ? 'true' : undefined, + }, + [...badge, { type: 'inlineCode', value: path }] + ); + }, +}); + +export default endpointDirective; diff --git a/src/scripts/main.js b/src/scripts/main.js index 7ede0ee7eb..90584d1510 100644 --- a/src/scripts/main.js +++ b/src/scripts/main.js @@ -31,6 +31,9 @@ monitorInputType(); enableSharing(); highlightCurrentHeading('.page-toc a'); highlightCurrentHeading('.article-nav a'); +// The API section lists the current page's endpoints in the left nav instead +// of a table of contents, so that list tracks the reader the same way. +highlightCurrentHeading('.site-nav__link--heading'); // @ts-ignore const f = site_features ?? {}; diff --git a/src/styles/api.css b/src/styles/api.css index db2a269d7d..284fbd86ba 100644 --- a/src/styles/api.css +++ b/src/styles/api.css @@ -1,3 +1,154 @@ +/* ----- General styles for the API and CLI pages ----- */ + +.type-label { + color: var(--colorTextInfo); +} + +/* ----- The API docs have a different layout than the rest of the docs ----- */ + +/* +On API pages the top level of the body is the body column of an endpoint +rather than .page-content itself, because satteri-api-examples.js wraps each +section so its examples can sit beside it. */ +.api-section__body > *:not(:is(h2, h3, h4, h5, h6)), +.api-section__body > blockquote > *:not(:last-child), +.api-section__body > div.info > *:not(:last-child), +.api-section__body > div.success > *:not(:last-child), +.api-section__body > div.warning > *:not(:last-child), +.api-section__body > div.problem > *:not(:last-child), +.api-section__body > div.question > *:not(:last-child), +.api-section__body > div.hint > *:not(:last-child) { + margin-block-end: var(--space16); +} + +/* API reference + Pages on src/layouts/Api.astro: their own left nav, no table of contents, + and each endpoint split into a body and an examples column by + plugins/satteri-api-examples.js. */ + +/* The article does not take the article/toc tracks the rest of the site is laid + out on, but it is centred the same way they are: a flexible gutter either + side of it, so the pair of columns sits in the middle of what the nav leaves, + never closer than space/16 to either end. */ +.content-group--api { + grid-template-columns: + var(--navigation-width) + minmax(var(--space16), 1fr) + minmax(var(--api-columns-min-width), var(--api-columns-width)) + minmax(var(--space16), 1fr); + grid-template-areas: + 'menu . content .' + 'menu . footer .'; +} + +/* Endpoints are the only thing on these pages, so the space between them is the + space an h2 would have carried, taken off the heading and put on the section. + + The heading takes a row of its own, which is what starts an example level + with the bottom of the heading it belongs to rather than the top, and with + the first line of the endpoint beside it. + + The pair is centred by the article's own gutters above, so the space between + the two columns is fixed and they compress together into whatever the article + is given. */ +.api-section { + display: grid; + grid-template-columns: + minmax(var(--api-content-min-width), var(--api-content-width)) + minmax(var(--api-examples-min-width), var(--api-examples-width)); + grid-template-areas: + 'heading .' + 'body examples'; + column-gap: var(--api-columns-gap); + margin-block-start: var(--space56); +} + +.api-section > h2 { + grid-area: heading; + margin-block-start: 0; +} + +.api-section__body { + grid-area: body; +} + +.api-section__examples { + grid-area: examples; +} + +/* Anything outside an endpoint — the introduction on the index page — takes the + width of an endpoint rather than the width of the article, so the measure is + the same everywhere in the section. */ +.content-group--api .page-content > :not(.api-section) { + max-width: var(--api-content-width); +} + +/* The heading above has already paid for the gap this would add. */ +.api-section__examples > .api-example:first-child .code-block { + margin-block-start: 0; +} + +/* Side by side, the two columns need the nav plus a gutter, both minimums and + the space between them: 320 + 16 + 420 + 32 + 400 + 16 = 1204px. Below that + an example goes back to being part of the endpoint it documents, and the + article gives up its minimum width along with them. */ +@media (max-width: 1220px) { + .content-group--api { + grid-template-columns: + var(--navigation-width) + minmax(var(--space16), 1fr) + minmax(0, var(--api-columns-width)) + minmax(var(--space16), 1fr); + } + + .api-section { + grid-template-columns: minmax(0, 1fr); + grid-template-areas: + 'heading' + 'body' + 'examples'; + } + + .content-group--api .page-content > :not(.api-section) { + max-width: none; + } + + .api-section__examples { + margin-block-start: var(--space24); + } +} + +@media (max-width: 1130px) { + /* The same stack as every other page, one row shorter because there is no + toc. Restated here rather than beside the rest of the restack, because the + tracks it replaces are set at the same specificity further up. */ + .content-group--api { + grid-template-columns: 1rem auto 1rem; + grid-template-areas: + 'left top right' + 'left content right' + 'left menu right' + 'left footer right'; + } +} + +/* ----- Styles for API badges ----- */ + +/* A deprecated endpoint keeps its badge and its row, and reads as secondary + until the reader opens it. The page itself carries the warning in full. */ +.site-nav__link--deprecated .site-nav__label { + color: var(--color-text-tertiary); + text-decoration: line-through; +} + +/* A badge in the left nav labels the endpoint the row links to. The row starts + its items at the top, so the badge overrides that and centres on the title it + belongs to however many lines that title runs to. */ +.site-nav__link > :is(.api-get, .api-post, .api-delete, .api-put) { + flex: none; + align-self: center; +} + :is(.api-get, .api-post, .api-delete, .api-put) { box-sizing: border-box; display: inline-flex; diff --git a/src/styles/main.css b/src/styles/main.css index 0277702a36..659e2d3e81 100644 --- a/src/styles/main.css +++ b/src/styles/main.css @@ -1358,6 +1358,14 @@ html[data-theme='dark'] img.card__icon { color: var(--colorTextSelected); } +/* The API nav lists the current page's endpoints in place of a table of + contents, so the row for the endpoint in view is marked the way one is + there: `highlight` comes from scripts/modules/toc.js. */ +.site-nav__link--heading.highlight { + background-color: var(--navBackgroundActive); + color: var(--colorTextSelected); +} + /* An expanded section is the only row that goes bold. */ .site-nav__group[open] > .site-nav__link { font: var(--textBodyBoldMedium); diff --git a/src/styles/vars.css b/src/styles/vars.css index 1fef3bb782..e566ac3607 100644 --- a/src/styles/vars.css +++ b/src/styles/vars.css @@ -224,6 +224,24 @@ --toc-width: 250px; /* Space between the article and the toc beside it. */ --toc-offset: 80px; + /* The two columns of an API reference page: the endpoint and the request and + response examples beside it. Each takes its full width wherever there is + room, and the pair compress together down to their minimums before the + examples drop below the endpoint instead. */ + --api-content-width: 680px; + --api-content-min-width: 420px; + --api-examples-width: 640px; + --api-examples-min-width: 400px; + --api-columns-gap: var(--space32); + /* The pair together, which is what the article is centred on. */ + --api-columns-width: calc( + var(--api-content-width) + var(--api-columns-gap) + + var(--api-examples-width) + ); + --api-columns-min-width: calc( + var(--api-content-min-width) + var(--api-columns-gap) + + var(--api-examples-min-width) + ); --grid-max-width: 1250px; --grid-gap: 1rem; --grid-gap-main: 1rem; diff --git a/src/themes/octopus/components/Breadcrumbs.astro b/src/themes/octopus/components/Breadcrumbs.astro index 8dcc818602..f2a790c3f6 100644 --- a/src/themes/octopus/components/Breadcrumbs.astro +++ b/src/themes/octopus/components/Breadcrumbs.astro @@ -23,16 +23,24 @@ stats.stop();