diff --git a/src/assets/icons/dotnet.svg b/src/assets/icons/dotnet.svg new file mode 100644 index 0000000000..7e07ca72ed --- /dev/null +++ b/src/assets/icons/dotnet.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/src/assets/icons/go.svg b/src/assets/icons/go.svg new file mode 100644 index 0000000000..1e2545e37e --- /dev/null +++ b/src/assets/icons/go.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/src/assets/icons/slack.svg b/src/assets/icons/slack.svg new file mode 100644 index 0000000000..2a66b2cba5 --- /dev/null +++ b/src/assets/icons/slack.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/src/assets/icons/typescript.svg b/src/assets/icons/typescript.svg new file mode 100644 index 0000000000..5c7567355e --- /dev/null +++ b/src/assets/icons/typescript.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/src/assets/icons/youtube.svg b/src/assets/icons/youtube.svg new file mode 100644 index 0000000000..a24c741579 --- /dev/null +++ b/src/assets/icons/youtube.svg @@ -0,0 +1,4 @@ + + + + diff --git a/src/layouts/Api.astro b/src/layouts/Api.astro index b584c954ae..54552b1bbf 100644 --- a/src/layouts/Api.astro +++ b/src/layouts/Api.astro @@ -38,8 +38,6 @@ type Props = { const { frontmatter, headings, breadcrumbs } = Astro.props satisfies Props; const area = resolveArea(frontmatter.area, Astro.url.pathname); -// The API section has no page of its own at /docs/api for the generic crumb -// walk to find, so buildAreaCrumbs splices the crumb in for it. const crumbs = buildAreaCrumbs(Astro.url, area, breadcrumbs); const lang = frontmatter.lang ?? SITE.default.lang; diff --git a/src/pages/docs/api/index.md b/src/pages/docs/api/index.md deleted file mode 100644 index 633046b7b3..0000000000 --- a/src/pages/docs/api/index.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -layout: src/layouts/Default.astro -pubDate: 2026-08-21 -modDate: 2026-08-21 -title: Get started with the Octopus REST API -navTitle: Get started -crumbTitle: API -description: Getting started with the Octopus REST API -navOrder: 1 -hideInThisSectionHeader: true ---- - -## API clients - -Octopus provides API clients for popular programming languages and runtime environments. You can access the source code for these clients on GitHub: - -- [Go API Client for Octopus Deploy](https://github.com/OctopusDeploy/go-octopusdeploy) -- [.NET C# API Client for Octopus Deploy](https://github.com/OctopusDeploy/OctopusClients) -- [TypeScript API Client for Octopus Deploy](https://github.com/OctopusDeploy/api-client.ts) - -Code snippets using these clients for operations in the Octopus REST API are available in our [API examples](/docs/octopus-rest-api/examples) documentation. - -## REST API authentication \{#authentication} - -The Octopus Deploy API is available at: - -```text -https:///api -``` - -Replace `` with the URL that you host your Octopus instance on. - -The API supports 2 methods of authentication. - -### Creating an API Key - -You can get your API key from your profile page on the Octopus Web Portal. - -After you have a key, you can provide it to the API in the following ways: - -1. Through the `X-Octopus-ApiKey` HTTP header with all requests. This is the preferred approach. -1. As an `apikey` query string parameter with all requests. You should only be used for simple requests. - -:::div{.hint} -Learn more about [how to create an API key](/docs/octopus-rest-api/how-to-create-an-api-key). -::: - -### OpenID Connect - -OpenID Connect is a set of identity specifications that build on OAuth 2.0 to let software systems connect in a way that promotes security best practices. - -When using OIDC, Octopus validates an identity token from a trusted external system using [public key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography). Octopus then issues a short-lived access token that you can use to interact with the Octopus API. - -Some of the benefits of using OIDC in Octopus include: - -- You don't need to provision API keys and store them in external systems. This reduces the risk of unauthorized access to the Octopus API from exposed keys. -- Administrators don't need to rotate API keys manually. This reduces the risk of disruption when updating to newer keys in external systems. -- Access tokens issued by Octopus are short-lived. This reduces the risk of unauthorized access to the Octopus API. -- Access tokens are only issued for requests from trusted external systems. This allows for controlled access to service accounts and promotes the principle of least access. - -We support any issuer that can generate signed OIDC tokens that can be validated anonymously. However, we provide built-in support for GitHub Actions with the [OctopusDeploy/login](https://github.com/OctopusDeploy/login) action. - -For more information see [Using OpenId Connect with the Octopus API](https://octopus.com/docs/octopus-rest-api/openid-connect). - -## REST API Swagger documentation \{#api-swagger-docs} - -Octopus includes the default Swagger UI for displaying the API documentation in a nice, human, readable way. To browse that UI just open your browser and go to `https:///swaggerui/`. The original Non-Swagger API page is still available and you can access it via `https:///api/`. - -:::figure -![Server API](/docs/img/octopus-rest-api/images/server-api.png) -::: - -You can view the API through the Octopus Demo server at [demo.octopus.app/swaggerui/index.html](https://demo.octopus.app/swaggerui/index.html). - -## REST API links \{#api-links} - -All resources returned by the REST API contain links to other resources. The idea is that instead of memorizing or hard-coding URLs when using the API, you should start with the root API resource and use links to navigate. - -For example, a `GET` request to `/api` returns a resource that looks like: - -```json -{ - "Application": "Octopus Deploy", - "Version": "2022.1.2386", - "ApiVersion": "3.0.0", - "InstallationId": "9f155416-5d9e-4e19-ba58-b710d4edf336", - "Links": { - "Self": "/api", - "Accounts": "/api/Spaces-1/accounts{/id}{?skip,take,ids,partialName,accountType}", - "Environments": "/api/Spaces-1/environments{/id}{?name,skip,ids,take,partialName}", - "Machines": "/api/Spaces-1/machines{/id}{?skip,take,name,ids,partialName,roles,isDisabled,healthStatuses,commStyles,tenantIds,tenantTags,environmentIds,thumbprint,deploymentId,shellNames,deploymentTargetTypes}", - "Projects": "/api/Spaces-1/projects{/id}{?name,skip,ids,clone,take,partialName,clonedFromProjectId}", - "RunbookProcesses": "/api/Spaces-1/runbookProcesses{/id}{?skip,take,ids}", - "RunbookRuns": "/api/Spaces-1/runbookRuns{/id}{?skip,take,ids,projects,environments,tenants,runbooks,taskState,partialName}", - "Runbooks": "/api/Spaces-1/runbooks{/id}{?skip,take,ids,partialName,clone,projectIds}", - "RunbookSnapshots": "/api/Spaces-1/runbookSnapshots{/id}{?skip,take,ids,publish}", - "Feeds": "/api/feeds{/id}{?skip,take,ids,partialName,feedType,name}", - "Tasks": "/api/tasks{/id}{?skip,active,environment,tenant,runbook,project,name,node,running,states,hasPendingInterruptions,hasWarningsOrErrors,take,ids,partialName,spaces,includeSystem,description,fromCompletedDate,toCompletedDate,fromQueueDate,toQueueDate,fromStartDate,toStartDate}", - "Variables": "/api/Spaces-1/variables{/id}{?ids}", - "Web": "/app" - } -} -``` - -:::div{.hint} -Note: the `Links` collection example above has been significantly reduced in size for demonstration purposes. -::: - -You can follow the links in the result to navigate around the API. For example, by following the `Projects` link, you'll find a list of the projects on your Octopus server. - -Since the format and structure of links may change, it's essential that clients avoid hardcoding URL's to resources, and instead rely on starting at `/api` and navigating from there. - -### URI templates - -Some links (mainly to collections) use URI templates as defined in [RFC 6570](http://tools.ietf.org/html/rfc6570). If in doubt, a client should assume that any link is a URI template. - -### Collections - -Collections of resources also include links. For example, following the `Environments` link above will give you a list of environments. - -```json -{ - "ItemType": "Environment", - "TotalResults": 20, - "ItemsPerPage": 10, - "NumberOfPages": 2, - "LastPageNumber": 1, - "Items": [ - // ... a list of environments ... - ], - "Links": { - "Self": "/api/Spaces-1/environments?skip=0&take=10", - "Template": "/api/Spaces-1/environments{?skip,ids,take,partialName}", - "Page.All": "/api/Spaces-1/environments?skip=0&take=2147483647", - "Page.Next": "/api/Spaces-1/environments?skip=10&take=10", - "Page.Current": "/api/Spaces-1/environments?skip=0&take=10" - } -} -``` - -The links at the bottom of the resource allow you to traverse the pages of results. Again, instead of hard-coding query string parameters, you can look for a `Page.Next` link and follow that instead. - -## REST API and Spaces \{#api-and-spaces} - -If you are using spaces, you need to include the `SpaceID` in your API calls. If you do not include the `SpaceID`, your API calls will automatically use the default space. - -## REST API code samples \{#api-samples} - -Code snippet samples for various operations in the Octopus REST API are available both in our [API examples](/docs/octopus-rest-api/examples) and on the [OctopusDeploy-API GitHub repository](https://github.com/OctopusDeploy/OctopusDeploy-Api) diff --git a/src/pages/docs/api/index.mdx b/src/pages/docs/api/index.mdx new file mode 100644 index 0000000000..3ef5ebbba0 --- /dev/null +++ b/src/pages/docs/api/index.mdx @@ -0,0 +1,99 @@ +--- +layout: src/layouts/Default.astro +pubDate: 2026-08-20 +modDate: 2026-08-20 +title: Octopus API +navTitle: Get started +crumbTitle: API +navOrder: 1 +apiHub: true +description: Create releases, trigger deployments, run runbooks, and manage variables and infrastructure programmatically with the Octopus REST API. +subtitle: The Octopus web portal is built on this API, so anything you can click, you can script. Create releases, trigger deployments, run runbooks, and manage variables and infrastructure programmatically. +--- +import Button from 'src/components/Button.astro'; +import Card from 'src/components/Card.astro'; +import arrowUpRightIcon from 'src/assets/icons/arrow-up-right.svg'; +import goIcon from 'src/assets/icons/go.svg'; +import dotnetIcon from 'src/assets/icons/dotnet.svg'; +import typescriptIcon from 'src/assets/icons/typescript.svg'; +import slackIcon from 'src/assets/icons/slack.svg'; +import youtubeIcon from 'src/assets/icons/youtube.svg'; + +
+ + +## Test endpoints + +Explore endpoints interactively via Swagger - served by your own instance. + +```text +https:///swaggerui/ +``` + +:::div{.hint} +Our docs cover the latest version of the Octopus REST API. If you're on a Long Term Support (LTS) version, some endpoints and values may differ. Use the Swagger UI served by your own instance (see above) as the source of truth for your version. +::: + +## Common tasks + +
+ + + + + + + + +
+ +## API clients + +
+ + + + + +
+ +## More resources + +
+ + + + +
+ +
diff --git a/src/styles/api.css b/src/styles/api.css index 8704c05377..45c78b71f7 100644 --- a/src/styles/api.css +++ b/src/styles/api.css @@ -240,3 +240,27 @@ section so its examples can sit beside it. */ mask-image: url('../assets/icons/pen-line.svg'); mask-size: 90% 80%; } + +/* ----- The API hub page (/docs/api) ----- */ + +/* The hub is a landing page, not an endpoint reference: its content nests + inside .api-hub rather than sitting at the top level of .page-content, + which keeps plugins/satteri-api-examples.js from regrouping its headings + into the two-column endpoint layout above (that plugin only touches + headings that are direct children of the document root). It gets the + design's own width instead of the endpoint body measure. */ +.content-group--api .page-content > .api-hub { + max-width: 1140px; +} + +/* h2's own margin-block-start (56px, set in main.css) plus this padding gives + each hub section an 80px gap from the one before it. */ +.api-hub h2 { + padding-block-start: var(--space24); +} + +/* The header (title + subtitle) sits outside .page-content, so it needs its + own rule to match the same width. */ +.article--api-hub .header { + max-width: 1140px; +} diff --git a/src/styles/main.css b/src/styles/main.css index 63d8cf83b9..65eedb52c6 100644 --- a/src/styles/main.css +++ b/src/styles/main.css @@ -1617,6 +1617,16 @@ a[data-youtube] { padding-block-start: var(--space32); } +.page-content:has(> :is(a, button, h1, h2, h3, h4, h5, h6):first-child), +.page-content:has( + > .api-hub > :is(a, button, h1, h2, h3, h4, h5, h6):first-child +) { + /* The API hub page's content nests inside .api-hub (see api.css) rather + than sitting directly in .page-content, so its own first child needs + checking too. */ + padding-block-start: var(--space0); +} + /* Paging */ .post-paging {