Deployments represent updates to the running state of an Environment. Deployments are made by applying _Deltas_ to a state defined by an existing Deployment. The Environment’s from_deploy property defines the Deployment. This Deployment is usually but not always in the current Environment. If the Deployment is from another Environment, the state of that Environment will be "cloned" into the current Environment with the option to apply a Delta.
openapi: 3.0.0
info:
title: Humanitec AccountType Deployment 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: Deployment
x-displayName: Deployments
description: 'Deployments represent updates to the running state of an Environment.
Deployments are made by applying _Deltas_ to a state defined by an existing Deployment. The Environment’s from_deploy property defines the Deployment. This Deployment is usually but not always in the current Environment. If the Deployment is from another Environment, the state of that Environment will be "cloned" into the current Environment with the option to apply a Delta.
<SchemaDefinition schemaRef="#/components/schemas/DeploymentRequest" />
'
paths:
/orgs/{orgId}/apps/{appId}/envs/{envId}/deploys:
get:
tags:
- Deployment
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:
- Deployment
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:
- Deployment
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:
- Deployment
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
components:
schemas:
DeploymentResponse:
description: 'Deployments represent updates to the running state of an Environment.
Deployments are made by applying _Deltas_ to a state defined by an existing Deployment. The Environment’s from_deploy property defines the Deployment. This Deployment is usually but not always in the current Environment. If the Deployment is from another Environment, the state of that Environment will be "cloned" into the current Environment with the option to apply a Delta.'
example:
comment: Updated version of module-one to v0.3.1
created_at: '2020-05-22T14:58:07Z'
created_by: a.user@example.com
delta_id: df1ad41807b0390a9b0eaf8688e1f5baece9d764
env_id: my-env
from_id: 42d4b302fd3c
id: 67f1619a57d
status: in progress
status_changed_at: '2020-05-22T14:59:01Z'
properties:
comment:
description: An optional comment to help communicate the purpose of the Deployment.
type: string
created_at:
description: The Timestamp of when the Deployment was initiated.
example: '2020-06-22T09:37:23.523Z'
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{3})?Z$
title: Simplified extended ISO format date/time string.
format: date-time
type: string
created_by:
description: The user who initiated the Deployment.
type: string
delta_id:
description: ID of the Deployment Delta describing the changes to the current Environment for this Deployment.
type: string
env_id:
description: The Environment where the Deployment occurred.
type: string
export_file:
type: string
dependency_graph_id:
type: string
description: 'The ID of the Dependency Graph which holds the sorted list of the resources provisioned with this deployment.
The referenced Graph does not include resources of type k8s-cluster and k8s-namespace (and logging in case of deployments executed in Operator mode).'
legacy_mode:
type: boolean
description: Defines if it's a Legacy Mode deployment, nil means either the mode is unknown or the deployment not yet finished.
export_status:
type: string
from_id:
description: The ID of the Deployment that this Deployment was based on.
type: string
id:
description: The ID of the Deployment.
type: string
pipeline:
$ref: '#/components/schemas/DeploymentPipelineReferenceResponse'
description: The Pipeline that created this deployment. This may be blank if no Pipeline is associated.
set_id:
description: ID of the Deployment Set describing the state of the Environment after Deployment.
type: string
status:
description: The current status of the Deployment. Can be `pending`, `in progress`, `succeeded`, or `failed`.
type: string
status_changed_at:
description: The timestamp of the last `status` change. If `status` is `succeeded` or `failed` it it will indicate when the Deployment finished.
example: '2020-06-22T09:37:23.523Z'
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{3})?Z$
title: Simplified extended ISO format date/time string.
format: date-time
type: string
value_set_version_id:
description: ID of the Value Set Version describe the values to be used for this Deployment.
nullable: true
type: string
required:
- set_id
- comment
- id
- env_id
- created_at
- created_by
- status
- status_changed_at
- from_id
- export_status
- export_file
type: object
DeploymentErrorResponse:
description: Error happening during deployment.
example:
code: CLD-001
message: Incorrect cloud provider credentials.
object_id: my-workload
scope: workload
summary: Provider error
properties:
code:
type: string
error_type:
type: string
message:
type: string
object_id:
type: string
scope:
type: string
summary:
type: string
required:
- scope
- object_id
- code
- summary
- message
- error_type
type: object
DeploymentPipelineReferenceRequest:
properties:
id:
description: The ID of the Pipeline
type: string
job_id:
description: The ID of the Pipeline Job within the Run.
type: string
run_id:
description: The ID of the Pipeline Run
type: string
step_index:
description: The index of the step with in the Job.
type: integer
type: object
DeploymentRequest:
description: 'Deployments represent updates to the running state of an Environment.
Deployments are made by applying _Deltas_ to a state defined by an existing Deployment. The Environment’s from_deploy property defines the Deployment. This Deployment is usually but not always in the current Environment. If the Deployment is from another Environment, the state of that Environment will be "cloned" into the current Environment with the option to apply a Delta.'
example:
comment: Updated version of module-one to v0.3.1
created_at: '2020-05-22T14:58:07Z'
created_by: a.user@example.com
delta_id: df1ad41807b0390a9b0eaf8688e1f5baece9d764
env_id: my-env
from_id: 42d4b302fd3c
id: 67f1619a57d
status: in progress
status_changed_at: '2020-05-22T14:59:01Z'
properties:
comment:
description: An optional comment to help communicate the purpose of the Deployment.
type: string
delta_id:
description: ID of the Deployment Delta describing the changes to the current Environment for this Deployment.
type: string
pipeline:
$ref: '#/components/schemas/DeploymentPipelineReferenceRequest'
description: The Pipeline that created this deployment. This may be blank if no Pipeline is associated.
set_id:
description: ID of the Deployment Set describing the state of the Environment after Deployment.
type: string
value_set_version_id:
description: ID of the Value Set Version describe the values to be used for this Deployment.
nullable: true
type: string
type: object
DeploymentPipelineReferenceResponse:
properties:
id:
description: The ID of the Pipeline
type: string
job_id:
description: The ID of the Pipeline Job within the Run.
type: string
run_id:
description: The ID of the Pipeline Run
type: string
step_index:
description: The index of the step with in the Job.
type: integer
required:
- id
- run_id
- job_id
- step_index
type: object
HumanitecErrorResponse:
description: HumanitecError represents a standard Humanitec Error
properties:
details:
additionalProperties: true
type: object
description: (Optional) Additional information is enclosed here.
error:
type: string
example: API-000
description: A short code to help with error identification.
message:
type: string
example: Could not validate token
description: A Human readable message about the error.
required:
- error
- message
type: object
example:
error: API-000
message: Could not validate token.
externalDocs:
description: Find out more about how to use Humanitec in your every-day development work.
url: https://developer.humanitec.com/
x-tagGroups:
- name: Core
tags:
- Agents
- Application
- Artefact
- ArtefactVersion
- AuditLogs
- Logs
- Deployment
- EnvironmentType
- Environment
- Image
- PublicKeys
- Organization
- Registry
- RuntimeInfo
- SecretStore
- Value
- ValueSetVersion
- name: App Configuration
tags:
- Delta
- Set
- WorkloadProfile
- name: Resources
tags:
- ActiveResource
- DriverDefinition
- MatchingCriteria
- ResourceDefinition
- ResourceDefinitionVersion
- ResourceProvision
- AccountType
- ResourceAccount
- ResourceType
- ResourceClass
- name: Automation
tags:
- AutomationRule
- Event
- Pipelines
- PipelineRuns
- PipelineApprovals
- name: Users
tags:
- UserProfile
- UserRole
- Group
- TokenInfo