openapi: 3.0.0
info:
title: Humanitec AccountType Delta 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: Delta
x-displayName: Deployment Deltas
description: "A Deployment Delta (or just \"Delta\") describes the changes that must be applied to one Deployment Set to generate another Deployment Set. Deployment Deltas are the only way to create new Deployment Sets.\n\nDeployment Deltas can be created fully formed or combined together via PATCHing. They can also be generated from the difference between two Deployment Sets.\n\n**Basic Structure**\n\n```\n {\n \"id\": <ID of the Deployment Delta.>,\n \"metadata\": {\n <Properties such as who created the Delta, which Environment it is associated to and a Human-friendly name>\n }\n \"modules\" : {\n \"add\" : {\n <ID of Module to add to the Deployment Set> : {\n <An entire Modules object>\n }\n },\n \"remove\": [\n <An array of Module IDs that should be removed from the Deployment Set>\n ],\n \"update\": {\n <ID of Module already in the Set to be updated> : [\n <An array of JSON Patch (Search Results (RFC 6902) objects scoped to the module>\n ]\n }\n }\n }\n```\n<SchemaDefinition schemaRef=\"#/components/schemas/DeltaRequest\" />\n"
paths:
/orgs/{orgId}/apps/{appId}/deltas:
get:
tags:
- Delta
summary: List Deltas in an Application
operationId: listDeltas
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/appIdPathParam'
- name: archived
in: query
description: 'If true, return archived Deltas.
'
schema:
type: boolean
- name: env
in: query
description: 'Only return Deltas associated with the specified Environment.
'
schema:
type: string
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
responses:
'200':
description: 'A possibly empty list of Deployment Deltas.
'
content:
application/json:
schema:
items:
$ref: '#/components/schemas/DeltaResponse'
type: array
post:
tags:
- Delta
summary: Create a new Delta
operationId: createDelta
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/appIdPathParam'
requestBody:
description: 'A Deployment Delta to create.
The Deployment Delta will be added with the provided content of `modules` and the ''env_id'' and ''name'' properties of the ''metadata'' property.
NOTE: If the `id` property is specified, it will be ignored. A new ID will be generated and returned in the response.'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeltaRequest'
example:
metadata:
env_id: feature-test
name: 'Updates for ticket # 2581'
modules:
updates:
module-one:
- op: add
path: /spec/containers/simple-service/variables/REDIS_URL
value: redis://${modules.redis-cache.service.name}
responses:
'200':
description: 'The requested Deployment Delta.
'
content:
application/json:
schema:
oneOf:
- type: string
- $ref: '#/components/schemas/DeltaResponse'
'400':
description: 'The request was invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/apps/{appId}/deltas/{deltaId}:
get:
tags:
- Delta
summary: Fetch an existing Delta
operationId: getDelta
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/appIdPathParam'
- name: deltaId
in: path
description: 'ID of the Delta to fetch.
'
required: true
schema:
type: string
responses:
'200':
description: The requested Deployment Delta.
content:
application/json:
schema:
$ref: '#/components/schemas/DeltaResponse'
'404':
description: 'No Deployment Delta with ID `deltaId` found in Application.
'
content:
application/json:
schema:
type: string
patch:
tags:
- Delta
summary: Update an existing Delta
operationId: patchDelta
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/appIdPathParam'
- name: deltaId
in: path
description: 'ID of the Delta to update.
'
required: true
schema:
type: string
requestBody:
description: 'An array of Deltas.
The Deltas in the request are combined, meaning the current Delta is updated in turn by each Delta in the request. Once all Deltas have been combined, the resulting Delta is simplified.
* All Modules in the `modules.add` property are replaced with the new Delta''s values. If the value of a Module is `null`, and the ID is in the `modules.remove` list, it is removed from the `modules.remove` list.
* All IDs listed in `modules.remove` are combined. Any ID in `modules.remove` and also in `modules.add` are removed from `modules.add`
* The lists of JSON Patches in `modules.update` are concatenated or created in `modules.updates`.
Simplification involves:
* Applying any entries in `modules.updates` that have matching IDs in `modules.add` to the `modules.add` entry and removing the `modules.update` entry.
* Reducing the number of JSON Patches in each `modules.update` entry to the smallest set that has the same effect.
**Extension to JSON Patch**
If a JSON Patch entry needs to be removed, without side effects, the `value` of the `remove` action can be set to `{"scope": "delta"}. This will result in the remove action being used during simplification but be discarded before the Delta is finalized.
If the user making the request is not the user who created the Delta and they are not already on the contributors list, they will be added to the contributors list.
_NOTE: If the `id` or `metadata` properties are specified, they will be ignored._'
required: true
content:
application/json:
schema:
items:
$ref: '#/components/schemas/DeltaRequest'
type: array
example:
- modules:
updates:
module-one:
- op: add
path: /spec/containers/simple-service/variables/REDIS_URL
value: redis://${modules.redis-cache.service.name}
responses:
'200':
description: 'The requested Deployment Delta.
'
content:
application/json:
schema:
$ref: '#/components/schemas/DeltaResponse'
'400':
description: 'The request was invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'No Deployment Delta with ID `deltaId` found in Application.
'
content:
application/json:
schema:
type: string
put:
tags:
- Delta
summary: Update an existing Delta
operationId: putDelta
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/appIdPathParam'
- name: deltaId
in: path
description: 'ID of the Delta to update.
'
required: true
schema:
type: string
requestBody:
description: 'An array of Deltas.
The Deltas in the request are combined, meaning the current Delta is updated in turn by each Delta in the request. Once all Deltas have been combined, the resulting Delta is simplified.
* All Modules in the `modules.add` property are replaced with the new Delta''s values. If the value of a Module is `null`, and the ID is in the `modules.remove` list, it is removed from the `modules.remove` list.
* All IDs listed in `modules.remove` are combined. Any ID in `modules.remove` and also in `modules.add` are removed from `modules.add`
* The lists of JSON Patches in `modules.update` are concatenated or created in `modules.updates`.
Simplification involves:
* Applying any entries in `modules.updates` that have matching IDs in `modules.add` to the `modules.add` entry and removing the `modules.update` entry.
* Reducing the number of JSON Patches in each `modules.update` entry to the smallest set that has the same effect.
**Extension to JSON Patch**
If a JSON Patch entry needs to be removed, without side effects, the `value` of the `remove` action can be set to `{"scope": "delta"}. This will result in the remove action being used during simplification but be discarded before the Delta is finalized.
If the user making the request is not the user who created the Delta and they are not already on the contributors list, they will be added to the contributors list.
_NOTE: If the `id` or `metadata` properties are specified, they will be ignored._'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeltaRequest'
responses:
'204':
description: 'The requested Deployment Delta.
'
'400':
description: 'The request was invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'No Deployment Delta with ID `deltaId` found in Application.
'
content:
application/json:
schema:
type: string
/orgs/{orgId}/apps/{appId}/deltas/{deltaId}/metadata/archived:
put:
tags:
- Delta
summary: Mark a Delta as "archived"
operationId: archiveDelta
description: Archived Deltas are still accessible but can no longer be updated.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/appIdPathParam'
- name: deltaId
in: path
description: 'ID of the Deployment Delta.
'
required: true
schema:
type: string
requestBody:
description: 'Either `true` or `false`.
'
required: true
content:
application/json:
schema:
type: boolean
example: true
responses:
'204':
description: 'Archived state successfully updated.
'
'400':
description: 'The request was invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'No Deployment Delta with ID `deltaId` found in Application.
'
content:
application/json:
schema:
type: string
/orgs/{orgId}/apps/{appId}/deltas/{deltaId}/metadata/env_id:
put:
tags:
- Delta
summary: Change the Environment of a Delta
operationId: changeEnvOfDelta
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/appIdPathParam'
- name: deltaId
in: path
description: 'ID of the Deployment Delta.
'
required: true
schema:
type: string
requestBody:
description: 'The new Environment ID. (NOTE: The string must still be JSON encoded.)
'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentID'
example: new-env
responses:
'204':
description: 'Environment ID successfully updated.
'
'400':
description: 'The request was invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'No Deployment Delta with ID `deltaId` found in Application.
'
content:
application/json:
schema:
type: string
/orgs/{orgId}/apps/{appId}/deltas/{deltaId}/metadata/name:
put:
tags:
- Delta
summary: Change the name of a Delta
operationId: changeNameOfDelta
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/appIdPathParam'
- name: deltaId
in: path
description: 'ID of the Deployment Delta.
'
required: true
schema:
type: string
requestBody:
description: 'The new name.(NOTE: The string must still be JSON encoded.)
'
required: true
content:
application/json:
schema:
type: string
example: 'Update for ticket #s 2568 & 2572'
responses:
'204':
description: 'Name successfully updated.
'
'400':
description: 'The request was invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'No Deployment Delta with ID `deltaId` found in Application.
'
content:
application/json:
schema:
type: string
components:
schemas:
DeployConditionResponse:
description: 'A deploy condition for the workload
Possible values for "when" are: - "before", deployed before other workloads - "deploy", deployed in-parallel with other workloads (default) - "after", deployed after other workloads
Possible values for "success" are: - "deploy", workload deployed - "available", workload available - "complete", workload complete (often used with jobs)'
example:
success: complete
when: before
properties:
success:
type: string
timeout:
type: integer
when:
type: string
required:
- when
- success
- timeout
type: object
DeployConditionRequest:
description: 'A deploy condition for the workload
Possible values for "when" are: - "before", deployed before other workloads - "deploy", deployed in-parallel with other workloads (default) - "after", deployed after other workloads
Possible values for "success" are: - "deploy", workload deployed - "available", workload available - "complete", workload complete (often used with jobs)'
example:
success: complete
when: before
properties:
success:
type: string
timeout:
type: integer
when:
type: string
type: object
ModuleRequest:
description: Module single workload data
properties:
deploy:
$ref: '#/components/schemas/DeployConditionRequest'
externals:
additionalProperties: true
type: object
nullable: true
profile:
type: string
spec:
additionalProperties: true
type: object
nullable: true
type: object
nullable: true
DeltaMetadataRequest:
properties:
archived:
type: boolean
contributers:
items:
type: string
type: array
nullable: true
created_at:
example: '2020-06-22T09:37:23.523Z'
format: date-time
title: Simplified extended ISO format date/time string.
type: string
created_by:
type: string
env_id:
$ref: '#/components/schemas/EnvironmentID'
last_modified_at:
example: '2020-06-22T09:37:23.523Z'
format: date-time
title: Simplified extended ISO format date/time string.
type: string
name:
type: string
shared:
type: boolean
type: object
EnvironmentID:
type: string
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
example: my-env
ModuleDeltasRequest:
description: ModuleDeltas groups the different operations together.
properties:
add:
additionalProperties:
$ref: '#/components/schemas/ModuleRequest'
type: object
nullable: true
remove:
items:
type: string
type: array
nullable: true
update:
additionalProperties:
items:
$ref: '#/components/schemas/UpdateActionRequest'
type: array
type: object
nullable: true
type: object
DeltaMetadataResponse:
properties:
archived:
type: boolean
contributers:
items:
type: string
type: array
created_at:
example: '2020-06-22T09:37:23.523Z'
format: date-time
title: Simplified extended ISO format date/time string.
type: string
created_by:
type: string
env_id:
$ref: '#/components/schemas/EnvironmentID'
last_modified_at:
example: '2020-06-22T09:37:23.523Z'
format: date-time
title: Simplified extended ISO format date/time string.
type: string
name:
type: string
shared:
type: boolean
required:
- created_by
- created_at
- last_modified_at
- archived
type: object
PodStateResponse:
description: PodState represents single pod status
properties:
containerStatuses:
items:
additionalProperties: true
type: object
type: array
phase:
type: string
podName:
type: string
revision:
type: integer
status:
type: string
required:
- podName
- revision
- phase
- status
- containerStatuses
type: object
UpdateActionResponse:
description: 'A representation of the main object defined in JSON Patch specified in RFC 6902 from the IETF. The main differences are:
* Only `add`, `remove` and `replace` are supported
* `remove` can have have its scope of application applied in its `value`. e.g. `{"scope":"delta"}'
properties:
from:
type: string
op:
type: string
path:
type: string
value: {}
required:
- op
- path
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.
DeltaResponse:
description: "A Deployment Delta (or just \"Delta\") describes the changes that must be applied to one Deployment Set to generate another Deployment Set. Deployment Deltas are the only way to create new Deployment Sets.\n\nDeployment Deltas can be created fully formed or combined together via PATCHing. They can also be generated from the difference between two Deployment Sets.\n\n**Basic Structure**\n\n```\n {\n \"id\": <ID of the Deployment Delta.>,\n \"metadata\": {\n <Properties such as who created the Delta, which Environment it is associated to and a Human-friendly name>\n }\n \"modules\" : {\n \"add\" : {\n <ID of Module to add to the Deployment Set> : {\n <An entire Modules object>\n }\n },\n \"remove\": [\n <An array of Module IDs that should be removed from the Deployment Set>\n ],\n \"update\": {\n <ID of Module already in the Set to be updated> : [\n <An array of JSON Patch (Search Results (RFC 6902) objects scoped to the module>\n ]\n }\n }\n }\n```"
example:
id: 49393b5004d072000b8abfd910c61685eb9235f5
metadata: {}
modules:
add:
redis-cache:
profile: humanitec/redis
remove:
- simple-service
update:
module-one:
- op: replace
path: /spec/containers/core-service/variables/EXAMPLE
value: New Value
properties:
id:
description: A unique ID for the Delta
type: string
metadata:
$ref: '#/components/schemas/DeltaMetadataResponse'
description: Holds various metadata such as a Human-friendly name, collaborators, and Environment it is associated with.
modules:
$ref: '#/components/schemas/ModuleDeltasResponse'
description: A dictionary of the Modules this Delta has operations for.
shared:
items:
$ref: '#/components/schemas/UpdateActionResponse'
type: array
required:
- id
- metadata
- modules
- shared
type: object
ModuleDeltasResponse:
description: ModuleDeltas groups the different operations together.
properties:
add:
additionalProperties:
$ref: '#/components/schemas/ModuleResponse'
type: object
remove:
items:
type: string
type: array
update:
additionalProperties:
items:
$ref: '#/components/schemas/UpdateActionResponse'
type: array
type: object
required:
- add
- remove
- update
type: object
UpdateActionRequest:
description: 'A representation of the main object defined in JSON Patch specified in RFC 6902 from the IETF. The main differences are:
* Only `add`, `remove` and `replace` are supported
* `remove` can have have its scope of application applied in its `value`. e.g. `{"scope":"delta"}'
properties:
from:
type: string
op:
type: string
path:
type: string
value:
nullable: true
type: object
ModuleResponse:
description: Module represents a collection of workload controllers (deployments/statefulsets/etc) for the module
properties:
deploy:
$ref: '#/components/schemas/DeployConditionResponse'
externals:
additionalProperties: true
type: object
profile:
type: string
spec:
additionalProperties: true
type: object
required:
- profile
- spec
- externals
type: object
additionalProperties:
$ref: '#/components/schemas/ControllerResponse'
DeltaRequest:
description: "A Deployment Delta (or just \"Delta\") describes the changes that must be applied to one Deployment Set to generate another Deployment Set. Deployment Deltas are the only way to create new Deployment Sets.\n\nDeployment Deltas can be created fully formed or combined together via PATCHing. They can also be generated from the difference between two Deployment Sets.\n\n**Basic Structure**\n\n```\n {\n \"id\": <ID of the Deployment Delta.>,\n \"metadata\": {\n <Properties such as who created the Delta, which Environment it is associated to and a Human-friendly name>\n }\n \"modules\" : {\n \"add\" : {\n <ID of Module to add to the Deployment Set> : {\n <An entire Modules object>\n }\n },\n \"remove\": [\n <An array of Module IDs that should be removed from the Deployment Set>\n ],\n \"update\": {\n <ID of Module already in the Set to be updated> : [\n <An array of JSON Patch (Search Results (RFC 6902) objects scoped to the module>\n ]\n }\n }\n }\n```"
example:
id: 49393b5004d072000b8abfd910c61685eb9235f5
metadata: {}
modules:
add:
redis-cache:
profile: humanitec/redis
remove:
- simple-service
update:
module-one:
- op: replace
path: /spec/containers/core-service/variables/EXAMPLE
value: New Value
properties:
id:
description: Ignored, but can be provided.
type: string
metadata:
$ref: '#/components/schemas/DeltaMetadataRequest'
description: Holds various metadata such as a Human-friendly name, collaborators, and Environment it is associated with.
modules:
$ref: '#/components/schemas/ModuleDeltasRequest'
description: A dictionary of the Modules this Delta has operations for.
shared:
items:
$ref: '#/components/schemas/UpdateActionRequest'
type: array
nullable: true
type: object
ControllerResponse:
description: Controller represents deployment, stateful set etc
properties:
kind:
type: string
message:
type: string
pods:
items:
$ref: '#/components/schemas/PodStateResponse'
type: array
replicas:
type: integer
revision:
type: integer
status:
type: string
required:
- kind
- replicas
- status
- message
- pods
- revision
type: object
parameters:
orgIdPathParam:
name: orgId
in: path
description: The Organization ID
example: sample-org
required: true
schema:
type: string
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
maxLength: 50
appIdPathParam:
name: appId
in: path
description: The Application ID
required: true
example: sample-app
schema:
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
type: string
maxLength: 50
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