Humanitec public API
The public API from Humanitec — 141 operation(s) for public.
OpenAPI Specification
openapi: 3.0.0
info:
title: Humanitec AccountType public API
version: 0.28.24
description: '# Introduction
The *Humanitec API* allows you to automate and integrate Humanitec into your developer and operational workflows.
The API is a REST based API. It is based around a set of concepts:
* Core
* External Resources
* Sets and Deltas
## Authentication
Almost all requests made to the Humanitec API require Authentication. See our [Developer Docs on API Authentication](https://developer.humanitec.com/platform-orchestrator/reference/api-references/#authentication) for instructions.
## Content Types
The Humanitec API, unless explicitly specified, only accepts content types of `application/json` and will always return valid `application/json` or an empty response.
## Response Codes
### Success
Any response code in the `2xx` range should be regarded as success.
| **Code** | **Meaning** |
|----------|-------------------------------------|
| `200` | Success |
| `201` | Success, a new resource was created |
| `204` | Success, but no content in response |
_Note: We plan to simplify the interface by replacing 201 with 200 status codes._
### Failure
Any response code in the `4xx` range should be regarded as an error that can be rectified by the client. `5xx` error codes indicate errors that cannot be corrected by the client.
| **Code** | **Meaning** |
|----------|-----------------------------------------------------------------------------------------------------------------------|
| `400` | General error. (Body will contain details) |
| `401` | Attempt to access protected resource without `Authorization` Header. |
| `403` | The `Bearer` or `JWT` does not grant access to the requested resource. |
| `404` | Resource not found. |
| `405` | Method not allowed |
| `409` | Conflict. Usually indicated a resource with that ID already exists. |
| `422` | Unprocessable Entity. The body was not valid JSON, was empty or contained an object different from what was expected. |
| `429` | Too many requests - request rate limit has been reached. |
| `500` | Internal Error. If it occurs repeatedly, contact support. |
'
contact:
name: Humanitec Support
email: support@humanitec.com
x-logo:
url: humanitec-logo.png
altText: Humanitec logo
servers:
- url: https://api.humanitec.io/
tags:
- name: public
paths:
/orgs/{orgId}/agents:
post:
tags:
- public
operationId: createAgent
summary: Register a new Agent under an Organization.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentCreateBody'
responses:
'200':
description: Agent registered.
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'400':
$ref: '#/components/responses/400BadRequest'
'409':
$ref: '#/components/responses/409Conflict'
get:
tags:
- public
operationId: listAgents
summary: List all the agents in an Organization.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/fingerprintQueryParam'
responses:
'200':
description: Successful list response.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Agent'
/orgs/{orgId}/agents/{agentId}:
delete:
tags:
- public
operationId: deleteAgent
summary: Delete an Agent (and its keys) stored under an Organization.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/agentIdPathParam'
responses:
'204':
description: Agent successfully deleted.
'404':
$ref: '#/components/responses/404NotFound'
patch:
tags:
- public
operationId: patchAgent
summary: Update the description of an Agent.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/agentIdPathParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentPatchBody'
responses:
'200':
description: Agent updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
'400':
$ref: '#/components/responses/400BadRequest'
'404':
$ref: '#/components/responses/404NotFound'
/orgs/{orgId}/agents/{agentId}/keys:
get:
tags:
- public
operationId: listKeysInAgent
summary: List all the keys registered under an Agent in an Organization.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/agentIdPathParam'
responses:
'200':
description: Successful list response.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Key'
'404':
$ref: '#/components/responses/404NotFound'
post:
tags:
- public
operationId: createKey
summary: Register a new Key under an Agent in an Organization.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/agentIdPathParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/KeyCreateBody'
responses:
'200':
description: Successful list response.
content:
application/json:
schema:
$ref: '#/components/schemas/Key'
'400':
$ref: '#/components/responses/400BadRequest'
'404':
$ref: '#/components/responses/404NotFound'
'409':
$ref: '#/components/responses/409Conflict'
/orgs/{orgId}/agents/{agentId}/keys/{fingerprint}:
delete:
tags:
- public
operationId: deleteKeyInAgent
summary: Delete a key registered under a Agent.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/agentIdPathParam'
- $ref: '#/components/parameters/fingerprintPathParam'
responses:
'204':
description: Key successfully deleted.
'404':
$ref: '#/components/responses/404NotFound'
/orgs/{orgId}/apps:
get:
tags:
- public
summary: List all Applications in an Organization.
operationId: listApplications
description: Listing or lists of all Applications that exist within a specific Organization.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
responses:
'200':
description: Possibly empty list of Applications.
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ApplicationResponse'
type: array
example:
- created_at: '2020-06-15T09:32:03Z'
created_by: a-user@example.com
envs:
id: development
name: Development
type: development
id: my-app
name: My Awesome App
post:
tags:
- public
summary: Add a new Application to an Organization
operationId: createApplication
description: Creates a new Application, then adds it to the specified Organization.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
requestBody:
description: 'The request ID, Human-friendly name and environment of the Application.
'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationCreationRequest'
responses:
'201':
description: 'The Application requested.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationResponse'
example:
created_at: '2020-06-15T09:32:03Z'
created_by: a-user@example.com
envs:
id: development
name: Development
type: development
id: my-app
name: My Awesome App
'400':
description: 'The request body was unparseable.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'401':
description: 'The Authorization header was not present or invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'409':
description: 'The supplied `id` clashes with an existing Application.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/apps/{appId}:
get:
tags:
- public
summary: Get an existing Application
operationId: getApplication
description: Gets a specific Application in the specified Organization by ID.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: appId
in: path
description: 'The Application ID.
'
required: true
schema:
type: string
responses:
'200':
description: 'The Application requested.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationResponse'
example:
created_at: '2020-06-15T09:32:03Z'
created_by: a-user@example.com
envs:
id: development
name: Development
type: development
id: my-app
name: My Awesome App
'404':
description: 'No Application with ID `appId` in Organization.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
patch:
tags:
- public
summary: Update metadata of an existing Application
operationId: patchApplication
description: Update metadata of an existing Application in the specified Organization.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/appIdPathParam'
requestBody:
description: The Application patch request. Only the field `name` can be updated.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationPatchPayload'
responses:
'200':
description: Application updated.
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationResponse'
example:
created_at: '2020-06-15T09:32:03Z'
created_by: a-user@example.com
envs:
id: development
name: Development
type: development
id: my-app
name: My Awesome App
'404':
description: No Application with ID `appId` in Organization.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
delete:
tags:
- public
summary: Delete an Application
operationId: deleteApplication
description: 'Deleting an Application will also delete everything associated with it. This includes Environments, Deployment history on those Environments, and any shared values and secrets associated.
_Deletions are currently irreversible._'
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: appId
in: path
description: 'The Application ID.
'
required: true
schema:
type: string
responses:
'204':
description: 'Application Successfully deleted.
'
'202':
description: 'Application deletion is in progress.
'
'401':
description: 'The Authorization header was not present or invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'No Application with `id` in Organization.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/apps/{appId}/envs:
get:
tags:
- public
summary: List all Environments.
operationId: listEnvironments
description: Lists all of the Environments in the Application.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: appId
in: path
description: 'The Application ID.
'
required: true
schema:
type: string
responses:
'200':
description: 'A list of Environments associated with an Application.
'
content:
application/json:
schema:
items:
$ref: '#/components/schemas/EnvironmentResponse'
type: array
example:
- {}
post:
tags:
- public
summary: Add a new Environment to an Application.
operationId: createEnvironment
description: 'Creates a new Environment of the specified Type and associates it with the Application specified by `appId`.
The Environment is also initialized to the **current or past state of Deployment in another Environment**. This ensures that every Environment is derived from a previously known state. This means it is not possible to create a new Environment for an Application until at least one Deployment has occurred. (The Deployment does not have to be successful.)
The Type of the Environment must be already defined in the Organization.'
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: appId
in: path
description: 'The Application ID.
'
required: true
schema:
type: string
requestBody:
description: 'The ID, Name, Type, and Deployment the Environment will be derived from.
'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentDefinitionRequest'
example:
from_deploy_id: e80db1a327208c1a
id: awesome-feature
name: Awesome Feature Dev
namespace: awesome-namespace
type: development
responses:
'201':
description: 'The new Environment.
'
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentResponse'
example: {}
'400':
description: 'The supplied `id` is an invalid ID or a required field is missing.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'No Application with `id` in Organization.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'409':
description: 'The supplied `id` clashes with an existing Environment.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/apps/{appId}/envs/{envId}:
get:
tags:
- public
summary: Get a specific Environment.
operationId: getEnvironment
description: Gets a specific Environment in an Application.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: appId
in: path
description: 'The Application ID.
'
required: true
schema:
type: string
- name: envId
in: path
description: 'The Environment ID.
'
required: true
schema:
type: string
responses:
'200':
description: 'The Environment requested.
'
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentResponse'
example: {}
'404':
description: 'No Environment with `id` in Application.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
patch:
tags:
- public
summary: Update a specific Environment.
operationId: updateEnvironment
description: Update a specific Environment in an Application.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: appId
in: path
description: 'The Application ID.
'
required: true
schema:
type: string
- name: envId
in: path
description: 'The Environment ID.
'
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentBaseUpdateRequest'
responses:
'200':
description: 'The updated Environment.
'
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentResponse'
example: {}
'404':
description: 'No Environment with `id` in Application.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
delete:
tags:
- public
summary: Delete a specific Environment.
operationId: deleteEnvironment
description: 'Deletes a specific Environment in an Application.
Deleting an Environment will also delete the Deployment history of the Environment.
_Deletions are currently irreversible._'
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: appId
in: path
description: 'The Application ID.
'
required: true
schema:
type: string
- name: envId
in: path
description: 'The Environment ID.
'
required: true
schema:
type: string
responses:
'204':
description: 'Environment successfully deleted.
'
'202':
description: 'Environment deletion is in progress.
'
'400':
description: 'Attempt to delete the last Environment in an Application.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'No Environment with `envId` in Application.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/apps/{appId}/envs/{envId}/deploys:
get:
tags:
- public
summary: List Deployments in an Environment.
description: List all of the Deployments that have been carried out in the current Environment. Deployments are returned with the newest first.
operationId: listDeployments
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: appId
in: path
description: 'The Application ID.
'
required: true
schema:
type: string
- name: envId
in: path
description: 'The Environment ID.
'
required: true
schema:
type: string
- name: pipelineRunId
in: query
description: 'An optional filter by the Pipeline and Pipeline Run ID separated by a comma.
'
example: default,01234567-89ab-cdef-0123-456789abcdef
schema:
type: string
responses:
'200':
description: 'A possibly empty list of Deployments.
'
content:
application/json:
schema:
items:
$ref: '#/components/schemas/DeploymentResponse'
type: array
example:
- {}
'404':
description: 'No Environment with `id` in Application.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
post:
tags:
- public
summary: Start a new Deployment.
operationId: createDeployment
description: 'At Humanitec, Deployments are defined as changes to the state of the Environment. The state can be changed by defining a set of desired changes to the current state via a Deployment Delta or by resetting the current state after a previous Deployment. (See Environment Rebase.) Both types of changes can be combined into a single Deployment during which the Delta is applied to the Rebased state.
When specifying a Delta, a Delta ID must be used. That Delta must have been committed to the Delta store prior to the Deployment.
A Set ID can also be defined in the deployment to force the state of the environment to a particular state. This will be ignored if the Delta is specified.
**NOTE:**
Directly setting a `set_id` in a deployment is not recommended as it will not record history of where the set came from. If the intention is to replicate an existing environment, use the environment rebasing approach described above.'
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: appId
in: path
description: 'The Application ID.
'
required: true
schema:
type: string
- name: envId
in: path
description: 'The Environment ID.
'
required: true
schema:
type: string
requestBody:
description: 'The Delta describing the change to the Environment and a comment.
'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentRequest'
example:
comment: Updated version of module-one to v0.3.1
delta_id: df1ad41807b0390a9b0eaf8688e1f5baece9d764
responses:
'201':
description: 'A description of the Deployment.
'
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentResponse'
'400':
description: 'Error because the Delta is non-existent or incompatible with the state of the Environment.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'No Environment with `id` in Application.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'409':
description: 'There is already an active deployment in the Environment.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/apps/{appId}/envs/{envId}/deploys/{deployId}:
get:
tags:
- public
summary: Get a specific Deployment.
description: Gets a specific Deployment in an Application and an Environment.
operationId: getDeployment
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: appId
in: path
description: 'The Application ID.
'
required: true
schema:
type: string
- name: envId
in: path
description: 'The Environment ID.
'
required: true
schema:
type: string
- name: deployId
in: path
description: 'The Deployment ID.
'
required: true
schema:
type: string
responses:
'200':
description: 'The Deployment requested.
'
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentResponse'
example: {}
'404':
description: 'No Deployment with `deployId` in Application and Environment.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/apps/{appId}/envs/{envId}/deploys/{deployId}/errors:
get:
tags:
- public
summary: List errors that occurred in a Deployment.
operationId: listDeploymentErrors
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: appId
in: path
description: 'The Application ID.
'
required: true
schema:
type: string
- name: envId
in: path
description: 'The Environment ID.
'
required: true
schema:
type: string
- name: deployId
in: path
description: 'The Deployment ID.
'
required: true
schema:
type: string
responses:
'200':
description: 'A List of deployment errors, could be empty.
'
content:
application/json:
schema:
items:
$ref: '#/components/schemas/DeploymentErrorResponse'
type: array
example:
- code: CLD-001
message: Incorrect credentials
object_id: my-service
scope: workload
/orgs/{orgId}/apps/{appId}/envs/{envId}/from_deploy_id:
put:
tags:
- public
summary: Rebase to a different Deployment.
operationId: rebaseEnvironment
description: 'Rebasing an Environment means that the next Deployment to the Environment will be based on the Deployment specified in the rebase rather than the last one in the Environment. The Deployment to rebase to can either be current or a previous Deployment. The Deployment can be from any Environment of the same Application.
_Running code will only be affected on the next Deployment to the Environment._
Common use cases for rebasing an Environment:
* _Rollback_: Rebasing to a previous Deployment in the current Environment and then Deploying without additional changes will execute a rollback to the previous Deployment state.
* _Clone_: Rebasing to the current Deployment in a different Environment and then deploying without additional changes will clone all of the configuration of the other Environment into the current one. (NOTE: External Resources will not be cloned in the process - the current External Resources of the Environment will remain unchanged and will be used by the deployed Application in the Environment.'
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: appId
in: path
description: 'The Application ID.
'
required: true
schema:
type: string
- name: envId
in: path
description: 'The Environment ID.
'
required: true
schema:
type: string
requestBody:
description: 'The Deployment ID to rebase to.
'
required: true
content:
application/json:
schema:
type: string
responses:
'204':
description: 'Rebase successful.
'
'400':
description: 'No Deployment with ID found in Application.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'No Environment with ID found in Application and Organization.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/env-types:
get:
tags:
- public
summary: List all Environment Types
operationId: listEnvironmentTypes
description: Lists all Environment Types in an Organization.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
responses:
'200':
description: 'A list of Environment Types.
'
content:
application/json:
schema:
items:
$ref: '#/compone
# --- truncated at 32 KB (497 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/humanitec/refs/heads/main/openapi/humanitec-public-api-openapi.yml