Humanitec Environment API
Environments are independent spaces where Applications can run. An Application is always deployed into an Environment.
OpenAPI Specification
openapi: 3.0.0
info:
title: Humanitec AccountType Environment 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: Environment
x-displayName: Environments
description: 'Environments are independent spaces where Applications can run. An Application is always deployed into an Environment.
<SchemaDefinition schemaRef="#/components/schemas/EnvironmentResponse" />
'
paths:
/orgs/{orgId}/apps/{appId}/envs:
get:
tags:
- Environment
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:
- Environment
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:
- Environment
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:
- Environment
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:
- Environment
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}/from_deploy_id:
put:
tags:
- Environment
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'
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
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.
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
EnvironmentDefinitionRequest:
properties:
from_deploy_id:
description: Defines the existing Deployment the new Environment will be based on.
type: string
id:
description: The ID the Environment is referenced as.
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
maxLength: 50
type: string
name:
description: The Human-friendly name for the Environment.
type: string
type:
description: The Environment Type. This is used for organizing and managing Environments.
type: string
required:
- id
- name
type: object
EnvironmentResponse:
description: Environments are independent spaces where Applications can run. An Application is always deployed into an Environment.
example:
created_at: '2020-05-22T14:58:07Z'
created_by: a.user@example.com
status: active
status_changed_at: '2020-05-22T14:59:01Z'
from_deploy:
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'
id: feature-test
last_deploy:
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'
name: Feature Test
type: development
properties:
created_at:
description: The timestamp in UTC of when the Environment was created.
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 created the Environment
type: string
from_deploy:
$ref: '#/components/schemas/DeploymentResponse'
description: 'The Deployment which acts as the base for the next Deployment. Typically this will be identical to last_deploy but can differ if an Environment Rebase occurred.
This property is not present before the first Deployment in the first Environment in a new Application.'
id:
description: The ID the Environment is referenced as.
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
type: string
last_deploy:
$ref: '#/components/schemas/DeploymentResponse'
description: The last Deployment to have occured in the environment. This is not present if a deployment is yet to occur in the Environment.
name:
description: The Human-friendly name for the Environment.
type: string
type:
description: The Environment Type. This is used for organizing and managing Environments.
type: string
status:
description: The status of the environment
type: string
enum:
- active
- deleting
status_changed_at:
description: The timestamp in UTC of when the Environment status was last changed.
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
status_message:
description: The message associated with the status of the environment
type: string
required:
- id
- name
- type
- created_at
- created_by
- status
- status_changed_at
type: object
EnvironmentBaseUpdateRequest:
properties:
name:
description: The Human-friendly name for the Environment.
type: string
type: object
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