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
Almost all requests made to the Humanitec API require Authentication. See our Developer Docs on API Authentication for instructions.
The Humanitec API, unless explicitly specified, only accepts content types of application/json and will always return valid application/json or an empty response.
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. |
An object containing the details of an Agent.
| id required | string The Agent id. |
| description | string A description to show future users. It can be empty. |
| created_at required | string <date-time> Time of the Agent being registered. |
| created_by required | string User ID of user that added the Agent. |
{- "id": "agent-id",
- "description": "One of my agents.",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "00000000-0000-0000-0000-000000000000"
}Register a new Agent under an Organization.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
Request Body schema: application/json
| id required | string^[a-z0-9](?:-?[a-z0-9]+)+$ The Agent id. It can't be empty and should contain only url safe characters. |
| public_key required | string A pcks8 RSA public key PEM encoded (as the ones produced by openssl), whose module length is greater or equal than 4096 bits. |
| description | string An optional description to show future users. |
Responses
Request samples
- Payload
{- "id": "agent-id",
- "public_key": "-----BEGIN PUBLIC KEY-----\n...-----END PUBLIC KEY-----",
- "description": "One of my agents."
}Response samples
- 200
- 400
- 409
{- "id": "agent-id",
- "description": "One of my agents.",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "00000000-0000-0000-0000-000000000000"
}List all the agents in an Organization.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
query Parameters
| fingerprint | string Example: fingerprint=9be36d7e31323a00e88facdd50843accd95ddbcffaefea28e49c28c08399417d The Key fingerprint (hexadecimal representation of sha256 hash of the DER representation of the key). |
Responses
Response samples
- 200
[- {
- "id": "agent-id",
- "description": "One of my agents.",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "00000000-0000-0000-0000-000000000000"
}
]Delete an Agent (and its keys) stored under an Organization.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| agentId required | string Example: my-agent The Agent id. |
Responses
Response samples
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}Update the description of an Agent.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| agentId required | string Example: my-agent The Agent id. |
Request Body schema: application/json
| description required | string A description to show future users. It can be empty. |
Responses
Request samples
- Payload
{- "description": "One of my agents."
}Response samples
- 200
- 400
- 404
{- "id": "agent-id",
- "description": "One of my agents.",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "00000000-0000-0000-0000-000000000000"
}List all the keys registered under an Agent in an Organization.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| agentId required | string Example: my-agent The Agent id. |
Responses
Response samples
- 200
- 404
[- {
- "fingerprint": "9be36d7e31323a00e88facdd50843accd95ddbcffaefea28e49c28c08399417d",
- "public_key": "-----BEGIN PUBLIC KEY-----\n...-----END PUBLIC KEY-----",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "00000000-0000-0000-0000-000000000000",
- "expired_at": "2022-06-22T09:37:23.523Z",
- "is_authorized": true
}
]Register a new Key under an Agent in an Organization.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| agentId required | string Example: my-agent The Agent id. |
Request Body schema: application/json
| public_key required | string A pcks8 RSA public key PEM encoded (as the ones produced by openssl), whose module length is greater or equal than 4096 bits. |
Responses
Request samples
- Payload
{- "public_key": "-----BEGIN PUBLIC KEY-----\n...-----END PUBLIC KEY-----"
}Response samples
- 200
- 400
- 404
- 409
{- "fingerprint": "9be36d7e31323a00e88facdd50843accd95ddbcffaefea28e49c28c08399417d",
- "public_key": "-----BEGIN PUBLIC KEY-----\n...-----END PUBLIC KEY-----",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "00000000-0000-0000-0000-000000000000",
- "expired_at": "2022-06-22T09:37:23.523Z",
- "is_authorized": true
}Delete a key registered under a Agent.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| agentId required | string Example: my-agent The Agent id. |
| fingerprint required | string Example: 9be36d7e31323a00e88facdd50843accd95ddbcffaefea28e49c28c08399417d The Key fingerprint (hexadecimal representation of sha256 hash of the DER representation of the key). |
Responses
Response samples
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}An Application is a collection of Workloads that work together. When deployed, all Workloads in an Application are deployed to the same namespace.
Apps are the root of the configuration tree holding Environments, Deployments, Shared Values, and Secrets.
| id required | string^[a-z0-9](?:-?[a-z0-9]+)+$ The ID which refers to a specific application. |
| name required | string The Human-friendly name for the Application. |
{- "created_at": "2020-05-22T14:53:27Z",
- "envs": [
- {
- "id": "my-env",
- "name": "My Environment"
}
], - "id": "my-app",
- "name": "My Application"
}List all Applications in an Organization.
Listing or lists of all Applications that exist within a specific Organization.
path Parameters
| orgId required | string The Organization ID. |
Responses
Response samples
- 200
[- {
- "created_at": "2020-06-15T09:32:03Z",
- "envs": {
- "id": "development",
- "name": "Development",
- "type": "development"
}, - "id": "my-app",
- "name": "My Awesome App"
}
]Add a new Application to an Organization
Creates a new Application, then adds it to the specified Organization.
path Parameters
| orgId required | string The Organization ID. |
Request Body schema: application/json
The request ID, Human-friendly name and environment of the Application.
object (EnvironmentBaseRequest) | |
| id required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ The ID which refers to a specific application. |
| name required | string The Human-friendly name for the Application. |
Responses
Request samples
- Payload
{- "env": {
- "id": "string",
- "name": "string",
- "type": "string"
}, - "id": "string",
- "name": "string"
}Response samples
- 201
- 400
- 401
- 409
{- "created_at": "2020-06-15T09:32:03Z",
- "envs": {
- "id": "development",
- "name": "Development",
- "type": "development"
}, - "id": "my-app",
- "name": "My Awesome App"
}Get an existing Application
Gets a specific Application in the specified Organization by ID.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
Responses
Response samples
- 200
- 404
{- "created_at": "2020-06-15T09:32:03Z",
- "envs": {
- "id": "development",
- "name": "Development",
- "type": "development"
}, - "id": "my-app",
- "name": "My Awesome App"
}Delete an Application
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.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
Responses
Response samples
- 401
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}Artefacts can be registered with Humanitec. Continuous Integration (CI) pipelines notify Humanitec when a new version of an Artefact becomes available. Humanitec tracks the Artefact along with metadata about how it was built.
| created_at | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... The time when the Artefact was added to Humanitec. |
| created_by | string The user ID of the user who added the Artefact to Humanitec. |
| id required | string The UUID of the Artefact. |
| name required | string The name of the Artefact. |
| type required | string The type of the Artefact. |
| updated_at | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... The time when the Artefact was updated for the last time. |
| updated_by | string The user ID of the user who updated the Artefact for the last time. |
{- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "name": "registry.humanitec.io/my-org/my-service",
- "type": "container",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "updated_by": "01234567-89ab-cdef-0123-456789abcdef"
}Get the spec of this Workload Artefact Version
Returns the spec of this Artefact Version if it is of type workload. An error will be returned if it is not.
path Parameters
| orgId required | string Example: sample-org The organization ID. |
| artefactVersionId required | string Example: 662b80db-cc71-40cf-b601-08d57983f6e4 The Artefact Version ID. |
header Parameters
| Accept | string Example: application/json The accepted content type. |
Responses
Response samples
- 200
- 400
- 404
{ }Get the Humanitec module definition of this Workload Artefact Version as a deployment set
Returns the Humanitec workload module of this Artefact Version if it is of type workload. An error will be returned if it is not.
path Parameters
| orgId required | string Example: sample-org The organization ID. |
| artefactVersionId required | string Example: 662b80db-cc71-40cf-b601-08d57983f6e4 The Artefact Version ID. |
header Parameters
| Accept | string Example: application/json The accepted content type. |
Responses
Response samples
- 200
- 400
- 404
{- "modules": {
- "property1": { },
- "property2": { }
}, - "shared": {
- "property1": { },
- "property2": { }
}
}List all Artefacts.
Returns the Artefacts registered with your organization. If no elements are found, an empty list is returned.
path Parameters
| orgId required | string Example: sample-org The organization ID. |
query Parameters
| type | string Example: type=container (Optional) Filter Artefacts by type. |
| name | string Example: name=registry.humanitec.io/public/sample-app (Optional) Filter Artefacts by name. |
Responses
Response samples
- 200
[- {
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "name": "registry.humanitec.io/my-org/my-service",
- "type": "container",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "updated_by": "01234567-89ab-cdef-0123-456789abcdef"
}
]Delete Artefact and all related Artefact Versions
The specified Artefact and its Artefact Versions will be permanently deleted. Only Administrators can delete an Artefact.
path Parameters
| orgId required | string Example: sample-org The organization ID. |
| artefactId required | string Example: da97af75-2e7c-4ef3-bec0-755ce1e8dd29 The Artefact ID. |
Responses
Response samples
- 403
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}Details of a Container Artefact Version
| archived required | boolean If the Artefact Version is archived. |
| artefact_id required | string The UUID of the Artefact. |
| commit required | string (Optional) The commit ID the Artefact Version was built on. |
| created_at | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... The time when the Artefact Version was added to Humanitec. |
| created_by | string The user ID of the user who added the Artefact Version to Humanitec. |
| id required | string The UUID of the Artefact Version. |
| name required | string The name of the Artefact. |
| ref required | string (Optional) The ref the Artefact Version was built from. |
| updated_at | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... The time when the Artefact Version was updated for the last time. |
| updated_by | string The user ID of the user who performed the last updated on the Artefact Version. |
| version | string (Optional) The version of the Artefact Version. |
| digest required | string (Optional) The Artefact Version digest. |
{- "archived": false,
- "artefact_id": "01234567-89ab-cdef-0123-456789abcdef",
- "commit": "060c3d6530a881afb808f105f36af25e1ad1b2f3",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "name": "registry.humanitec.io/my-org/my-service",
- "ref": "refs/heads/main",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "updated_by": "01234567-89ab-cdef-0123-456789abcdef",
- "version": "1.2.7",
- "digest": "sha256:8414aa82208bc4c2761dc149df67e25c6b8a9380e5d8c4e7b5c84ca2d04bb244"
}List all Artefacts Versions in the org.
Returns the Artefact Versions registered with your organization. If no elements are found, an empty list is returned.
path Parameters
| orgId required | string Example: sample-org The organization ID. |
query Parameters
| name | string Example: name=registry.humanitec.io/public/sample-app (Optional) Filter Artefact Versions by name. |
| reference | string Example: reference=registry.humanitec.io/public/sample-app:v1@sha256:8414aa82208bc4c2761dc149df67e25c6b8a9380e5d8c4e7b5c84ca2d04bb244 (Optional) Filter Artefact Versions by the reference to a Version of the same Artefact. This cannot be used together with |
| archived | boolean (Optional) Filter for non-archived Artefact Versions. If no filter is defined only non-archived Artefact Versions are returned, if the filter is true both archived and non-archived Versions are returned. |
| type | string Example: type=containers (Optional) Filter by artefact type. |
Responses
Response samples
- 200
- 400
[- {
- "type": "container",
- "archived": false,
- "artefact_id": "01234567-89ab-cdef-0123-456789abcdef",
- "commit": "060c3d6530a881afb808f105f36af25e1ad1b2f3",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "name": "registry.humanitec.io/my-org/my-service",
- "ref": "refs/heads/main",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "updated_by": "01234567-89ab-cdef-0123-456789abcdef",
- "version": "1.2.7",
- "digest": "sha256:8414aa82208bc4c2761dc149df67e25c6b8a9380e5d8c4e7b5c84ca2d04bb244"
}
]Register a new Artefact Version with your organization.
path Parameters
| orgId required | string Example: sample-org The organization ID. |
query Parameters
| vcs | string Example: vcs=git (Optional) Which version control system the version comes from. Default value is "git". If this parameter is not supplied or its value is "git", the provided ref, if not empty, is checked to ensure that it has the prefix "refs/". |
| dry_run | boolean Optionally validate the request but do not persist the actual artefact. If the Accept type is set to "application/x.workload-deployment-set+json" or "application/x.workload-deployment-set+x-yaml", the generated deployment set will be returned. |
header Parameters
| Accept | string Indicates which content types the client is able to understand. |
Request Body schema:
The data needed to register a new Artefact Version within the organization.
| type required | string The Artefact Version type. |
| name required | string The Artefact name. |
| version | string (Optional) The Artefact Version. |
| ref | string (Optional) The ref the Artefact Version was built from. |
| commit | string^[0-9a-f]{5,40}$ (Optional) The commit ID the Artefact Version was built on. |
| digest | string (Optional) The Artefact Version digest. |
Responses
Request samples
- Payload
{- "type": "container",
- "name": "registry.humanitec.io/my-org/my-service",
- "version": "1.2.7",
- "ref": "refs/heads/main",
- "commit": "884bccaa807ea27cc1997a7492a3b6279fd7bd55",
- "digest": "sha256:8414aa82208bc4c2761dc149df67e25c6b8a9380e5d8c4e7b5c84ca2d04bb244"
}Response samples
- 200
- 400
- 401
{- "archived": false,
- "artefact_id": "01234567-89ab-cdef-0123-456789abcdef",
- "commit": "060c3d6530a881afb808f105f36af25e1ad1b2f3",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "name": "registry.humanitec.io/my-org/my-service",
- "ref": "refs/heads/main",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "updated_by": "01234567-89ab-cdef-0123-456789abcdef",
- "version": "1.2.7",
- "digest": "sha256:8414aa82208bc4c2761dc149df67e25c6b8a9380e5d8c4e7b5c84ca2d04bb244",
- "type": "container"
}Get an Artefacts Versions.
Returns a specific Artefact Version.
path Parameters
| orgId required | string Example: sample-org The organization ID. |
| artefactVersionId required | string Example: 662b80db-cc71-40cf-b601-08d57983f6e4 The Artefact Version ID. |
Responses
Response samples
- 200
- 400
- 404
{- "archived": false,
- "artefact_id": "01234567-89ab-cdef-0123-456789abcdef",
- "commit": "060c3d6530a881afb808f105f36af25e1ad1b2f3",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "name": "registry.humanitec.io/my-org/my-service",
- "ref": "refs/heads/main",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "updated_by": "01234567-89ab-cdef-0123-456789abcdef",
- "version": "1.2.7",
- "digest": "sha256:8414aa82208bc4c2761dc149df67e25c6b8a9380e5d8c4e7b5c84ca2d04bb244",
- "type": "container"
}List all Artefact Versions of an Artefact.
Returns the Artefact Versions of a specified Artefact registered with your organization. If no elements are found, an empty list is returned.
path Parameters
| orgId required | string Example: sample-org The organization ID. |
| artefactId required | string Example: da97af75-2e7c-4ef3-bec0-755ce1e8dd29 The Artefact ID. |
query Parameters
| archived | boolean (Optional) Filter for non-archived Artefact Versions. If no filter is defined only non-archived Artefact Versions are returned, if the filter is true both archived and non-archived Versions are returned. |
| reference | string Example: reference=registry.humanitec.io/public/sample-app:v1@sha256:8414aa82208bc4c2761dc149df67e25c6b8a9380e5d8c4e7b5c84ca2d04bb244 (Optional) Filter Artefact Versions by by name including a version or digest. |
| limit | integer Example: limit=20 (Optional) Limit the number of versions returned by the endpoint. |
Responses
Response samples
- 200
- 400
- 404
[- {
- "type": "container",
- "archived": false,
- "artefact_id": "01234567-89ab-cdef-0123-456789abcdef",
- "commit": "060c3d6530a881afb808f105f36af25e1ad1b2f3",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "name": "registry.humanitec.io/my-org/my-service",
- "ref": "refs/heads/main",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "updated_by": "01234567-89ab-cdef-0123-456789abcdef",
- "version": "1.2.7",
- "digest": "sha256:8414aa82208bc4c2761dc149df67e25c6b8a9380e5d8c4e7b5c84ca2d04bb244"
}
]Update Version of an Artefact.
Update the version of a specified Artefact registered with your organization".
path Parameters
| orgId required | string Example: sample-org The organization ID. |
| artefactId required | string Example: da97af75-2e7c-4ef3-bec0-755ce1e8dd29 The Artefact ID. |
| versionId required | string Example: da97af75-2e7c-4ef3-bec0-755ce1e8dd29 The Version ID. |
Request Body schema: application/json
The Artefact Version Update Request. Only the field archive can be updated.
| archived required | boolean or null The Value of the archived value. |
Responses
Request samples
- Payload
{- "archived": true
}Response samples
- 200
- 400
- 401
- 403
- 404
{- "archived": false,
- "artefact_id": "01234567-89ab-cdef-0123-456789abcdef",
- "commit": "060c3d6530a881afb808f105f36af25e1ad1b2f3",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "name": "registry.humanitec.io/my-org/my-service",
- "ref": "refs/heads/main",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "updated_by": "01234567-89ab-cdef-0123-456789abcdef",
- "version": "1.2.7",
- "digest": "sha256:8414aa82208bc4c2761dc149df67e25c6b8a9380e5d8c4e7b5c84ca2d04bb244",
- "type": "container"
}Convert a Score specification, optional overrides, and extensions into the contents for a deployment set.
path Parameters
| orgId required | string Example: sample-org The organization ID. |
Request Body schema: application/json
The Score specification, optional overrides, and extensions.
required | object A Json object containing the workload specification. Score v1b1 is expected. |
| image | string An optional default image to assign to any containers in the workload that do not have an image set or whose image is '.' |
object An optional Json object containing the workload overrides. Score v1b1 is expected. | |
object An optional set of path overrides that will be applied to the workload. | |
object (ScoreHumanitecExtensions) Humanitec workload extensions for the Workload Artefact Version. These can be used to override the profile, or workload module spec and resource attributes. |
Responses
Request samples
- Payload
{- "spec": {
- "apiVersion": "score.dev/v1b1",
- "metadata": {
- "name": "hello-world"
}
}, - "image": "busybox:latest",
- "overrides": {
- "apiVersion": "score.dev/v1b1",
- "profile": "humanitec/default-module"
}, - "property_overrides": {
- "containers.my-container.image": "busybox:latest",
- "containers.my-container.variables.DEBUG": null
}, - "extensions": {
- "apiVersion": "humanitec.org/v1b1",
- "profile": "humanitec/default-module",
- "spec": {
- "labels": {
- "my-label": "my-value"
}
}
}
}Response samples
- 200
- 400
{- "modules": {
- "property1": { },
- "property2": { }
}, - "shared": {
- "property1": { },
- "property2": { }
}
}An entry in the audit log
| at required | string <date-time> The date and time when the event was recorded. |
| org_id | string The id of the Organization this event occurred in. |
| user_id required | string The id of the User who triggered the event. |
| request_method required | string The HTTP method that was requested. Only POST, PATCH, PUT, and DELETE are audited. |
| request_path required | string The URL path that was called. |
| response_status required | integer The status code of the response. Only successful responses are audited. |
{- "at": "2023-01-01T00:00:00Z",
- "org_id": "my-organization",
- "user_id": "01234567-89ab-cdef-0123-456789abcdef",
- "request_method": "POST",
- "request_path": "/orgs/some-org/apps",
- "response_status": 201
}List audit log entries by Organization
List all available audit log entries in the Organization that match the specified filters. This API returns entries from newest to oldest and is paginated. Only successful create, modify, or delete requests are stored in the audit log. This API may return a lot of data, depending on the size of the Organization, so it is recommended to use the "to" and "from" query parameters to limit the returned data to the time window of interest. Each response contains at most 32 days worth of data for performance reasons and may be empty if no records exist within that time range. Pagination links in the 'Link' header should always be followed when present. This API requires administrator permissions in the Organization.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
query Parameters
| per_page | integer [ 1 .. 100 ] Default: 50 Example: per_page=50 The maximum number of items to return in a page of results |
| page | string Example: page=AAAAAAAAAA== The page token to request from |
| from | string <date-time> Example: from=2023-01-01T00:00:00Z Optional filter for entries created after the given time. |
| to | string <date-time> Example: to=2023-01-01T00:00:00Z Optional filter for entries created before the given time. |
Responses
Response samples
- 200
- 400
- 403
- 404
[- {
- "at": "2023-01-01T00:00:00Z",
- "org_id": "my-organization",
- "user_id": "01234567-89ab-cdef-0123-456789abcdef",
- "request_method": "POST",
- "request_path": "/orgs/some-org/apps",
- "response_status": 201
}
]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.
| comment | string An optional comment to help communicate the purpose of the Deployment. |
| delta_id | string ID of the Deployment Delta describing the changes to the current Environment for this Deployment. |
object (DeploymentPipelineReferenceRequest) | |
| set_id | string ID of the Deployment Set describing the state of the Environment after Deployment. |
| value_set_version_id | string or null ID of the Value Set Version describe the values to be used for this Deployment. |
{- "comment": "Updated version of module-one to v0.3.1",
- "created_at": "2020-05-22T14:58:07Z",
- "delta_id": "df1ad41807b0390a9b0eaf8688e1f5baece9d764",
- "env_id": "my-env",
- "from_id": "42d4b302fd3c",
- "id": "67f1619a57d",
- "status": "in progress",
- "status_changed_at": "2020-05-22T14:59:01Z"
}List Deployments in an Environment.
List all of the Deployments that have been carried out in the current Environment. Deployments are returned with the newest first.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
query Parameters
| pipelineRunId | string Example: pipelineRunId=default,01234567-89ab-cdef-0123-456789abcdef An optional filter by the Pipeline and Pipeline Run ID separated by a comma. |
Responses
Response samples
- 200
- 404
[- { }
]Start a new Deployment.
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.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
Request Body schema: application/json
The Delta describing the change to the Environment and a comment.
| comment | string An optional comment to help communicate the purpose of the Deployment. |
| delta_id | string ID of the Deployment Delta describing the changes to the current Environment for this Deployment. |
object (DeploymentPipelineReferenceRequest) | |
| set_id | string ID of the Deployment Set describing the state of the Environment after Deployment. |
| value_set_version_id | string or null ID of the Value Set Version describe the values to be used for this Deployment. |
Responses
Request samples
- Payload
{- "comment": "Updated version of module-one to v0.3.1",
- "delta_id": "df1ad41807b0390a9b0eaf8688e1f5baece9d764"
}Response samples
- 201
- 400
- 404
- 409
{- "comment": "Updated version of module-one to v0.3.1",
- "created_at": "2020-05-22T14:58:07Z",
- "delta_id": "df1ad41807b0390a9b0eaf8688e1f5baece9d764",
- "env_id": "my-env",
- "from_id": "42d4b302fd3c",
- "id": "67f1619a57d",
- "status": "in progress",
- "status_changed_at": "2020-05-22T14:59:01Z"
}Get a specific Deployment.
Gets a specific Deployment in an Application and an Environment.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
| deployId required | string The Deployment ID. |
Responses
Response samples
- 200
- 404
{ }List errors that occurred in a Deployment.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
| deployId required | string The Deployment ID. |
Responses
Response samples
- 200
[- {
- "code": "CLD-001",
- "message": "Incorrect credentials",
- "object_id": "my-service",
- "scope": "workload"
}
]Environment Types are a way of grouping and managing Environments. Every Environment has exactly 1 Environment Type.
Environment Types can be used with External Resources to manage where resources such as databases are provisioned or even which cluster to deploy to.
| description | string A Human-readable description of the Environment Type |
| id required | string^[a-z0-9](?:-?[a-z0-9]+)+$ The ID of the Environment Type. (Must be unique within an Organization.) |
{- "description": "Environments used for automated QA.",
- "id": "qa-automation"
}Add a new Environment Type
Adds a new Environment Type to an Organization.
path Parameters
| orgId required | string The Organization ID. |
Request Body schema: application/json
New Environment Type.
| description | string A Human-readable description of the Environment Type |
| id required | string^[a-z0-9](?:-?[a-z0-9]+)+$ The ID of the Environment Type. (Must be unique within an Organization.) |
Responses
Request samples
- Payload
{- "description": "Environments used for automated QA.",
- "id": "qa-automation"
}Response samples
- 201
- 400
- 401
- 409
{- "description": "Environments used for automated QA.",
- "id": "qa-automation"
}Get an Environment Type
Gets a specific Environment Type within an Organization.
path Parameters
| orgId required | string The Organization ID. |
| envTypeId required | string ID of the Environment Type. |
Responses
Response samples
- 200
- 404
{- "description": "Environments used for automated QA.",
- "id": "qa-automation"
}Deletes an Environment Type
Deletes a specific Environment Type from an Organization. If there are Environments with this Type in the Organization, the operation will fail.
path Parameters
| orgId required | string The Organization ID. |
| envTypeId required | string ID of the Environment Type. |
Responses
Response samples
- 204
- 401
- 404
- 409
{- "description": "Environments used for automated QA.",
- "id": "qa-automation"
}Updates Environment Type
Updates Environment Type.
path Parameters
| orgId required | string The Organization ID. |
| envTypeId required | string ID of the Environment Type. |
Request Body schema: application/json
| description | string or null |
Responses
Request samples
- Payload
{- "description": "Example Environment Type description"
}Response samples
- 200
- 401
- 404
{- "description": "Environments used for automated QA.",
- "id": "qa-automation"
}Environments are independent spaces where Applications can run. An Application is always deployed into an Environment.
| created_at required | string <date-time> (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... The timestamp in UTC of when the Environment was created. |
| created_by required | string The user who created the Environment |
object (DeploymentResponse) 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. | |
| id required | string^[a-z0-9](?:-?[a-z0-9]+)+$ The ID the Environment is referenced as. |
object (DeploymentResponse) 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. | |
| name required | string The Human-friendly name for the Environment. |
| type required | string The Environment Type. This is used for organizing and managing Environments. |
{- "created_at": "2020-05-22T14:58:07Z",
- "from_deploy": {
- "comment": "Updated version of module-one to v0.3.1",
- "created_at": "2020-05-22T14:58:07Z",
- "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",
- "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"
}Add a new Environment to an Application.
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.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
Request Body schema: application/json
The ID, Name, Type, and Deployment the Environment will be derived from.
| from_deploy_id | string Defines the existing Deployment the new Environment will be based on. |
| id required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ The ID the Environment is referenced as. |
| name required | string The Human-friendly name for the Environment. |
| type | string The Environment Type. This is used for organizing and managing Environments. |
Responses
Request samples
- Payload
{- "from_deploy_id": "e80db1a327208c1a",
- "id": "awesome-feature",
- "name": "Awesome Feature Dev",
- "namespace": "awesome-namespace",
- "type": "development"
}Response samples
- 201
- 400
- 404
- 409
{ }Update a specific Environment.
Update a specific Environment in an Application.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
Request Body schema: application/json
| name | string The Human-friendly name for the Environment. |
Responses
Request samples
- Payload
{- "name": "string"
}Response samples
- 200
- 404
{ }Delete a specific Environment.
Deletes a specific Environment in an Application.
Deleting an Environment will also delete the Deployment history of the Environment.
Deletions are currently irreversible.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
Responses
Response samples
- 400
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}Rebase to a different Deployment.
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.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
Request Body schema: application/json
The Deployment ID to rebase to.
Responses
Request samples
- Payload
"string"Response samples
- 400
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}DEPRECATED: This type exists for historical compatibility and should not be used. Please use the Artefact API instead.
Container Images (known simply as Images) can be registered with Humanitec. Continuous Integration (CI) pipelines can then notify Humanitec when a new build of a Container Image becomes available. Humanitec tracks the Image along with metadata about how it was built.
| added_at | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... The time the first build of this Image was added to the organization |
Array of objects (ImageBuildRequest) A list of Image Builds ordered by addition date. | |
| id | string The ID used to group different builds of the same Image together. |
| source | string The Image Source that this Image is added via |
{- "added_at": "2020-06-22T09:37:23.523Z",
- "builds": [
- {
- "branch": "master",
- "commit": "884bccaa807ea27cc1997a7492a3b6279fd7bd55",
- "image": "registry.humanitec.io/my-org/my-service:1.2.7",
- "tags": [
- "string"
]
}
], - "id": "my-service",
- "source": "github"
}List all Container Images
DEPRECATED: This endpoint exists for historical compatibility and should not be used. Please use the Artefact API instead.
Lists all of the Container Images registered for this organization.
path Parameters
| orgId required | string Example: sample-org The organization ID. |
Responses
Response samples
- 200
[- {
- "added_at": "2020-06-22T09:37:23.523Z",
- "builds": [
- {
- "added_at": "2020-06-22T09:37:23.523Z",
- "branch": "master",
- "commit": "884bccaa807ea27cc1997a7492a3b6279fd7bd55",
- "image": "registry.humanitec.io/my-org/my-service:1.2.7",
- "tags": [
- "string"
]
}
], - "id": "my-service",
- "source": "github"
}
]Get a specific Image Object
DEPRECATED: This endpoint exists for historical compatibility and should not be used. Please use the Artefact API instead.
The response includes a list of Image Builds as well as some metadata about the Image such as its Image Source.
Note, imageId may not be the same as the container name. imageId is determined by the system making notifications about new builds.
path Parameters
| orgId required | string Example: sample-org The organization ID. |
| imageId required | string Example: sample-app The Image ID. |
Responses
Response samples
- 200
- 404
{- "added_at": "2020-06-22T09:37:23.523Z",
- "builds": [
- {
- "added_at": "2020-06-22T09:37:23.523Z",
- "branch": "master",
- "commit": "884bccaa807ea27cc1997a7492a3b6279fd7bd55",
- "image": "registry.humanitec.io/my-org/my-service:1.2.7",
- "tags": [
- "string"
]
}
], - "id": "my-service",
- "source": "github"
}Lists all the Builds of an Image
DEPRECATED: This endpoint exists for historical compatibility and should not be used. Please use the Artefact API instead.
The response lists all available Image Builds of an Image.
path Parameters
| orgId required | string Example: sample-org The organization ID. |
| imageId required | string Example: sample-app The Image ID. |
Responses
Response samples
- 200
- 404
[- {
- "added_at": "2020-06-22T09:37:23.523Z",
- "branch": "master",
- "commit": "884bccaa807ea27cc1997a7492a3b6279fd7bd55",
- "image": "registry.humanitec.io/my-org/my-service:1.2.7",
- "tags": [
- "string"
]
}
]Add a new Image Build
DEPRECATED: This endpoint exists for historical compatibility and should not be used. Please use the Artefact API instead.
This endpoint is used by Continuous Integration (CI) pipelines to notify Humanitec that a new Image Build is available.
If there is no Image with ID imageId, it will be automatically created.
path Parameters
| orgId required | string Example: sample-org The organization ID. |
| imageId required | string Example: sample-app The Image ID. |
Request Body schema: application/json
The metadata associated with the build.
| branch | string The branch name of the branch the build was built on |
| commit | string The commit ID that this build was built from. |
| image | string^((?:[\w.\-_]+(?:(?::\d+|)(?=/[a-z0-9._-]+/[a... The fully qualified Image URL including registry, repository and tag. |
| tags | Array of strings The tag that the build was built from. |
Responses
Request samples
- Payload
{- "branch": "master",
- "commit": "884bccaa807ea27cc1997a7492a3b6279fd7bd55",
- "image": "registry.humanitec.io/my-org/my-service:1.2.7",
- "tags": [
- "string"
]
}Response samples
- 400
- 401
- 403
{- "error": "API-000",
- "message": "Could not validate token."
}PublicKey stores a Public Key an organization shares with Humanitec.
| id required | string |
| key required | string |
| created_at required | string <date-time> (Simplified extended ISO format date/time string.) |
| created_by required | string |
| expired_at required | string <date-time> (Date of key expiration.) |
| fingerprint required | string It's the hexadecimal representation of the sha256 hash of the DER representation of the key, it's computed and stored when a new key is uploaded. |
{- "id": "string",
- "key": "string",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "expired_at": "2020-06-22T09:37:23.523Z",
- "fingerprint": "string"
}Associate a new RSA public key to an organization.
path Parameters
| orgId required | string The organization ID. |
Request Body schema: application/json
A pcks8 RSA public key PEM encoded (as the ones produced by openssl), whose module length is greater or equal than 4096 bits. It should be provided as a single line. This might be accomplished through the usage of awk bash tool: awk -v ORS='\n' '1' public_key.pem
Responses
Request samples
- Payload
"-----BEGIN PUBLIC KEY-----\\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAo22jj/h+WPhL5M8RUyqC\\nEqRK3FOYD6KuDTyUHZL2QUX/q35bT1aGIOtu+22oM/8hTZ/6+BTknvF+Z+e7At8E\\n/I6/qNZilJFH/HqNHYflykceILVCFQM6v0ar6CSPh88DjwQPGLrh+UYp0NKBF6D5\\n2LEVQpxsM/0qV4fOZngRVI9UeKiYehk8aXJi20nI5Cj9GnV7BuEo7sKq7NewTOMN\\nwHqSnCtMV+E7SIgyy4+aKAFHOR0Y4FgJN14bAjE2GX/VUmAYBNtPgGwkCNDbA9v1\\nJJnFmdKflp8foqeWwC9UcUDLqjZzMT2a16pnL89iHV4fJ4vI6h26Jf2wUJbb7xE3\\nxJNhCR9Qf2IHx8TTVetIRl5I/ZUPkRrq5iskOIWV4+I+NzS+gbnCUv6sCO3cnZaa\\noZ4Wk5V+5qfctANeTn0TEAabYAJ/zFgYcs2IwYNqcN5eTss99zGNgtDL3oJr/A6g\\neGBgzad3p80qPMb1le64cHAAFZaerI2kcdnNpWGLXJ/J7IKF9uNfsrvi7Zdv8AXg\\nVAyqBARfzSkgnUKN6iWkWxAAzylKnQ3Etw81huaLwDG/6Lqd8I5OePMwHEZkollD\\nEBD16L/iyV9veru2zLVXkX/nL64YtZERLOWI5NUMaSurAR4N3ptFAsDRcO5Z4+Dq\\nO3pqszSh1aCyJvyl6cjQLT8CAwEAAQ==\\n-----END PUBLIC KEY-----\\n"Response samples
- 200
- 400
- 403
- 409
{- "id": "string",
- "key": "string",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "expired_at": "2020-06-22T09:37:23.523Z",
- "fingerprint": "string"
}List all public keys associated to an organization.
path Parameters
| orgId required | string The organization ID. |
query Parameters
| fingerprint | string The fingerprint (the hexadecimal representation of the sha256 hash of the DER representation of the key) of the requested key. If a value is provided, the result will contain a single key, if any. |
Responses
Response samples
- 200
- 400
[- {
- "id": "string",
- "key": "string",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "expired_at": "2020-06-22T09:37:23.523Z",
- "fingerprint": "string"
}
]Retrieve a single public key associated to an organization.
path Parameters
| orgId required | string The organization ID. |
| keyId required | string The public key ID. |
Responses
Response samples
- 200
- 404
{- "id": "string",
- "key": "string",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "expired_at": "2020-06-22T09:37:23.523Z",
- "fingerprint": "string"
}An Organization is the top level object in Humanitec. All other objects belong to an Organization.
| created_at required | string or null <date-time> Timestamp when the Organization was created. |
| created_by required | string User ID that created the Organization. |
| id required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ Unique ID for the Organization. |
required | object (LogoResponse) |
| name required | string Human friendly name for the Organization. |
| trial_expires_at required | string or null <date-time> Timestamp the trial expires at. |
| scaffolding_url | string or null URL of the scaffolding service. |
{- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "id": "string",
- "logo": {
- "dark_url": "string",
- "light_url": "string"
}, - "name": "string",
- "trial_expires_at": "2020-06-22T09:37:23.523Z",
- "scaffolding_url": "string"
}Response samples
- 200
- 403
[- {
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "id": "string",
- "logo": {
- "dark_url": "string",
- "light_url": "string"
}, - "name": "string",
- "trial_expires_at": "2020-06-22T09:37:23.523Z",
- "scaffolding_url": "string"
}
]Get the specified Organization.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
Responses
Response samples
- 200
- 403
{- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "id": "string",
- "logo": {
- "dark_url": "string",
- "light_url": "string"
}, - "name": "string",
- "trial_expires_at": "2020-06-22T09:37:23.523Z",
- "scaffolding_url": "string"
}Humanitec can be used to manage registry credentials. The Registry object represents how to match credentials to a particular registry.
Humanitec supports all Docker compatible registries as well as the custom authentication formats used by AWS Elastic Container Registry and Google Container Registry. It also supports the injection of a specific secret to be copied from an existing namespace in the cluster.
object (AccountCredsRequest) AccountCreds represents an account credentials (either, username- or token-based). | |
| enable_ci | boolean Indicates if registry secrets and credentials should be exposed to CI agents. |
| id required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ Registry ID, unique within the Organization. |
| registry required | string Registry name, usually in a "{domain}" or "{domain}/{project}" format. |
object (ClusterSecretsMapRequest) ClusterSecretsMap stores a list of Kuberenetes secret references for the target deployment clusters. | |
| type required | string Registry type, describes the registry authentication method, and defines the schema for the credentials. Supported values:
|
{- "created_at": "2020-05-22T14:53:27Z",
- "enable_ci": false,
- "id": "humanitec",
- "registry": "registry.humanitec.io",
- "secrets": {
- "*": {
- "namespace": "dev-secrets",
- "secret": "custom-regcred"
}, - "cluster-A": {
- "namespace": "prod-secrets",
- "secret": "custom-regcred"
}
}, - "type": "basic"
}Lists available registries for the organization.
path Parameters
| orgId required | string Unique (alpha-numerical) organization identifier. |
Responses
Response samples
- 200
- 400
- 404
[- {
- "created_at": "2020-05-22T14:53:27Z",
- "enable_ci": false,
- "id": "humanitec",
- "registry": "registry.humanitec.io",
- "secrets": {
- "*": {
- "namespace": "dev-secrets",
- "secret": "custom-regcred"
}, - "cluster-A": {
- "namespace": "prod-secrets",
- "secret": "custom-regcred"
}
}, - "type": "basic"
}
]Creates a new registry record.
path Parameters
| orgId required | string Unique (alpha-numerical) organization identifier. |
Request Body schema: application/json
A new record details.
object (AccountCredsRequest) AccountCreds represents an account credentials (either, username- or token-based). | |
| enable_ci | boolean Indicates if registry secrets and credentials should be exposed to CI agents. |
| id required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ Registry ID, unique within the Organization. |
| registry required | string Registry name, usually in a "{domain}" or "{domain}/{project}" format. |
object (ClusterSecretsMapRequest) ClusterSecretsMap stores a list of Kuberenetes secret references for the target deployment clusters. | |
| type required | string Registry type, describes the registry authentication method, and defines the schema for the credentials. Supported values:
|
Responses
Request samples
- Payload
{- "created_at": "2020-05-22T14:53:27Z",
- "enable_ci": false,
- "id": "humanitec",
- "registry": "registry.humanitec.io",
- "secrets": {
- "*": {
- "namespace": "dev-secrets",
- "secret": "custom-regcred"
}, - "cluster-A": {
- "namespace": "prod-secrets",
- "secret": "custom-regcred"
}
}, - "type": "basic"
}Response samples
- 201
- 400
- 401
- 404
- 409
{- "created_at": "2020-05-22T14:53:27Z",
- "enable_ci": false,
- "id": "humanitec",
- "registry": "registry.humanitec.io",
- "secrets": {
- "*": {
- "namespace": "dev-secrets",
- "secret": "custom-regcred"
}, - "cluster-A": {
- "namespace": "prod-secrets",
- "secret": "custom-regcred"
}
}, - "type": "basic"
}Loads a registry record details.
path Parameters
| orgId required | string Unique (alpha-numerical) organization identifier. |
| regId required | string Unique (alpha-numerical) registry identifier. |
Responses
Response samples
- 200
- 400
- 404
{- "created_at": "2020-05-22T14:53:27Z",
- "enable_ci": false,
- "id": "humanitec",
- "registry": "registry.humanitec.io",
- "secrets": {
- "*": {
- "namespace": "dev-secrets",
- "secret": "custom-regcred"
}, - "cluster-A": {
- "namespace": "prod-secrets",
- "secret": "custom-regcred"
}
}, - "type": "basic"
}Deletes an existing registry record and all associated credentials and secrets.
Deletions are currently irreversible.
path Parameters
| orgId required | string Unique (alpha-numerical) organization identifier. |
| regId required | string Unique (alpha-numerical) registry identifier. |
Responses
Response samples
- 400
- 403
- 404
{- "error": "string"
}Updates (patches) an existing registry record.
path Parameters
| orgId required | string Unique (alpha-numerical) organization identifier. |
| regId required | string Unique (alpha-numerical) registry identifier. |
Request Body schema: application/json
Record details to update.
object (AccountCredsRequest) AccountCreds represents an account credentials (either, username- or token-based). | |
| enable_ci | boolean Indicates if registry secrets and credentials should be exposed to CI agents. |
| id required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ Registry ID, unique within the Organization. |
| registry required | string Registry name, usually in a "{domain}" or "{domain}/{project}" format. |
object (ClusterSecretsMapRequest) ClusterSecretsMap stores a list of Kuberenetes secret references for the target deployment clusters. | |
| type required | string Registry type, describes the registry authentication method, and defines the schema for the credentials. Supported values:
|
Responses
Request samples
- Payload
{- "created_at": "2020-05-22T14:53:27Z",
- "enable_ci": false,
- "id": "humanitec",
- "registry": "registry.humanitec.io",
- "secrets": {
- "*": {
- "namespace": "dev-secrets",
- "secret": "custom-regcred"
}, - "cluster-A": {
- "namespace": "prod-secrets",
- "secret": "custom-regcred"
}
}, - "type": "basic"
}Response samples
- 200
- 400
- 403
- 404
- 409
{- "created_at": "2020-05-22T14:53:27Z",
- "enable_ci": false,
- "id": "humanitec",
- "registry": "registry.humanitec.io",
- "secrets": {
- "*": {
- "namespace": "dev-secrets",
- "secret": "custom-regcred"
}, - "cluster-A": {
- "namespace": "prod-secrets",
- "secret": "custom-regcred"
}
}, - "type": "basic"
}Returns current account credentials or secret details for the registry.
path Parameters
| orgId required | string Unique (alpha-numerical) organization identifier. |
| regId required | string Unique (alpha-numerical) registry identifier. |
Responses
Response samples
- 200
- 400
- 401
- 404
{- "expires": "2020-05-22T14:53:27Z",
- "password": "",
- "registry": "registry.io/project",
- "secrets": {
- "*": {
- "namespace": "dev-secrets",
- "secret": "custom-regcred"
}, - "cluster-A": {
- "namespace": "prod-secrets",
- "secret": "custom-regcred"
}
}, - "username": ""
}RuntimeInfo object returned by the runtime endpoint. Represents a list post statuses grouped by modules and controllers (deployments and stateful sets).
required | object Modules represent a collection of workloads for the application. |
| namespace required | string The namespace where the application runs. |
{- "modules": {
- "property1": {
- "status": "Running",
- "status_class": "Success",
- "controllers": {
- "property1": {
- "kind": "string",
- "replicas": 0,
- "status": "Running",
- "message": "string",
- "pods": [
- {
- "podName": "string",
- "revision": 0,
- "phase": "Pending",
- "status": "Failure",
- "containerStatuses": [
- {
- "name": "string",
- "ready": true,
- "restart_count": 0,
- "status": "Failure",
- "state": {
- "waiting": null,
- "running": null,
- "terminated": null
}
}
]
}
], - "revision": 0
}, - "property2": {
- "kind": "string",
- "replicas": 0,
- "status": "Running",
- "message": "string",
- "pods": [
- {
- "podName": "string",
- "revision": 0,
- "phase": "Pending",
- "status": "Failure",
- "containerStatuses": [
- {
- "name": "string",
- "ready": true,
- "restart_count": 0,
- "status": "Failure",
- "state": {
- "waiting": null,
- "running": null,
- "terminated": null
}
}
]
}
], - "revision": 0
}
}
}, - "property2": {
- "status": "Running",
- "status_class": "Success",
- "controllers": {
- "property1": {
- "kind": "string",
- "replicas": 0,
- "status": "Running",
- "message": "string",
- "pods": [
- {
- "podName": "string",
- "revision": 0,
- "phase": "Pending",
- "status": "Failure",
- "containerStatuses": [
- {
- "name": "string",
- "ready": true,
- "restart_count": 0,
- "status": "Failure",
- "state": {
- "waiting": null,
- "running": null,
- "terminated": null
}
}
]
}
], - "revision": 0
}, - "property2": {
- "kind": "string",
- "replicas": 0,
- "status": "Running",
- "message": "string",
- "pods": [
- {
- "podName": "string",
- "revision": 0,
- "phase": "Pending",
- "status": "Failure",
- "containerStatuses": [
- {
- "name": "string",
- "ready": true,
- "restart_count": 0,
- "status": "Failure",
- "state": {
- "waiting": null,
- "running": null,
- "terminated": null
}
}
]
}
], - "revision": 0
}
}
}
}, - "namespace": "string"
}Get Runtime information about the environment.
Runtime info are fetched from the cluster provisioned by the Orchestrator with Resource Id k8s-cluster-runtime. If no cluster with that id is found, the system fetches information from a cluster provisioned with the default Resource Id k8s-cluster.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| envId required | string Example: development The Environment ID |
Responses
Response samples
- 200
- 400
- 404
{- "modules": {
- "property1": {
- "deploy": {
- "success": "complete",
- "when": "before"
}, - "externals": { },
- "profile": "string",
- "spec": { },
- "property1": {
- "kind": "string",
- "message": "string",
- "pods": [
- {
- "containerStatuses": [
- { }
], - "phase": "string",
- "podName": "string",
- "revision": 0,
- "status": "string"
}
], - "replicas": 0,
- "revision": 0,
- "status": "string"
}, - "property2": {
- "kind": "string",
- "message": "string",
- "pods": [
- {
- "containerStatuses": [
- { }
], - "phase": "string",
- "podName": "string",
- "revision": 0,
- "status": "string"
}
], - "replicas": 0,
- "revision": 0,
- "status": "string"
}
}, - "property2": {
- "deploy": {
- "success": "complete",
- "when": "before"
}, - "externals": { },
- "profile": "string",
- "spec": { },
- "property1": {
- "kind": "string",
- "message": "string",
- "pods": [
- {
- "containerStatuses": [
- { }
], - "phase": "string",
- "podName": "string",
- "revision": 0,
- "status": "string"
}
], - "replicas": 0,
- "revision": 0,
- "status": "string"
}, - "property2": {
- "kind": "string",
- "message": "string",
- "pods": [
- {
- "containerStatuses": [
- { }
], - "phase": "string",
- "podName": "string",
- "revision": 0,
- "status": "string"
}
], - "replicas": 0,
- "revision": 0,
- "status": "string"
}
}
}, - "namespace": "string"
}Get Runtime information about specific multiple environments.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
query Parameters
| id | Array of strings Filter environments by ID (required). Up to 5 ids can be supplied per request. |
Responses
Response samples
- 200
- 400
[- {
- "id": "development",
- "paused": true,
- "status": "Success"
}, - {
- "id": "staging",
- "paused": false,
- "status": "Warning"
}, - {
- "error": "Environment my-org/my-app/not-existing-env does not exist",
- "id": "not-existing-env",
- "paused": false
}
]Provision and check the cluster connectivity in an environment
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
Request Body schema: application/json
Parameters required to start a cluster provisioning and connection check.
| app_id required | string The application Id to test |
| env_id required | string The environment Id to test |
| env_type required | string The environment type to test |
Responses
Request samples
- Payload
{- "app_id": "sample-app",
- "env_id": "sample-env",
- "env_type": "development"
}Response samples
- 200
{- "success": true,
- "resource_summaries": [
- {
- "type": "k8s-cluster",
- "class": "default",
- "res_id": "k8s-cluster",
- "gu_res_id": "0123456789abcdef0123456789abcdef",
- "depends_on": [
- "0123456789abcdef0123456789abcdee",
- "0123456789abcdef0123456789abcded"
], - "def_id": "sample-definition",
- "def_version_id": "01234567-89ab-cdef-0123-456789abcdef",
- "driver_type": "humanitec/echo"
}
], - "conditions": [
- {
- "type": "GraphCanProvision",
- "status": "True",
- "message": "A sample message."
}
]
}Secret Store represents external secret management system used by an organization to store secrets referenced in Humanitec.
object (AWSSMRequest) AWS Secret Manager specification. | |
object (AzureKVRequest) Azure Key Vault specification. | |
| created_at | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... |
| created_by | string |
object (GCPSMRequest) GCP Secret Manager specification. | |
| humanitec | object (HumanitecRequest) Humanitec built-in Secret Store specification. |
| id | string |
| primary | boolean |
| updated_at | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... |
| updated_by | string |
object (VaultRequest) Vault specification. |
{- "awssm": {
- "auth": {
- "access_key_id": "string",
- "secret_access_key": "string"
}, - "endpoint": "string",
- "region": "string"
}, - "azurekv": {
- "auth": {
- "client_id": "string",
- "client_secret": "string"
}, - "tenant_id": "string",
- "url": "string"
}, - "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "gcpsm": {
- "auth": {
- "secret_access_key": "string"
}, - "project_id": "string"
}, - "humanitec": { },
- "id": "string",
- "primary": true,
- "updated_at": "2020-06-22T09:37:23.523Z",
- "updated_by": "string",
- "vault": {
- "agent_id": "string",
- "auth": {
- "role": "string",
- "token": "string"
}, - "path": "string",
- "url": "string"
}
}Get list of Secret Stores for the given organization.
path Parameters
| orgId required | string The Organization ID. |
Responses
Response samples
- 200
[- {
- "awssm": {
- "endpoint": "string",
- "region": "string"
}, - "azurekv": {
- "tenant_id": "string",
- "url": "string"
}, - "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "gcpsm": {
- "project_id": "string"
}, - "humanitec": { },
- "id": "string",
- "primary": true,
- "updated_at": "2020-06-22T09:37:23.523Z",
- "updated_by": "string",
- "vault": {
- "agent_id": "string",
- "path": "string",
- "url": "string"
}
}
]Create a Secret Store for the given organization.
path Parameters
| orgId required | string The Organization ID. |
Request Body schema: application/json
Secret Store data.
object (AWSSMRequest) AWS Secret Manager specification. | |
object (AzureKVRequest) Azure Key Vault specification. | |
object (GCPSMRequest) GCP Secret Manager specification. | |
| id required | string^[a-z0-9](?:-?[a-z0-9]+)+$ The Secret Store ID. |
| primary required | boolean Defines whether the Secret Store is the primary secret management system for the organization. |
object (VaultRequest) Vault specification. |
Responses
Request samples
- Payload
{- "awssm": {
- "auth": {
- "access_key_id": "...",
- "secret_access_key": "..."
}, - "region": "us-east-1"
}, - "id": "my-aws-secret-manager",
- "primary": true
}Response samples
- 201
- 400
- 401
- 409
{- "awssm": {
- "endpoint": "string",
- "region": "string"
}, - "azurekv": {
- "tenant_id": "string",
- "url": "string"
}, - "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "gcpsm": {
- "project_id": "string"
}, - "humanitec": { },
- "id": "string",
- "primary": true,
- "updated_at": "2020-06-22T09:37:23.523Z",
- "updated_by": "string",
- "vault": {
- "agent_id": "string",
- "path": "string",
- "url": "string"
}
}Get the Secret Store.
path Parameters
| orgId required | string The Organization ID. |
| storeId required | string The Secret Store ID. |
Responses
Response samples
- 200
- 404
{- "awssm": {
- "endpoint": "string",
- "region": "string"
}, - "azurekv": {
- "tenant_id": "string",
- "url": "string"
}, - "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "gcpsm": {
- "project_id": "string"
}, - "humanitec": { },
- "id": "string",
- "primary": true,
- "updated_at": "2020-06-22T09:37:23.523Z",
- "updated_by": "string",
- "vault": {
- "agent_id": "string",
- "path": "string",
- "url": "string"
}
}Update the Secret Store.
path Parameters
| orgId required | string The Organization ID. |
| storeId required | string The Secret Store ID. |
Request Body schema: application/json
Secret Store data.
object (AWSSMRequest) AWS Secret Manager specification. | |
object (AzureKVRequest) Azure Key Vault specification. | |
object (GCPSMRequest) GCP Secret Manager specification. | |
| primary | boolean or null Defines whether the Secret Store is the primary secret management system for the organization. |
object (VaultRequest) Vault specification. |
Responses
Request samples
- Payload
{- "awssm": {
- "auth": {
- "secret_access_key": "s0mE_te$t_wrIte_kee"
}, - "region": "us-east-1"
}, - "primary": true
}Response samples
- 200
- 400
- 404
{- "awssm": {
- "endpoint": "string",
- "region": "string"
}, - "azurekv": {
- "tenant_id": "string",
- "url": "string"
}, - "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "gcpsm": {
- "project_id": "string"
}, - "humanitec": { },
- "id": "string",
- "primary": true,
- "updated_at": "2020-06-22T09:37:23.523Z",
- "updated_by": "string",
- "vault": {
- "agent_id": "string",
- "path": "string",
- "url": "string"
}
}Shared Values can be used to manage variables and configuration that might vary between environments. They are also the way that secrets can be stored securely.
Shared Values are by default shared across all environments in an application. However, they can be overridden on an Environment by Environment basis.
For example: There might be 2 API keys that are used in an application. One development key used in the development and staging environments and another used for production. The development API key would be set at the Application level. The value would then be overridden at the Environment level for the production Environment.
| description | string A Human friendly description of what the Shared Value is. |
| is_secret | boolean Specified that the Shared Value contains a secret. |
| key | string The unique key by which the Shared Value can be referenced. pattern: ^[a-zA-Z0-9._-]+$. |
| value | string The value that will be stored. (Will be always empty for secrets.) |
object or null (SecretReference) It stores sensitive value in the organization primary store or a reference to a sensitive value stored in a store registered under the organization. |
{- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}List Shared Values in an Environment
The returned values will be the base Application values with the Environment overrides where applicable. The source field will specify the level from which the value is from.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
Responses
Response samples
- 200
[- {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}
]Create a Shared Value for an Environment
The Shared Value created will only be available to the specific Environment.
If a Value is marked as a secret, it will be securely stored. It will not be possible to retrieve the value again through the API. The value of the secret can however be updated.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
Request Body schema: application/json
Definition of the new Shared Value.
| description required | string or null |
| is_secret | boolean |
| key required | string^[A-Za-z0-9_.-]+$ |
| value | string or null |
object or null (SecretReference) It stores sensitive value in the organization primary store or a reference to a sensitive value stored in a store registered under the organization. |
Responses
Request samples
- Payload
{- "description": "string",
- "is_secret": true,
- "key": "string",
- "value": "string",
- "secret_ref": {
- "store": "string",
- "ref": "string",
- "version": "string",
- "value": "string"
}
}Response samples
- 201
- 400
- 409
{- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}Update Shared Value for an Environment
Update the value or description of the Shared Value. Shared Values marked as secret can also be updated.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
| key required | string The key to update. |
Request Body schema: application/json
Both value and description must be supplied. All other fields will be ignored.
| description required | string or null |
| value | string or null |
| is_secret | boolean |
| key | string^[A-Za-z0-9_.-]+$ |
object or null (SecretReference) It stores sensitive value in the organization primary store or a reference to a sensitive value stored in a store registered under the organization. |
Responses
Request samples
- Payload
{- "description": "string",
- "value": "string",
- "is_secret": true,
- "key": "string",
- "secret_ref": {
- "store": "string",
- "ref": "string",
- "version": "string",
- "value": "string"
}
}Response samples
- 200
- 400
- 404
{- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}Delete Shared Value for an Environment
The specified Shared Value will be permanently deleted. If the Shared Value is marked as a secret, it will also be permanently deleted.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
| key required | string The key to update. |
Responses
Response samples
- 400
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}Update Shared Value for an Environment
Update the value or description of the Shared Value. Shared Values marked as secret can also be updated.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
| key required | string The key to update. |
Request Body schema: application/json
At least value or description must be supplied. All other fields will be ignored.
| description | string or null |
| value | string or null |
object or null (SecretReference) It stores sensitive value in the organization primary store or a reference to a sensitive value stored in a store registered under the organization. |
Responses
Request samples
- Payload
{- "description": "string",
- "value": "string",
- "secret_ref": {
- "store": "string",
- "ref": "string",
- "version": "string",
- "value": "string"
}
}Response samples
- 200
- 400
- 404
{- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}List Shared Values in an Application
The returned values will be the "base" values for the Application. The overridden value for the Environment can be retrieved via the /orgs/{orgId}/apps/{appId}/envs/{envId}/values endpoint.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
Responses
Response samples
- 200
[- {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}
]Create a Shared Value for an Application
The Shared Value created will be available to all Environments in that Application.
If a Value is marked as a secret, it will be securely stored. It will not be possible to retrieve the value again through the API. The value of the secret can however be updated.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
Request Body schema: application/json
Definition of the new Shared Value.
| description required | string or null |
| is_secret | boolean |
| key required | string^[A-Za-z0-9_.-]+$ |
| value | string or null |
object or null (SecretReference) It stores sensitive value in the organization primary store or a reference to a sensitive value stored in a store registered under the organization. |
Responses
Request samples
- Payload
{- "description": "string",
- "is_secret": true,
- "key": "string",
- "value": "string",
- "secret_ref": {
- "store": "string",
- "ref": "string",
- "version": "string",
- "value": "string"
}
}Response samples
- 201
- 400
- 409
{- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}Update Shared Value for an Application
Update the value or description of the Shared Value. Shared Values marked as secret can also be updated.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| key required | string The key to update. |
Request Body schema: application/json
Both value and description must be supplied. All other fields will be ignored.
| description required | string or null |
| value | string or null |
| is_secret | boolean |
| key | string^[A-Za-z0-9_.-]+$ |
object or null (SecretReference) It stores sensitive value in the organization primary store or a reference to a sensitive value stored in a store registered under the organization. |
Responses
Request samples
- Payload
{- "description": "string",
- "value": "string",
- "is_secret": true,
- "key": "string",
- "secret_ref": {
- "store": "string",
- "ref": "string",
- "version": "string",
- "value": "string"
}
}Response samples
- 200
- 400
- 404
{- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}Delete Shared Value for an Application
The specified Shared Value will be permanently deleted. If the Shared Value is marked as a secret, it will also be permanently deleted.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| key required | string The key to update. |
Responses
Response samples
- 400
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}Update Shared Value for an Application
Update the value or description of the Shared Value. Shared Values marked as secret can also be updated.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| key required | string The key to update. |
Request Body schema: application/json
At least value or description must be supplied. All other fields will be ignored.
| description | string or null |
| value | string or null |
object or null (SecretReference) It stores sensitive value in the organization primary store or a reference to a sensitive value stored in a store registered under the organization. |
Responses
Request samples
- Payload
{- "description": "string",
- "value": "string",
- "secret_ref": {
- "store": "string",
- "ref": "string",
- "version": "string",
- "value": "string"
}
}Response samples
- 200
- 400
- 404
{- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}A Value Set Version can be used as a track record of Shared Values changes, to restore a previous version of a Shared Value or Value Set, or to purge a Shared Value if it shouldn't be accessible anymore.
required | Array of objects (JSONPatchesResponse) |
| comment required | string |
| created_at required | string <date-time> (Simplified extended ISO format date/time string.) |
| created_by required | string |
| id required | string |
| result_of required | string or null (ValueSetVersionResultOf) Enum: "app_value_create" "app_value_update" "app_value_delete" "app_values_delete" "app_value_set_version_restore" "app_value_set_version_purge" "env_value_create" "env_value_update" "env_value_delete" "env_values_delete" "env_value_set_version_restore" "env_value_set_version_purge" |
| source_value_set_version_id required | string or null |
| updated_at required | string <date-time> (Simplified extended ISO format date/time string.) |
required | object (ValueSetResponse) |
{- "change": [
- {
- "op": "string",
- "path": "string",
- "value": null
}
], - "comment": "string",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "id": "string",
- "result_of": "app_value_create",
- "source_value_set_version_id": "string",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "values": {
- "property1": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}, - "property2": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}
}
}List Value Set Versions in an Environment of an App
A new Value Set Version is created on every modification of a Value inside the an Environment of an App. In case this environment has no overrides the response is the same as the App level endpoint.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
query Parameters
| key_changed | string (Optional) Return only value set version where the specified key changed |
Responses
Response samples
- 200
[- {
- "change": [
- {
- "op": "string",
- "path": "string",
- "value": null
}
], - "comment": "string",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "id": "string",
- "result_of": "app_value_create",
- "source_value_set_version_id": "string",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "values": {
- "property1": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}, - "property2": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}
}
}
]Get a single Value Set Version in an Environment of an App. The zero version id (00000000-0000-0000-0000-000000000000) will return the latest Value Set Version.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
| valueSetVersionId required | string <uuid> The ValueSetVersion ID. |
Responses
Response samples
- 200
- 404
{- "change": [
- {
- "op": "string",
- "path": "string",
- "value": null
}
], - "comment": "string",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "id": "string",
- "result_of": "app_value_create",
- "source_value_set_version_id": "string",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "values": {
- "property1": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}, - "property2": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}
}
}Purge the value of a specific Shared Value from the App Environment Version history.
Purging permanently removes the value of a specific Shared Value in an application. A purged value is no longer accessible, can't be restored and can't be used by deployments referencing a Value Set Version where the value was present.
Learn more about purging in our docs.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
| valueSetVersionId required | string <uuid> The ValueSetVersion ID. |
| key required | string Key of the value to be purged. |
Request Body schema: application/json
| comment | string |
Responses
Request samples
- Payload
{- "comment": "string"
}Response samples
- 400
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}Restore a Value Set Version in an Environment of an App
Restore the values of all Shared Values in an environment from a specific version. Keys not existing in the selected version are deleted.
Learn more about reverting in our docs.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
| valueSetVersionId required | string <uuid> The ValueSetVersion ID. |
Request Body schema: application/json
| comment | string |
Responses
Request samples
- Payload
{- "comment": "string"
}Response samples
- 200
- 404
{- "change": [
- {
- "op": "string",
- "path": "string",
- "value": null
}
], - "comment": "string",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "id": "string",
- "result_of": "app_value_create",
- "source_value_set_version_id": "string",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "values": {
- "property1": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}, - "property2": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}
}
}Restore a specific key from the Value Set Version in an Environment of an App
Restore the values of a single Shared Value in an Environment from a specific version.
Learn more about reverting in our docs.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
| valueSetVersionId required | string <uuid> The ValueSetVersion ID. |
| key required | string Key of the value to be restored. |
Request Body schema: application/json
| comment | string |
Responses
Request samples
- Payload
{- "comment": "string"
}Response samples
- 200
- 400
- 404
{- "change": [
- {
- "op": "string",
- "path": "string",
- "value": null
}
], - "comment": "string",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "id": "string",
- "result_of": "app_value_create",
- "source_value_set_version_id": "string",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "values": {
- "property1": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}, - "property2": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}
}
}List Value Set Versions in the App
A new Value Set Version is created on every modification of a Value inside the app.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
query Parameters
| key_changed | string (Optional) Return only value set version where the specified key changed |
Responses
Response samples
- 200
[- {
- "change": [
- {
- "op": "string",
- "path": "string",
- "value": null
}
], - "comment": "string",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "id": "string",
- "result_of": "app_value_create",
- "source_value_set_version_id": "string",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "values": {
- "property1": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}, - "property2": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}
}
}
]Get a single Value Set Version from the App
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| valueSetVersionId required | string <uuid> The ValueSetVersion ID. |
Responses
Response samples
- 200
- 404
{- "change": [
- {
- "op": "string",
- "path": "string",
- "value": null
}
], - "comment": "string",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "id": "string",
- "result_of": "app_value_create",
- "source_value_set_version_id": "string",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "values": {
- "property1": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}, - "property2": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}
}
}Purge the value of a specific Shared Value from the App Version history.
Purging permanently removes the value of a specific Shared Value in an Application. A purged value is no longer accessible, can't be restored and can't be used by deployments referencing a Value Set Version where the value was present.
Learn more about purging in our docs.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| valueSetVersionId required | string <uuid> The ValueSetVersion ID. |
| key required | string Key of the value to be purged. |
Request Body schema: application/json
| comment | string |
Responses
Request samples
- Payload
{- "comment": "string"
}Response samples
- 400
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}Restore a Value Set Version in an App
Restore the values of all Shared Values in an application from a specific version. Keys not existing in the selected version are deleted.
Learn more about reverting in our docs.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| valueSetVersionId required | string <uuid> The ValueSetVersion ID. |
Request Body schema: application/json
| comment | string |
Responses
Request samples
- Payload
{- "comment": "string"
}Response samples
- 200
- 404
{- "change": [
- {
- "op": "string",
- "path": "string",
- "value": null
}
], - "comment": "string",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "id": "string",
- "result_of": "app_value_create",
- "source_value_set_version_id": "string",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "values": {
- "property1": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}, - "property2": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}
}
}Restore a specific key from the Value Set Version in an App
Restore the values of a single Shared Value in an application from a specific version.
Learn more about reverting in our docs.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| valueSetVersionId required | string <uuid> The ValueSetVersion ID. |
| key required | string Key of the value to be restored. |
Request Body schema: application/json
| comment | string |
Responses
Request samples
- Payload
{- "comment": "string"
}Response samples
- 200
- 400
- 404
{- "change": [
- {
- "op": "string",
- "path": "string",
- "value": null
}
], - "comment": "string",
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "id": "string",
- "result_of": "app_value_create",
- "source_value_set_version_id": "string",
- "updated_at": "2020-06-22T09:37:23.523Z",
- "values": {
- "property1": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}, - "property2": {
- "description": "The message to show me.",
- "is_secret": false,
- "key": "MY_MSG",
- "value": "Hello World"
}
}
}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.
Deployment Deltas can be created fully formed or combined together via PATCHing. They can also be generated from the difference between two Deployment Sets.
Basic Structure
{
"id": <ID of the Deployment Delta.>,
"metadata": {
<Properties such as who created the Delta, which Environment it is associated to and a Human-friendly name>
}
"modules" : {
"add" : {
<ID of Module to add to the Deployment Set> : {
<An entire Modules object>
}
},
"remove": [
<An array of Module IDs that should be removed from the Deployment Set>
],
"update": {
<ID of Module already in the Set to be updated> : [
<An array of JSON Patch (Search Results (RFC 6902) objects scoped to the module>
]
}
}
}
| id | string Ignored, but can be provided. |
object (DeltaMetadataRequest) | |
object (ModuleDeltasRequest) ModuleDeltas groups the different operations together. | |
Array of objects or null (UpdateActionRequest) |
{- "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"
}
]
}
}
}List Deltas in an Application
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
query Parameters
| archived | boolean If true, return archived Deltas. |
| env | string^[a-z0-9](?:-?[a-z0-9]+)+$ Only return Deltas associated with the specified Environment. |
Responses
Response samples
- 200
[- {
- "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"
}
]
}
}
}
]Create a new Delta
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
Request Body schema: application/json
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.
| id | string Ignored, but can be provided. |
object (DeltaMetadataRequest) | |
object (ModuleDeltasRequest) ModuleDeltas groups the different operations together. | |
Array of objects or null (UpdateActionRequest) |
Responses
Request samples
- Payload
{- "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}"
}
]
}
}
}Response samples
- 200
- 400
"string"Fetch an existing Delta
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| deltaId required | string ID of the Delta to fetch. |
Responses
Response samples
- 200
- 404
{- "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"
}
]
}
}
}Update an existing Delta
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| deltaId required | string ID of the Delta to update. |
Request Body schema: application/json
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.addproperty are replaced with the new Delta's values. If the value of a Module isnull, and the ID is in themodules.removelist, it is removed from themodules.removelist.All IDs listed in
modules.removeare combined. Any ID inmodules.removeand also inmodules.addare removed frommodules.addThe lists of JSON Patches in
modules.updateare concatenated or created inmodules.updates.
Simplification involves:
Applying any entries in
modules.updatesthat have matching IDs inmodules.addto themodules.addentry and removing themodules.updateentry.Reducing the number of JSON Patches in each
modules.updateentry 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.
| id | string Ignored, but can be provided. |
object (DeltaMetadataRequest) | |
object (ModuleDeltasRequest) ModuleDeltas groups the different operations together. | |
Array of objects or null (UpdateActionRequest) |
Responses
Request samples
- Payload
[- {
- "modules": {
- "updates": {
- "module-one": [
- {
- "op": "add",
- "path": "/spec/containers/simple-service/variables/REDIS_URL",
- "value": "redis://${modules.redis-cache.service.name}"
}
]
}
}
}
]Response samples
- 200
- 400
- 404
{- "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"
}
]
}
}
}Update an existing Delta
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| deltaId required | string ID of the Delta to update. |
Request Body schema: application/json
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.addproperty are replaced with the new Delta's values. If the value of a Module isnull, and the ID is in themodules.removelist, it is removed from themodules.removelist.All IDs listed in
modules.removeare combined. Any ID inmodules.removeand also inmodules.addare removed frommodules.addThe lists of JSON Patches in
modules.updateare concatenated or created inmodules.updates.
Simplification involves:
Applying any entries in
modules.updatesthat have matching IDs inmodules.addto themodules.addentry and removing themodules.updateentry.Reducing the number of JSON Patches in each
modules.updateentry 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.
| id | string Ignored, but can be provided. |
object (DeltaMetadataRequest) | |
object (ModuleDeltasRequest) ModuleDeltas groups the different operations together. | |
Array of objects or null (UpdateActionRequest) |
Responses
Request samples
- Payload
{- "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"
}
]
}
}
}Response samples
- 400
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}Mark a Delta as "archived"
Archived Deltas are still accessible but can no longer be updated.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| deltaId required | string ID of the Deployment Delta. |
Request Body schema: application/json
Either true or false.
Responses
Request samples
- Payload
trueResponse samples
- 400
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}Change the Environment of a Delta
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| deltaId required | string ID of the Deployment Delta. |
Request Body schema: application/json
The new Environment ID. (NOTE: The string must still be JSON encoded.)
Responses
Request samples
- Payload
"new-env"Response samples
- 400
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}Change the name of a Delta
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| deltaId required | string ID of the Deployment Delta. |
Request Body schema: application/json
The new name.(NOTE: The string must still be JSON encoded.)
Responses
Request samples
- Payload
"Update for ticket #s 2568 & 2572"Response samples
- 400
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}A Deployment Set (or just "Set") defines all of the non-Environment specific configuration for Modules and External Resources. Each of these Modules or External Resources has a unique name.
Deployment Sets are immutable and their ID is a cryptographic hash of their content. This means that a Deployment Set can be globally identified based on its ID. It also means that referencing a Deployment Set by ID will always return the same Deployment Set.
Deployment Sets cannot be created directly, instead they are created by applying a Deployment Delta to an existing Deployment Set.
Basic Structure
{
"id": <ID of the Deployment Set>,
"modules" : {
<ID of Module> : {
"profile": <Defines how the optional "spec" property is interpreted>
"spec": {
<Properties that depend on the "profile" property.>
}
"externals": {
<External Resource Name> : {
"type": <Resource Type>,
"params": {
<Properties which parametrize the resource depending on the Resource Type.>
}
}
}
}
}
}
For details about how the Humanitec provided profiles work, see (Deployment Set Profiles)[].
object The Modules that make up the Set | |
object Resources that are shared across the set | |
| version | integer The version of the Deployment Set Schema to use. (Currently, only 0 is supported, and if omitted, version 0 is assumed.) |
{- "modules": {
- "module-one": {
- "externals": {
- "db-one": {
- "params": {
- "extensions": {
- "uuid-ossp": { }
}
}, - "type": "postgres"
}
}, - "profile": "humanitec/default-module",
- "spec": {
- "containers": {
- "core-service": {
- "id": "core-service",
- "image": "registry.humanitec.io/my-org/core-service:VERSION_ONE",
- "readiness_probe": {
- "path": "/healtz",
- "port": 8080,
- "type": "http"
}, - "variables": {
- "DBHOST": "${externals.db-one.name}",
- "DBNAME": "${externals.db-one.name}",
- "DBPASSWORD": "${externals.db-one.password}",
- "DBUSERNAME": "${externals.db-one.username}",
- "REDIS_URL": "redis://${modules.redis-cache.service.name}"
}
}
}
}
}, - "redis-cache": {
- "profile": "humanitec/redis"
}
}
}Get all Deployment Sets
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
Responses
Response samples
- 200
- 404
[- {
- "modules": {
- "module-one": {
- "externals": {
- "db-one": {
- "params": {
- "extensions": {
- "uuid-ossp": { }
}
}, - "type": "postgres"
}
}, - "profile": "humanitec/default-module",
- "spec": {
- "containers": {
- "core-service": {
- "id": "core-service",
- "image": "registry.humanitec.io/my-org/core-service:VERSION_ONE",
- "readiness_probe": {
- "path": "/healtz",
- "port": 8080,
- "type": "http"
}, - "variables": {
- "DBHOST": "${externals.db-one.name}",
- "DBNAME": "${externals.db-one.name}",
- "DBPASSWORD": "${externals.db-one.password}",
- "DBUSERNAME": "${externals.db-one.username}",
- "REDIS_URL": "redis://${modules.redis-cache.service.name}"
}
}
}
}
}, - "redis-cache": {
- "profile": "humanitec/redis"
}
}
}
]Get a Deployment Set
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| setId required | string ID of the Deployment Set. |
query Parameters
| diff | string ID of the Deployment Set to compared against. |
Responses
Response samples
- 200
- 404
{- "modules": {
- "module-one": {
- "externals": {
- "db-one": {
- "params": {
- "extensions": {
- "uuid-ossp": { }
}
}, - "type": "postgres"
}
}, - "profile": "humanitec/default-module",
- "spec": {
- "containers": {
- "core-service": {
- "id": "core-service",
- "image": "registry.humanitec.io/my-org/core-service:VERSION_ONE",
- "readiness_probe": {
- "path": "/healtz",
- "port": 8080,
- "type": "http"
}, - "variables": {
- "DBHOST": "${externals.db-one.name}",
- "DBNAME": "${externals.db-one.name}",
- "DBPASSWORD": "${externals.db-one.password}",
- "DBUSERNAME": "${externals.db-one.username}",
- "REDIS_URL": "redis://${modules.redis-cache.service.name}"
}
}
}
}
}, - "redis-cache": {
- "profile": "humanitec/redis"
}
}
}Apply a Deployment Delta to a Deployment Set
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| setId required | string ID of the Deployment Set. |
Request Body schema: application/json
The Delta to apply to the Set.
NOTE: The id parameter is ignored if provided. The request body should be the full Delta.
| id | string Ignored, but can be provided. |
object (DeltaMetadataRequest) | |
object (ModuleDeltasRequest) ModuleDeltas groups the different operations together. | |
Array of objects or null (UpdateActionRequest) |
Responses
Request samples
- Payload
{- "modules": {
- "remove": [
- "module-one"
]
}
}Response samples
- 200
- 400
- 404
"string"Get the difference between 2 Deployment Sets
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| setId required | string ID of the Deployment Set. |
| sourceSetId required | string ID of the Deployment Set to diff against. |
Responses
Response samples
- 200
- 404
{- "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"
}
]
}
}
}Workload Profiles provide the baseline configuration for Workloads in Applications in Humanitec. Developers can configure various features of a workload profile to suit their needs. Examples of features might be schedules used in Kubernetes CronJobs or ingress which might be used to expose Pods controlled by a Kubernetes Deployment.
Workloads in Humanitec are implemented as Helm Charts which must implement a specific schema.
| id required | string Workload Profile ID |
| description | string Describes the workload profile |
| deprecation_message | string A not-empty string indicates that the workload profile is deprecated. |
required | object (WorkloadProfileSpecDefinition) Workload spec definition |
| version | string Version identifier. The version must be unique, but the API doesn't not enforce any ordering. Currently workloads will always use the latest update. If no identifier is provided, the each update will generate a random version identifier. |
required | object (WorkloadProfileChartReference) References a workload profile chart. |
{- "id": "string",
- "description": "string",
- "deprecation_message": "string",
- "spec_definition": {
- "properties": {
- "property1": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}, - "property2": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}
}, - "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
]
}, - "version": "string",
- "workload_profile_chart": {
- "id": "string",
- "version": "string"
}
}List workload profiles available to the organization.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
query Parameters
| deprecated | boolean Default: false Example: deprecated=true Whether to include deprecated profiles |
| per_page | integer [ 1 .. 100 ] Default: 50 Example: per_page=50 The maximum number of items to return in a page of results |
| page | string Example: page=AAAAAAAAAA== The page token to request from |
Responses
Response samples
- 200
[- {
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "description": "string",
- "deprecation_message": "string",
- "id": "string",
- "org_id": "string",
- "spec_definition": {
- "properties": {
- "property1": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}, - "property2": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}
}, - "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
]
}, - "spec_schema": null,
- "updated_at": "2019-08-24T14:15:22Z",
- "updated_by": "string",
- "version": "string",
- "workload_profile_chart": {
- "id": "string",
- "version": "string"
}
}
]Create new Workload Profile
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
Request Body schema: application/json
Workload profile details.
| id required | string Workload Profile ID |
| description | string Describes the workload profile |
| deprecation_message | string A not-empty string indicates that the workload profile is deprecated. |
required | object (WorkloadProfileSpecDefinition) Workload spec definition |
| version | string Version identifier. The version must be unique, but the API doesn't not enforce any ordering. Currently workloads will always use the latest update. If no identifier is provided, the each update will generate a random version identifier. |
required | object (WorkloadProfileChartReference) References a workload profile chart. |
Responses
Request samples
- Payload
{- "id": "string",
- "description": "string",
- "deprecation_message": "string",
- "spec_definition": {
- "properties": {
- "property1": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}, - "property2": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}
}, - "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
]
}, - "version": "string",
- "workload_profile_chart": {
- "id": "string",
- "version": "string"
}
}Response samples
- 201
- 400
- 409
{- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "description": "string",
- "deprecation_message": "string",
- "id": "string",
- "org_id": "string",
- "spec_definition": {
- "properties": {
- "property1": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}, - "property2": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}
}, - "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
]
}, - "spec_schema": null,
- "updated_at": "2019-08-24T14:15:22Z",
- "updated_by": "string",
- "version": "string",
- "workload_profile_chart": {
- "id": "string",
- "version": "string"
}
}Get a Workload Profile
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| profileQid required | string The Workload Profile ID. |
Responses
Response samples
- 200
- 400
- 404
{- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "description": "string",
- "deprecation_message": "string",
- "id": "string",
- "org_id": "string",
- "spec_definition": {
- "properties": {
- "property1": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}, - "property2": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}
}, - "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
]
}, - "spec_schema": null,
- "updated_at": "2019-08-24T14:15:22Z",
- "updated_by": "string",
- "version": "string",
- "workload_profile_chart": {
- "id": "string",
- "version": "string"
}
}Update a Workload Profile
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| profileQid required | string The Workload Profile ID. |
Request Body schema: application/json
Workload profile details.
| description | string Describes the workload profile |
| deprecation_message | string A not-empty string indicates that the workload profile is deprecated. |
required | object (WorkloadProfileSpecDefinition) Workload spec definition |
| version | string Version identifier. The version must be unique, but the API doesn't not enforce any ordering. Currently workloads will always use the latest update. If no identifier is provided, the each update will generate a random version identifier. |
required | object (WorkloadProfileChartReference) References a workload profile chart. |
Responses
Request samples
- Payload
{- "description": "string",
- "deprecation_message": "string",
- "spec_definition": {
- "properties": {
- "property1": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}, - "property2": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}
}, - "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
]
}, - "version": "string",
- "workload_profile_chart": {
- "id": "string",
- "version": "string"
}
}Response samples
- 200
- 400
- 404
- 409
{- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "description": "string",
- "deprecation_message": "string",
- "id": "string",
- "org_id": "string",
- "spec_definition": {
- "properties": {
- "property1": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}, - "property2": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}
}, - "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
]
}, - "spec_schema": null,
- "updated_at": "2019-08-24T14:15:22Z",
- "updated_by": "string",
- "version": "string",
- "workload_profile_chart": {
- "id": "string",
- "version": "string"
}
}Delete a Workload Profile
This will also delete all versions of a workload profile.
It is not possible to delete profiles of other organizations.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| profileQid required | string The Workload Profile ID. |
Responses
Response samples
- 400
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}List versions of the given workload profile.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| profileQid required | string The Workload Profile ID. |
query Parameters
| per_page | integer [ 1 .. 100 ] Default: 50 Example: per_page=50 The maximum number of items to return in a page of results |
| page | string Example: page=AAAAAAAAAA== The page token to request from |
Responses
Response samples
- 200
- 404
[- {
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "description": "string",
- "deprecation_message": "string",
- "id": "string",
- "org_id": "string",
- "spec_definition": {
- "properties": {
- "property1": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}, - "property2": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}
}, - "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
]
}, - "spec_schema": null,
- "workload_profile_chart": {
- "id": "string",
- "version": "string"
}, - "workload_profile_id": "string"
}
]Latest version of the given workload profile with optional constraint. Deprecated
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| profileQid required | string The Workload Profile ID. |
Responses
Response samples
- 200
- 404
{- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "description": "string",
- "deprecation_message": "string",
- "id": "string",
- "org_id": "string",
- "spec_definition": {
- "properties": {
- "property1": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}, - "property2": {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}, - "schema": { },
- "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
], - "properties": { }
}
}, - "runtime_properties": [
- {
- "type": "feature",
- "feature_name": "string",
- "title": "string",
- "version": "string",
- "ui_hints": {
- "order": 0,
- "hidden": true
}
}
]
}, - "spec_schema": null,
- "workload_profile_chart": {
- "id": "string",
- "version": "string"
}, - "workload_profile_id": "string"
}Add new Workload Profile Chart Version
Creates a Workload Profile Chart Version from the uploaded Helm chart. The name and version is retrieved from the chart's metadata (Charts.yaml file).
The request has content type multipart/form-data and the request body includes one part:
filewithapplication/x-gzipcontent type which is an archive containing a Helm chart.
Request body example:
Content-Type: multipart/form-data; boundary=----boundary ----boundary Content-Disposition: form-data; name="file"; filename="my-workload-1.0.1.tgz" Content-Type: application/x-gzip [TGZ_DATA] ----boundary
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
Request Body schema: multipart/form-data
Workload profile chart version.
| file | string <binary> |
Responses
Response samples
- 201
- 400
- 409
{- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "org_id": "string",
- "id": "string",
- "version": "string"
}Workload Profile Chart Versions for the given organization.
Returns all Workload Profile Chart Versions for the given organization.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
query Parameters
| per_page | integer [ 1 .. 100 ] Default: 50 Example: per_page=50 The maximum number of items to return in a page of results |
| page | string Example: page=AAAAAAAAAA== The page token to request from |
| id | string Filter Chart Versions by Chart Version ID. |
| version | string Filter Chart Versions by Chart Version. |
Responses
Response samples
- 200
[- {
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "org_id": "string",
- "id": "string",
- "version": "string"
}
]Active Resources represent the concrete resources provisioned for an Environment. They are provisioned on the first deployment after a dependency on a particular resource type is introduced into an Environment. In general, Active Resources are only deleted when their introductory Environment is deleted.
Active Resources are provisioned based on a Resource Definition. The Resource Definition describes how to provision a concrete resource based on a Resource Type and metadata about the Environment (for example the Environment Type or the Application ID). The criteria for how to choose a Resource Definition is known as a Matching Criteria. If the Matching Criteria changes or the Resource Definition is deleted, the concrete resource represented by an Active Resource might be deleted and reprovisioned when a deployment occurs in the Environment.
| app_id required | string The ID of the App the resource is associated with. |
| class required | string The Resource Class of the resource |
| criteria_id | string The Matching Criteria ID. |
| def_id required | string The Resource Definition that this resource was provisioned from. |
| def_version_id required | string The Resource Definition Version that this resource was provisioned from. |
| deploy_id required | string The deployment that the resource was last provisioned in. |
| driver_account | string (Optional) Security account required by the driver. |
| driver_type required | string The driver to be used to create the resource. |
| env_id required | string The ID of the Environment the resource is associated with. |
| env_type required | string The Environment Type of the Environment specified by env_id. |
| gu_res_id required | string Globally unique resource id |
| org_id required | string the ID of the Organization the Active Resource is associated with. |
| res_id required | string The ID of the resource |
required | object The resource provisioning outputs ('values' only). |
object Secret references from the resource provisioning output. | |
| status required | string Current resource status: 'pending', 'active', or 'deleting'. |
| type required | string The Resource Type of the resource |
| updated_at required | string <date-time> The time the resource was last provisioned as part of a deployment. |
{- "app_id": "test-app",
- "class": "default",
- "def_id": "gcp-dev-postgres",
- "def_version_id": "01234567-89ab-cdef-0123-4567890abcdef",
- "deploy_id": "172a1013b",
- "env_id": "gcp-dev",
- "env_type": "development",
- "gu_res_id": "7bd3966c9ff8eaa66c5cce855c03d715857c3440",
- "org_id": "test-org",
- "res_id": "modules.my-module.externals.my-db",
- "resource": {
- "host": "127.0.0.1",
- "name": "db_33c7ef9b_8d90-4c62_a1cf_0cdd30fd29a9",
- "port": 5432
}, - "secret_refs": {
- "credentials": "orgs/test-org/resources/7bd3966c9ff8eaa66c5cce855c03d715857c3440/secrets/.credentials"
}, - "type": "postgres",
- "updated_at": "2020-06-23T16:53:12Z"
}List Active Resources provisioned in an environment.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
Responses
Response samples
- 200
- 500
[- {
- "app_id": "test-app",
- "class": "default",
- "def_id": "gcp-dev-postgres",
- "def_version_id": "01234567-89ab-cdef-0123-4567890abcdef",
- "deploy_id": "172a1013b",
- "env_id": "gcp-dev",
- "env_type": "development",
- "gu_res_id": "7bd3966c9ff8eaa66c5cce855c03d715857c3440",
- "org_id": "test-org",
- "res_id": "modules.my-module.externals.my-db",
- "resource": {
- "host": "127.0.0.1",
- "name": "db_33c7ef9b_8d90-4c62_a1cf_0cdd30fd29a9",
- "port": 5432
}, - "secret_refs": {
- "credentials": "orgs/test-org/resources/7bd3966c9ff8eaa66c5cce855c03d715857c3440/secrets/.credentials"
}, - "type": "postgres",
- "updated_at": "2020-06-23T16:53:12Z"
}
]Delete Active Resource.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
| type required | string The Resource Type, may include a resource class: {type}.{class}. |
| resId required | string The Resource ID. |
query Parameters
| detach | boolean If set to |
Responses
Response samples
- 400
- 404
- 409
{- "error": "API-000",
- "message": "Could not validate token."
}Pin Active Resource to a target Resource Definition Version.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| envId required | string Example: development The Environment ID |
| type required | string The Resource Type, may include a resource class: {type}.{class}. |
| resId required | string The Resource ID. |
Request Body schema: application/json
| target_def_version_id required | string or null The Resource Definition Version pinned to this resource to be provisioned from. |
Responses
Request samples
- Payload
{- "target_def_version_id": "01234567-89ab-cdef-0123-4567890abcdef"
}Response samples
- 200
- 400
- 404
{- "app_id": "test-app",
- "class": "default",
- "def_id": "gcp-dev-postgres",
- "def_version_id": "01234567-89ab-cdef-0123-4567890abcdef",
- "deploy_id": "172a1013b",
- "env_id": "gcp-dev",
- "env_type": "development",
- "gu_res_id": "7bd3966c9ff8eaa66c5cce855c03d715857c3440",
- "org_id": "test-org",
- "res_id": "modules.my-module.externals.my-db",
- "resource": {
- "host": "127.0.0.1",
- "name": "db_33c7ef9b_8d90-4c62_a1cf_0cdd30fd29a9",
- "port": 5432
}, - "secret_refs": {
- "credentials": "orgs/test-org/resources/7bd3966c9ff8eaa66c5cce855c03d715857c3440/secrets/.credentials"
}, - "type": "postgres",
- "updated_at": "2020-06-23T16:53:12Z"
}List Active Resources provisioned via a specific Resource Definition.
path Parameters
| orgId required | string The Organization ID. |
| defId required | string The Resource Definition ID. |
Responses
Response samples
- 200
- 500
[- {
- "app_id": "test-app",
- "class": "default",
- "def_id": "gcp-dev-postgres",
- "def_version_id": "01234567-89ab-cdef-0123-4567890abcdef",
- "deploy_id": "172a1013b",
- "env_id": "gcp-dev",
- "env_type": "development",
- "gu_res_id": "7bd3966c9ff8eaa66c5cce855c03d715857c3440",
- "org_id": "test-org",
- "res_id": "modules.my-module.externals.my-db",
- "resource": {
- "host": "127.0.0.1",
- "name": "db_33c7ef9b_8d90-4c62_a1cf_0cdd30fd29a9",
- "port": 5432
}, - "secret_refs": {
- "credentials": "orgs/test-org/resources/7bd3966c9ff8eaa66c5cce855c03d715857c3440/secrets/.credentials"
}, - "type": "postgres",
- "updated_at": "2020-06-23T16:53:12Z"
}
]DriverDefinition describes the resource driver.
Resource Drivers are code that fulfils the Humanitec Resource Driver Interface. This interface allows for certain actions to be performed on resources such as creation and destruction. Humanitec provides numerous Resource Drivers “out of the box”. It is also possible to use 3rd party Resource Drivers or write your own.
| account_types required | Array of strings List of resources accounts types supported by the driver |
| id required | string The ID for this driver. Is used as |
required | object A JSON Schema specifying the driver-specific input parameters. |
| org_id required | string The Organization this driver exists under. Useful as public drivers are accessible to other orgs. |
| target | string The prefix where the driver resides or, if the driver is a virtual driver, the reference to an existing driver using the |
| template | any If the driver is a virtual driver, template defines a Go template that converts the driver inputs supplied in the resource definition into the driver inputs for the target driver. |
| type required | string The type of resource produced by this driver |
{- "account_types": [
- "gcp",
- "aws"
], - "id": "route53",
- "inputs_schema": { },
- "is_public": false,
- "org_id": "test-org",
- "template": "",
- "type": "dns"
}Response samples
- 200
- 500
[- {
- "account_types": [
- "gcp",
- "aws"
], - "id": "route53",
- "inputs_schema": { },
- "is_public": false,
- "org_id": "test-org",
- "template": "",
- "type": "dns"
}
]Register a new Resource Driver.
path Parameters
| orgId required | string The Organization ID. |
Request Body schema: application/json
Resources Driver details.
| account_types required | Array of strings List of resources accounts types supported by the driver |
| id required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ The ID for this driver. Is used as |
required | object A JSON Schema specifying the driver-specific input parameters. |
| target required | string The prefix where the driver resides or, if the driver is a virtual driver, the reference to an existing driver using the |
| template | any If the driver is a virtual driver, template defines a Go template that converts the driver inputs supplied in the resource definition into the driver inputs for the target driver. |
| type required | string The type of resource produced by this driver |
| is_public | boolean Deprecated |
Responses
Request samples
- Payload
{- "account_types": [
- "gcp",
- "aws"
], - "id": "route53",
- "inputs_schema": { },
- "is_public": false,
- "template": "",
- "type": "dns"
}Response samples
- 200
- 400
- 409
- 500
{- "account_types": [
- "gcp",
- "aws"
], - "id": "route53",
- "inputs_schema": { },
- "is_public": false,
- "org_id": "test-org",
- "template": "",
- "type": "dns"
}Get a Resource Driver.
Only drivers that belongs to the given organization or registered as public are accessible through this endpoint
path Parameters
| orgId required | string The Organization ID. |
| driverId required | string The Resource Driver ID. |
Responses
Response samples
- 200
- 404
- 500
{- "account_types": [
- "gcp",
- "aws"
], - "id": "route53",
- "inputs_schema": { },
- "is_public": false,
- "org_id": "test-org",
- "template": "",
- "type": "dns"
}Update a Resource Driver.
path Parameters
| orgId required | string The Organization ID. |
| driverId required | string The Resource Driver ID. |
Request Body schema: application/json
| account_types required | Array of strings List of resources accounts types supported by the driver |
required | object A JSON Schema specifying the driver-specific input parameters. |
| target required | string The prefix where the driver resides or, if the driver is a virtual driver, the reference to an existing driver using the |
| template | any If the driver is a virtual driver, template defines a Go template that converts the driver inputs supplied in the resource definition into the driver inputs for the target driver. |
| type required | string The type of resource produced by this driver |
| is_public | boolean Deprecated |
Responses
Request samples
- Payload
{- "account_types": [
- "gcp",
- "aws"
], - "inputs_schema": { },
- "is_public": false,
- "template": "{{ mustToRawJson .driver }}",
- "type": "dns"
}Response samples
- 200
- 400
- 404
- 500
{- "account_types": [
- "gcp",
- "aws"
], - "id": "route53",
- "inputs_schema": { },
- "is_public": false,
- "org_id": "test-org",
- "template": "",
- "type": "dns"
}Matching Criteria are a set of rules used to choose which Resource Definition to use to provision a particular Resource Type.
Matching criteria are made up in order of specificity with least specific first:
Environment Type (
env_type)Application (
app_id)Environment (
env_id)Resource (
res_id)
When selecting matching criteria, the most specific one is selected. In general, this means of all the Matching Criteria fully matching the context, the Matching Criteria Rule with the most specific element filled is chosen. If there is a tie, the next most specific elements are compared and so on until one is chosen.
NOTE:
Humanitec will reject the registration of matching criteria rules that duplicate rules already present for a Resource Type.
| app_id | string (Optional) The ID of the Application that the Resources should belong to. |
| class required | string (Optional) The class of the Resource in the Deployment Set. Can not be empty, if is not defined, set to |
| env_id | string (Optional) The ID of the Environment that the Resources should belong to. If |
| env_type | string (Optional) The Type of the Environment that the Resources should belong to. If |
| id required | string Matching Criteria ID |
| res_id | string (Optional) The ID of the Resource in the Deployment Set. The ID is normally a |
{- "app_id": "string",
- "class": "string",
- "env_id": "string",
- "env_type": "string",
- "id": "string",
- "res_id": "string"
}Update all Matching Criteria of a Resource Definition.
Matching Criteria are combined with Resource Type to select a specific definition. Matching Criteria can be set for any combination of Application ID, Environment ID, Environment Type, and Resource ID. In the event of multiple matches, the most specific match is chosen.
For example, given 3 sets of matching criteria for the same type:
1. {"env_type":"test"}
2. {"env_type":"development"}
3. {"env_type":"test", "app_id":"my-app"}
If, a resource of that type was needed in an Application my-app, Environment qa-team with Type test and Resource ID modules.my-module-externals.my-resource, there would be two resource definitions matching the criteria: #1 & #3. Definition #3 will be chosen because its matching criteria is the most specific.
path Parameters
| orgId required | string The Organization ID. |
| defId required | string The Resource Definition ID. |
Request Body schema: application/json
Matching Criteria rules.
| app_id | string (Optional) The ID of the Application that the Resources should belong to. |
| class | string (Optional) The class of the Resource in the Deployment Set. Can not be empty, if is not defined, set to |
| env_id | string (Optional) The ID of the Environment that the Resources should belong to. If |
| env_type | string (Optional) The Type of the Environment that the Resources should belong to. If |
| res_id | string (Optional) The ID of the Resource in the Deployment Set. The ID is normally a |
Responses
Request samples
- Payload
[- {
- "env_id": "production"
}
]Response samples
- 200
- 400
- 404
- 409
- 500
[- {
- "app_id": "string",
- "class": "string",
- "env_id": "string",
- "env_type": "string",
- "id": "string",
- "res_id": "string"
}
]Add a new Matching Criteria to a Resource Definition.
Matching Criteria are combined with Resource Type to select a specific definition. Matching Criteria can be set for any combination of Application ID, Environment ID, Environment Type, and Resource ID. In the event of multiple matches, the most specific match is chosen.
For example, given 3 sets of matching criteria for the same type:
1. {"env_type":"test"}
2. {"env_type":"development"}
3. {"env_type":"test", "app_id":"my-app"}
If, a resource of that type was needed in an Application my-app, Environment qa-team with Type test and Resource ID modules.my-module-externals.my-resource, there would be two resource definitions matching the criteria: #1 & #3. Definition #3 will be chosen because its matching criteria is the most specific.
path Parameters
| orgId required | string The Organization ID. |
| defId required | string The Resource Definition ID. |
Request Body schema: application/json
Matching Criteria rules.
| app_id | string (Optional) The ID of the Application that the Resources should belong to. |
| class | string (Optional) The class of the Resource in the Deployment Set. Can not be empty, if is not defined, set to |
| env_id | string (Optional) The ID of the Environment that the Resources should belong to. If |
| env_type | string (Optional) The Type of the Environment that the Resources should belong to. If |
| res_id | string (Optional) The ID of the Resource in the Deployment Set. The ID is normally a |
Responses
Request samples
- Payload
{- "env_id": "production"
}Response samples
- 200
- 400
- 404
- 409
- 500
{- "app_id": "string",
- "class": "string",
- "env_id": "string",
- "env_type": "string",
- "id": "string",
- "res_id": "string"
}Delete a Matching Criteria from a Resource Definition.
If there are no Active Resources that would match to a different Resource Definition when the current Matching Criteria is deleted, the Matching Criteria is deleted immediately.
If there are Active Resources that would match to a different Resource Definition, the request fails with HTTP status code 409 (Conflict). The response content will list all of affected Active Resources and their new matches.
The request can take an optional force query parameter. If set to true, the Matching Criteria is deleted immediately. Referenced Active Resources would match to a different Resource Definition during the next deployment in the target environment.
path Parameters
| orgId required | string The Organization ID. |
| defId required | string The Resource Definition ID. |
| criteriaId required | string The Matching Criteria ID. |
query Parameters
| force | boolean If set to |
Responses
Response samples
- 404
- 409
- 500
{- "error": "API-000",
- "message": "Could not validate token."
}A Resource Definitions describes how and when a resource should be provisioned. It links a driver (the how) along with a Matching Criteria (the when) to a Resource Type. This allows Humanitec to invoke a particular driver for the required Resource Type in the context of a particular Application and Environment.
The schema for the driver_inputs is defined by the input_schema property on the DriverDefinition identified by the driver_type property.
| created_at required | string <date-time> (Simplified extended ISO format date/time string.) The timestamp of when this record has been created. |
| created_by required | string The user who created this record. |
| updated_at | string <date-time> (Simplified extended ISO format date/time string.) The timestamp of when this record has been updated. |
| updated_by | string The user who updated this record. |
Array of objects (MatchingCriteriaResponse) (Optional) The criteria to use when looking for a Resource Definition during the deployment. | |
| driver_account | string (Optional) Security account required by the driver. |
object (ValuesSecretsRefsResponse) ValuesSecretsRefs stores data that should be passed around split by sensitivity. | |
| driver_type required | string The driver to be used to create the resource. |
| id required | string The Resource Definition ID. |
| active_version_id required | string The active Resource Definition Version ID. |
| is_default required | boolean Indicates this definition is a built-in one (provided by Humanitec). |
| is_deleted required | boolean Indicates if this record has been marked for deletion. The Resource Definition that has been marked for deletion cannot be used to provision new resources. |
| name required | string The display name. |
| org_id required | string The Organization ID. |
object (Optional) A map where the keys are resType#resId (if resId is omitted, the same id of the current resource definition is used) of the resources that should be provisioned when the current resource is provisioned. This also specifies if the resources have a dependency on the current resource. | |
| type required | string The Resource Type. |
{- "created_at": "2020-05-23T12:32:16Z",
- "criteria": [
- {
- "env_type": "development",
- "id": "123456"
}
], - "driver_account": "gcp-dev-cloudsql",
- "driver_inputs": {
- "secret_refs": {
- "credentials": {
- "password": {
- "value": "<secret>"
}, - "user": {
- "ref": "vault/path/to/data/secrets/user",
- "store": "my-external-vault",
- "version": "1"
}
}
}, - "values": {
- "instance": "my-dev-project:my-region:dev-db"
}
}, - "driver_type": "humanitec/postgres-cloudsql",
- "id": "dev-postgres",
- "is_default": false,
- "is_deleted": false,
- "name": "Dev Postgres Instance",
- "org_id": "test-org",
- "provision": {
- "aws-policy": {
- "is_dependent": false,
- "match_dependents": false
}, - "dns#my-dns": { }
}, - "type": "postgres"
}List Resource Definitions.
Filter criteria can be applied to obtain all the resource definitions that could match the filters, grouped by type and sorted by matching rank. Resources marked as deleted are not listed in the response, unless specified via deleted query parameter.
path Parameters
| orgId required | string The Organization ID. |
query Parameters
| app | string (Optional) Filter Resource Definitions that may match a specific Application. |
| env | string (Optional) Filter Resource Definitions that may match a specific Environment. |
| env_type | string (Optional) Filter Resource Definitions that may match a specific Environment Type. |
| res | string (Optional) Filter Resource Definitions that may match a specific Resource. |
| res_type | string (Optional) Filter Resource Definitions that may match a specific Resource Type. |
| class | string (Optional) Filter Resource Definitions that may match a specific Class. |
| deleted | boolean Default: false If returns also resource definitions which has been deleted. |
Responses
Response samples
- 200
- 500
[- {
- "created_at": "2020-05-23T12:32:16Z",
- "criteria": [
- {
- "env_type": "development",
- "id": "123456"
}
], - "driver_account": "gcp-dev-cloudsql",
- "driver_inputs": {
- "secret_refs": {
- "credentials": {
- "password": {
- "value": "<secret>"
}, - "user": {
- "ref": "vault/path/to/data/secrets/user",
- "store": "my-external-vault",
- "version": "1"
}
}
}, - "values": {
- "instance": "my-dev-project:my-region:dev-db"
}
}, - "driver_type": "humanitec/postgres-cloudsql",
- "id": "dev-postgres",
- "is_default": false,
- "is_deleted": false,
- "name": "Dev Postgres Instance",
- "org_id": "test-org",
- "provision": {
- "aws-policy": {
- "is_dependent": false,
- "match_dependents": false
}, - "dns#my-dns": { }
}, - "type": "postgres"
}
]Create a new Resource Definition.
path Parameters
| orgId required | string The Organization ID. |
Request Body schema: application/json
The Resource Definition details.
Array of objects (MatchingCriteriaRuleRequest) (Optional) The criteria to use when looking for a Resource Definition during the deployment. | |
| driver_account | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ (Optional) Security account required by the driver. |
object (ValuesSecretsRefsRequest) ValuesSecretsRefs stores data that should be passed around split by sensitivity. | |
| driver_type required | string The driver to be used to create the resource. |
| id required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ The Resource Definition ID. |
| name required | string The display name. |
object (Optional) A map where the keys are resType#resId (if resId is omitted, the same id of the current resource definition is used) of the resources that should be provisioned when the current resource is provisioned. This also specifies if the resources have a dependency on the current resource. | |
| type required | string The Resource Type. |
Responses
Request samples
- Payload
{- "criteria": [ ],
- "driver_account": "gcp-dev-cloudsql",
- "driver_inputs": {
- "secrets": {
- "dbcredentials": {
- "password": "***",
- "username": "***"
}
}, - "values": {
- "instance": "my-dev-project:my-region:dev-db"
}
}, - "driver_type": "humanitec/cloudsql",
- "id": "dev-postgres",
- "name": "Dev Postgres Instance",
- "provision": {
- "aws-policy": {
- "is_dependent": false
}, - "dns#my-dns": { }
}, - "type": "postgres"
}Response samples
- 200
- 400
- 409
- 500
{- "created_at": "2020-05-23T12:32:16Z",
- "criteria": [
- {
- "env_type": "development",
- "id": "123456"
}
], - "driver_account": "gcp-dev-cloudsql",
- "driver_inputs": {
- "secret_refs": {
- "credentials": {
- "password": {
- "value": "<secret>"
}, - "user": {
- "ref": "vault/path/to/data/secrets/user",
- "store": "my-external-vault",
- "version": "1"
}
}
}, - "values": {
- "instance": "my-dev-project:my-region:dev-db"
}
}, - "driver_type": "humanitec/postgres-cloudsql",
- "id": "dev-postgres",
- "is_default": false,
- "is_deleted": false,
- "name": "Dev Postgres Instance",
- "org_id": "test-org",
- "provision": {
- "aws-policy": {
- "is_dependent": false,
- "match_dependents": false
}, - "dns#my-dns": { }
}, - "type": "postgres"
}Get a Resource Definition.
If the resource is marked as deleted it is not shown in the response, unless specified via deleted query parameter.
path Parameters
| orgId required | string The Organization ID. |
| defId required | string The Resource Definition ID. |
query Parameters
| deleted | boolean Default: false If returns the resource definition even if it has been deleted. |
Responses
Response samples
- 200
- 404
- 500
{- "created_at": "2020-05-23T12:32:16Z",
- "criteria": [
- {
- "env_type": "development",
- "id": "123456"
}
], - "driver_account": "gcp-dev-cloudsql",
- "driver_inputs": {
- "secret_refs": {
- "credentials": {
- "password": {
- "value": "<secret>"
}, - "user": {
- "ref": "vault/path/to/data/secrets/user",
- "store": "my-external-vault",
- "version": "1"
}
}
}, - "values": {
- "instance": "my-dev-project:my-region:dev-db"
}
}, - "driver_type": "humanitec/postgres-cloudsql",
- "id": "dev-postgres",
- "is_default": false,
- "is_deleted": false,
- "name": "Dev Postgres Instance",
- "org_id": "test-org",
- "provision": {
- "aws-policy": {
- "is_dependent": false,
- "match_dependents": false
}, - "dns#my-dns": { }
}, - "type": "postgres"
}Update a Resource Definition.
path Parameters
| orgId required | string The Organization ID. |
| defId required | string The Resource Definition ID. |
Request Body schema: application/json
The Resource Definition record details.
The PUT operation updates a resource definition using the provided payload. An empty driver_account or driver_inputs property will unset the existing values.
If driver_type changes and an Active Resource which uses this Resource Definition exists, the resource provisioned with the previous used driver_type will be deleted. As driver_type can't be empty, an empty driver_type means existing value will be used.
Currently the resource can't be changed.
| driver_type | string (Optional) The driver to be used to create the resource. |
| driver_account | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ (Optional) Security account required by the driver. |
object (ValuesSecretsRefsRequest) ValuesSecretsRefs stores data that should be passed around split by sensitivity. | |
| name required | string The display name. |
object (Optional) A map where the keys are resType#resId (if resId is omitted, the same id of the current resource definition is used) of the resources that should be provisioned when the current resource is provisioned. This also specifies if the resources have a dependency on the current resource or if they have the same dependent resources. | |
| proposed | boolean (Optional) If true, the new definition version should be created as "proposed" version (not active). |
Responses
Request samples
- Payload
{- "driver_type": "humanitec/terraform",
- "driver_account": "gcp-dev-cloudsql",
- "driver_inputs": {
- "secret_refs": {
- "dbcredentials": {
- "password": {
- "ref": "path--to--password",
- "store": "my-store",
- "version": "1"
}, - "username": {
- "value": "***"
}
}
}, - "values": {
- "instance": "my-dev-project:my-region:dev-db"
}
}, - "name": "Dev Postgres Instance",
- "provision": {
- "aws-policy": {
- "is_dependent": false
}, - "dns#my-dns": { }
}
}Response samples
- 200
- 400
- 404
- 500
{- "created_at": "2020-05-23T12:32:16Z",
- "criteria": [
- {
- "env_type": "development",
- "id": "123456"
}
], - "driver_account": "gcp-dev-cloudsql",
- "driver_inputs": {
- "secret_refs": {
- "credentials": {
- "password": {
- "value": "<secret>"
}, - "user": {
- "ref": "vault/path/to/data/secrets/user",
- "store": "my-external-vault",
- "version": "1"
}
}
}, - "values": {
- "instance": "my-dev-project:my-region:dev-db"
}
}, - "driver_type": "humanitec/postgres-cloudsql",
- "id": "dev-postgres",
- "is_default": false,
- "is_deleted": false,
- "name": "Dev Postgres Instance",
- "org_id": "test-org",
- "provision": {
- "aws-policy": {
- "is_dependent": false,
- "match_dependents": false
}, - "dns#my-dns": { }
}, - "type": "postgres"
}Delete a Resource Definition.
If there are no Active Resources provisioned via the current definition, the Resource Definition is deleted immediately.
If there are Active Resources provisioned via the current definition, the request fails. The response will describe the changes to the affected Active Resources if operation is forced.
The request can take an optional force query parameter. If set to true, the current Resource Definition is deleted immediately even if there are Active Resources linked to it.
The Resource Definition that has been marked for deletion cannot be used to provision new resources.
With the next deployment, matching criteria for Resources will be re-evaluated, and current Active Resources for the target environment would be either linked to another matching Resource Definition or decommissioned and created using the new or default Resource Definition (when available).
path Parameters
| orgId required | string The Organization ID. |
| defId required | string The Resource Definition ID. |
query Parameters
| force | boolean If set to |
Responses
Response samples
- 404
- 409
- 500
{- "error": "API-000",
- "message": "Could not validate token."
}Update a Resource Definition.
path Parameters
| orgId required | string The Organization ID. |
| defId required | string The Resource Definition ID. |
Request Body schema: application/json
The Resource Definition record details.
The PATCH operation would change the value of the property if it is included in the request payload JSON, and not null. Missing and null properties are ignored.
For the map properties, such as PatchResourceDefinitionRequest.DriverInputs, the merge operation is applied.
Merge rules are as follows:
If a map property has a value, it is replaced (or added).
If a map property is set to
null, it is removed.If a map property is not included (missing in JSON), it remains unchanged.
| driver_account | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ (Optional) Security account required by the driver. |
object (ValuesSecretsRefsRequest) ValuesSecretsRefs stores data that should be passed around split by sensitivity. | |
| name | string (Optional) Resource display name |
object (Optional) A map where the keys are resType#resId (if resId is omitted, the same id of the current resource definition is used) of the resources that should be provisioned when the current resource is provisioned. This also specifies if the resources have a dependency on the current resource or if they have the same dependent resources. | |
| proposed | boolean (Optional) If true, the new definition version should be created as "proposed" version (not active). |
Responses
Request samples
- Payload
{- "driver_account": "gcp-dev-cloudsql",
- "driver_inputs": {
- "secret_refs": {
- "dbcredentials": {
- "password": {
- "ref": "path--to--password",
- "store": "my-store",
- "version": "1"
}, - "username": {
- "value": "***"
}
}
}, - "values": {
- "instance": "my-dev-project:my-region:dev-db"
}
}, - "provision": {
- "aws-policy": {
- "is_dependent": false
}, - "dns#my-dns": { }
}
}Response samples
- 200
- 400
- 404
- 500
{- "created_at": "2020-05-23T12:32:16Z",
- "criteria": [
- {
- "env_type": "development",
- "id": "123456"
}
], - "driver_account": "gcp-dev-cloudsql",
- "driver_inputs": {
- "secret_refs": {
- "credentials": {
- "password": {
- "value": "<secret>"
}, - "user": {
- "ref": "vault/path/to/data/secrets/user",
- "store": "my-external-vault",
- "version": "1"
}
}
}, - "values": {
- "instance": "my-dev-project:my-region:dev-db"
}
}, - "driver_type": "humanitec/postgres-cloudsql",
- "id": "dev-postgres",
- "is_default": false,
- "is_deleted": false,
- "name": "Dev Postgres Instance",
- "org_id": "test-org",
- "provision": {
- "aws-policy": {
- "is_dependent": false,
- "match_dependents": false
}, - "dns#my-dns": { }
}, - "type": "postgres"
}Update all Matching Criteria of a Resource Definition.
Matching Criteria are combined with Resource Type to select a specific definition. Matching Criteria can be set for any combination of Application ID, Environment ID, Environment Type, and Resource ID. In the event of multiple matches, the most specific match is chosen.
For example, given 3 sets of matching criteria for the same type:
1. {"env_type":"test"}
2. {"env_type":"development"}
3. {"env_type":"test", "app_id":"my-app"}
If, a resource of that type was needed in an Application my-app, Environment qa-team with Type test and Resource ID modules.my-module-externals.my-resource, there would be two resource definitions matching the criteria: #1 & #3. Definition #3 will be chosen because its matching criteria is the most specific.
path Parameters
| orgId required | string The Organization ID. |
| defId required | string The Resource Definition ID. |
Request Body schema: application/json
Matching Criteria rules.
| app_id | string (Optional) The ID of the Application that the Resources should belong to. |
| class | string (Optional) The class of the Resource in the Deployment Set. Can not be empty, if is not defined, set to |
| env_id | string (Optional) The ID of the Environment that the Resources should belong to. If |
| env_type | string (Optional) The Type of the Environment that the Resources should belong to. If |
| res_id | string (Optional) The ID of the Resource in the Deployment Set. The ID is normally a |
Responses
Request samples
- Payload
[- {
- "env_id": "production"
}
]Response samples
- 200
- 400
- 404
- 409
- 500
[- {
- "app_id": "string",
- "class": "string",
- "env_id": "string",
- "env_type": "string",
- "id": "string",
- "res_id": "string"
}
]Add a new Matching Criteria to a Resource Definition.
Matching Criteria are combined with Resource Type to select a specific definition. Matching Criteria can be set for any combination of Application ID, Environment ID, Environment Type, and Resource ID. In the event of multiple matches, the most specific match is chosen.
For example, given 3 sets of matching criteria for the same type:
1. {"env_type":"test"}
2. {"env_type":"development"}
3. {"env_type":"test", "app_id":"my-app"}
If, a resource of that type was needed in an Application my-app, Environment qa-team with Type test and Resource ID modules.my-module-externals.my-resource, there would be two resource definitions matching the criteria: #1 & #3. Definition #3 will be chosen because its matching criteria is the most specific.
path Parameters
| orgId required | string The Organization ID. |
| defId required | string The Resource Definition ID. |
Request Body schema: application/json
Matching Criteria rules.
| app_id | string (Optional) The ID of the Application that the Resources should belong to. |
| class | string (Optional) The class of the Resource in the Deployment Set. Can not be empty, if is not defined, set to |
| env_id | string (Optional) The ID of the Environment that the Resources should belong to. If |
| env_type | string (Optional) The Type of the Environment that the Resources should belong to. If |
| res_id | string (Optional) The ID of the Resource in the Deployment Set. The ID is normally a |
Responses
Request samples
- Payload
{- "env_id": "production"
}Response samples
- 200
- 400
- 404
- 409
- 500
{- "app_id": "string",
- "class": "string",
- "env_id": "string",
- "env_type": "string",
- "id": "string",
- "res_id": "string"
}Delete a Matching Criteria from a Resource Definition.
If there are no Active Resources that would match to a different Resource Definition when the current Matching Criteria is deleted, the Matching Criteria is deleted immediately.
If there are Active Resources that would match to a different Resource Definition, the request fails with HTTP status code 409 (Conflict). The response content will list all of affected Active Resources and their new matches.
The request can take an optional force query parameter. If set to true, the Matching Criteria is deleted immediately. Referenced Active Resources would match to a different Resource Definition during the next deployment in the target environment.
path Parameters
| orgId required | string The Organization ID. |
| defId required | string The Resource Definition ID. |
| criteriaId required | string The Matching Criteria ID. |
query Parameters
| force | boolean If set to |
Responses
Response samples
- 404
- 409
- 500
{- "error": "API-000",
- "message": "Could not validate token."
}List Active Resources provisioned via a specific Resource Definition.
path Parameters
| orgId required | string The Organization ID. |
| defId required | string The Resource Definition ID. |
Responses
Response samples
- 200
- 500
[- {
- "app_id": "test-app",
- "class": "default",
- "def_id": "gcp-dev-postgres",
- "def_version_id": "01234567-89ab-cdef-0123-4567890abcdef",
- "deploy_id": "172a1013b",
- "env_id": "gcp-dev",
- "env_type": "development",
- "gu_res_id": "7bd3966c9ff8eaa66c5cce855c03d715857c3440",
- "org_id": "test-org",
- "res_id": "modules.my-module.externals.my-db",
- "resource": {
- "host": "127.0.0.1",
- "name": "db_33c7ef9b_8d90-4c62_a1cf_0cdd30fd29a9",
- "port": 5432
}, - "secret_refs": {
- "credentials": "orgs/test-org/resources/7bd3966c9ff8eaa66c5cce855c03d715857c3440/secrets/.credentials"
}, - "type": "postgres",
- "updated_at": "2020-06-23T16:53:12Z"
}
]A Resource Definition Version represents a version of a Resource Definition.
| id required | string The Resource Definition Version ID. |
| org_id required | string The Organization ID. |
| def_id required | string The Resource Definition ID. |
| name required | string The display name. |
| type required | string The Resource Type. |
| driver_type required | string The driver to be used to create the resource. |
| driver_account required | string (Optional) Security account required by the driver. |
required | object (ValuesSecretsRefsResponse) ValuesSecretsRefs stores data that should be passed around split by sensitivity. |
required | object (Optional) A map where the keys are resType#resId (if resId is omitted, the same id of the current resource definition is used) of the resources that should be provisioned when the current resource is provisioned. This also specifies if the resources have a dependency on the current resource. |
| action required | string The action that generated the Resource Definition Version. Might be one of |
| archived required | boolean Specifies if the version is archived (i.e. can't be used for a new resource). |
| active required | boolean Specifies if the version is active (i.e. is being used if target version is not specified for a resource or a context). |
| proposed required | boolean Specifies if the version is proposed (i.e. is newer than the active version). |
| created_at required | string <date-time> (Simplified extended ISO format date/time string.) The timestamp of when this record has been created. |
| created_by required | string The user who created this record. |
{- "id": "01234567-89ab-cdef-0123-4567890abcdef",
- "org_id": "test-org",
- "def_id": "dev-postgres",
- "name": "Dev Postgres Instance",
- "type": "postgres",
- "driver_type": "humanitec/postgres-cloudsql",
- "driver_account": "gcp-dev-cloudsql",
- "driver_inputs": {
- "secret_refs": {
- "credentials": {
- "password": {
- "value": "<secret>"
}, - "user": {
- "ref": "vault/path/to/data/secrets/user",
- "store": "my-external-vault",
- "version": "1"
}
}
}, - "values": {
- "instance": "my-dev-project:my-region:dev-db"
}
}, - "provision": {
- "aws-policy": {
- "is_dependent": false,
- "match_dependents": false
}, - "dns#my-dns": { }
}, - "created_at": "2020-05-23T12:32:16Z",
- "action": "created",
- "archived": false,
- "active": true,
- "proposed": false
}Get Versions of a Resource Definition.
First 50 Versions are kept along with all the Versions referenced by an Active Resource.
To obtain Versions of a deleted Resource Definition, the deleted parameter needs to be used.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| defId required | string Example: sample-def The Resource Definition ID. |
query Parameters
| deleted | boolean Default: false Example: deleted=true If to show also deleted records in the response. |
| per_page | integer [ 1 .. 100 ] Default: 50 Example: per_page=50 The maximum number of items to return in a page of results |
| page | string Example: page=AAAAAAAAAA== The page token to request from |
Responses
Response samples
- 200
- 400
- 404
[- {
- "id": "01234567-89ab-cdef-0123-4567890abcdef",
- "org_id": "test-org",
- "def_id": "dev-postgres",
- "name": "Dev Postgres Instance",
- "type": "postgres",
- "driver_type": "humanitec/postgres-cloudsql",
- "driver_account": "gcp-dev-cloudsql",
- "driver_inputs": {
- "secret_refs": {
- "credentials": {
- "password": {
- "value": "<secret>"
}, - "user": {
- "ref": "vault/path/to/data/secrets/user",
- "store": "my-external-vault",
- "version": "1"
}
}
}, - "values": {
- "instance": "my-dev-project:my-region:dev-db"
}
}, - "provision": {
- "aws-policy": {
- "is_dependent": false,
- "match_dependents": false
}, - "dns#my-dns": { }
}, - "created_at": "2020-05-23T12:32:16Z",
- "action": "created",
- "archived": false,
- "active": true,
- "proposed": false
}
]Get a Resource Definition Version.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| defId required | string Example: sample-def The Resource Definition ID. |
| defVersionId required | string Example: 01234567-89ab-cdef-0123-4567890abcdef The Resource Definition Version ID. |
Responses
Response samples
- 200
- 404
{- "id": "01234567-89ab-cdef-0123-4567890abcdef",
- "org_id": "test-org",
- "def_id": "dev-postgres",
- "name": "Dev Postgres Instance",
- "type": "postgres",
- "driver_type": "humanitec/postgres-cloudsql",
- "driver_account": "gcp-dev-cloudsql",
- "driver_inputs": {
- "secret_refs": {
- "credentials": {
- "password": {
- "value": "<secret>"
}, - "user": {
- "ref": "vault/path/to/data/secrets/user",
- "store": "my-external-vault",
- "version": "1"
}
}
}, - "values": {
- "instance": "my-dev-project:my-region:dev-db"
}
}, - "provision": {
- "aws-policy": {
- "is_dependent": false,
- "match_dependents": false
}, - "dns#my-dns": { }
}, - "created_at": "2020-05-23T12:32:16Z",
- "action": "created",
- "archived": false,
- "active": true,
- "proposed": false
}Mark/unmark the Resource Definition Version as archived.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| defId required | string Example: sample-def The Resource Definition ID. |
| defVersionId required | string Example: 01234567-89ab-cdef-0123-4567890abcdef The Resource Definition Version ID. |
Request Body schema: application/json
| archived | boolean Indicates whether to set this version archived or non-archived. Optional, true if not specified. |
Responses
Request samples
- Payload
{- "archive": true
}Response samples
- 400
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}Promote the Resource Definition Version as active.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| defId required | string Example: sample-def The Resource Definition ID. |
| defVersionId required | string Example: 01234567-89ab-cdef-0123-4567890abcdef The Resource Definition Version ID. |
Responses
Response samples
- 400
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}ResourceProvisionRequest is the payload passed to the resource provisioner, specifying the resources to be provisioned.
| class | string (Optional) A resource class |
| id required | string |
object (Optional) The input parameters for the resource passed from the deployment set. | |
| type required | string |
{- "class": "cloudsql",
- "id": "shared.postgres",
- "resource": {
- "host": "127.0.0.1",
- "name": "my-database"
}, - "type": "postgres"
}Lists the resource objects that hold the information needed to provision the resources specified in the request and the resources they depend on. Deprecated
This endpoint is deprecated. Use /orgs/{orgId}/apps/{appId}/envs/{envId}/resources/graphs instead.
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| envId required | string The Environment ID. |
Request Body schema: application/json
Resources to provision.
| class | string (Optional) A resource class |
| id required | string |
object (Optional) The input parameters for the resource passed from the deployment set. | |
| type required | string |
Responses
Request samples
- Payload
[- {
- "class": "cloudsql",
- "id": "shared.postgres",
- "resource": {
- "host": "127.0.0.1",
- "name": "my-database"
}, - "type": "postgres"
}
]Response samples
- 200
- 400
- 500
[- {
- "class": "default",
- "criteria_id": "09876545321",
- "def_id": "dns-res-def",
- "def_version_id": "01234567-89ab-cdef-0123-4567890abcdef",
- "depends_on": [
- "ff09876545321"
], - "driver": {
- "secrets": { },
- "values": {
- "domain": "my-domain"
}
}, - "driver_type": "humanitec/dns-aws-route53",
- "guresid": "1234567890ff",
- "id": "modules.sample-app.my-dns",
- "resource": null,
- "resource_schema": {
- "properties": {
- "host": {
- "type": "string"
}
}, - "type": "object"
}, - "type": "dns"
}
]Create a Dependency Graph which is composed by the resource objects that hold the information needed to provision the resources specified in the request and the resources they depend on.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| envId required | string Example: development The Environment ID |
Request Body schema: application/json
Resources to provision.
| class | string (Optional) A resource class |
| id required | string |
object (Optional) The input parameters for the resource passed from the deployment set. | |
| type required | string |
Responses
Request samples
- Payload
[- {
- "class": "cloudsql",
- "id": "shared.postgres",
- "resource": {
- "host": "127.0.0.1",
- "name": "my-database"
}, - "type": "postgres"
}
]Response samples
- 200
- 400
{- "id": "01234567-89ab-cdef-0123-4567890abcdef",
- "hash": "string",
- "nodes": [
- {
- "class": "default",
- "criteria_id": "09876545321",
- "def_id": "dns-res-def",
- "def_version_id": "01234567-89ab-cdef-0123-4567890abcdef",
- "depends_on": [
- "ff09876545321"
], - "driver": {
- "secrets": { },
- "values": {
- "domain": "my-domain"
}
}, - "driver_type": "humanitec/dns-aws-route53",
- "guresid": "1234567890ff",
- "id": "modules.sample-app.my-dns",
- "resource": null,
- "resource_schema": {
- "properties": {
- "host": {
- "type": "string"
}
}, - "type": "object"
}, - "type": "dns"
}
], - "created_at": "2020-06-22T09:37:23.523Z",
- "used_at": "2020-06-22T09:37:23.523Z"
}Retrieve a Dependency Graph by its ID.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| envId required | string Example: development The Environment ID |
| graphId required | string Example: 01234567-89ab-cdef-0123-4567890abcdef The Dependency Graph ID. |
Responses
Response samples
- 200
- 404
{- "id": "01234567-89ab-cdef-0123-4567890abcdef",
- "hash": "string",
- "nodes": [
- {
- "class": "default",
- "criteria_id": "09876545321",
- "def_id": "dns-res-def",
- "def_version_id": "01234567-89ab-cdef-0123-4567890abcdef",
- "depends_on": [
- "ff09876545321"
], - "driver": {
- "secrets": { },
- "values": {
- "domain": "my-domain"
}
}, - "driver_type": "humanitec/dns-aws-route53",
- "guresid": "1234567890ff",
- "id": "modules.sample-app.my-dns",
- "resource": null,
- "resource_schema": {
- "properties": {
- "host": {
- "type": "string"
}
}, - "type": "object"
}, - "type": "dns"
}
], - "created_at": "2020-06-22T09:37:23.523Z",
- "used_at": "2020-06-22T09:37:23.523Z"
}Resource Account Types define cloud providers or protocols to which a resource account can belong.
| name required | string Display Name. |
| type required | string Unique account type identifier (system-wide, across all organizations). |
object A JSON Schema specifying the type-specific parameters for the account credentials (input). | |
object A JSON Schema specifying the type-specific data of returned account credentials (output). |
{- "name": "GCP",
- "type": "gcp"
}ResourceAccount represents the account being used to access a resource.
Resource Accounts hold credentials that are required to provision and manage resources.
| created_at required | string <date-time> (Simplified extended ISO format date/time string.) The timestamp of when the account was created. |
| created_by required | string The ID of the user who created the account. |
| id required | string Unique identifier for the account (in scope of the organization it belongs to). |
| is_used required | boolean Indicates if this account is being used (referenced) by any resource definition or active resource. |
| name required | string Display name. |
| type required | string The type of the account |
{- "created_at": "2020-05-22T14:58:07Z",
- "created_by": "test-user",
- "id": "gcp-dev-postgres",
- "is_default": false,
- "is_used": true,
- "name": "GCP Dev Postgres",
- "type": "gcp"
}List Resource Accounts in the organization.
path Parameters
| orgId required | string The Organization ID. |
Responses
Response samples
- 200
- 500
[- {
- "created_at": "2020-05-22T14:58:07Z",
- "created_by": "test-user",
- "id": "gcp-dev-postgres",
- "is_default": false,
- "is_used": true,
- "name": "GCP Dev Postgres",
- "type": "gcp"
}
]Create a new Resource Account in the organization.
path Parameters
| orgId required | string The Organization ID. |
query Parameters
| dry_run | boolean Example: dry_run=true Validate the request but do not persist the change. |
| check_credential | boolean Example: check_credential=true Validate that the Account credential authenticates successfully. |
Request Body schema: application/json
required | object Credentials associated with the account. |
| id required | string Unique identifier for the account (in scope of the organization it belongs to). |
| name required | string Display name. |
| type required | string The type of the account |
Responses
Request samples
- Payload
{- "credentials": {
- "password": "***",
- "username": "***"
}, - "id": "gcp-dev-postgres",
- "name": "GCP Dev Postgres",
- "type": "gcp-service-account"
}Response samples
- 200
- 400
- 401
- 409
- 500
{- "created_at": "2020-05-22T14:58:07Z",
- "created_by": "test-user",
- "id": "gcp-dev-postgres",
- "is_default": false,
- "is_used": true,
- "name": "GCP Dev Postgres",
- "type": "gcp"
}Get a Resource Account.
path Parameters
| orgId required | string The Organization ID. |
| accId required | string The Resource Account ID. |
Responses
Response samples
- 200
- 404
- 500
{- "created_at": "2020-05-22T14:58:07Z",
- "created_by": "test-user",
- "id": "gcp-dev-postgres",
- "is_default": false,
- "is_used": true,
- "name": "GCP Dev Postgres",
- "type": "gcp"
}Delete an unused Resource Account.
A Resource Account can be deleted if it is not referenced or referenced only by deleted Resource Definitions. Resource Definition Versions which reference the deleted Resource Account cannot be used in deployments.
path Parameters
| orgId required | string The Organization ID. |
| accId required | string The Resource Account ID. |
Responses
Response samples
- 400
- 404
- 500
{- "details": {
- "referencing_resources": {
- "resource_definitions": [
- {
- "created_at": "2020-05-23T12:32:16Z",
- "criteria": [
- {
- "env_type": "development",
- "id": "123456"
}
], - "driver_account": "gcp-dev-cloudsql",
- "driver_inputs": {
- "secret_refs": {
- "credentials": {
- "password": {
- "value": "<secret>"
}, - "user": {
- "ref": "vault/path/to/data/secrets/user",
- "store": "my-external-vault",
- "version": "1"
}
}
}, - "values": {
- "instance": "my-dev-project:my-region:dev-db"
}
}, - "driver_type": "humanitec/postgres-cloudsql",
- "id": "dev-postgres",
- "is_default": false,
- "is_deleted": false,
- "name": "Dev Postgres Instance",
- "org_id": "test-org",
- "provision": {
- "aws-policy": {
- "is_dependent": false,
- "match_dependents": false
}, - "dns#my-dns": { }
}, - "type": "postgres"
}
], - "active_resources": [
- {
- "app_id": "test-app",
- "class": "default",
- "def_id": "gcp-dev-postgres",
- "def_version_id": "01234567-89ab-cdef-0123-4567890abcdef",
- "deploy_id": "172a1013b",
- "env_id": "gcp-dev",
- "env_type": "development",
- "gu_res_id": "7bd3966c9ff8eaa66c5cce855c03d715857c3440",
- "org_id": "test-org",
- "res_id": "modules.my-module.externals.my-db",
- "resource": {
- "host": "127.0.0.1",
- "name": "db_33c7ef9b_8d90-4c62_a1cf_0cdd30fd29a9",
- "port": 5432
}, - "secret_refs": {
- "credentials": "orgs/test-org/resources/7bd3966c9ff8eaa66c5cce855c03d715857c3440/secrets/.credentials"
}, - "type": "postgres",
- "updated_at": "2020-06-23T16:53:12Z"
}
]
}
}, - "error": "string",
- "message": "string"
}Update a Resource Account.
path Parameters
| orgId required | string The Organization ID. |
| accId required | string The Resource Account ID. |
query Parameters
| dry_run | boolean Example: dry_run=true Validate the request but do not persist the change. |
| check_credential | boolean Example: check_credential=true Validate that the Account credential authenticates successfully. |
Request Body schema: application/json
object Credentials associated with the account. | |
| name | string Display name. |
Responses
Request samples
- Payload
{- "credentials": {
- "password": "***",
- "username": "***"
}, - "name": "GCP Dev Postgres"
}Response samples
- 200
- 400
- 404
- 500
{- "created_at": "2020-05-22T14:58:07Z",
- "created_by": "test-user",
- "id": "gcp-dev-postgres",
- "is_default": false,
- "is_used": true,
- "name": "GCP Dev Postgres",
- "type": "gcp"
}Check the credentials of an existing Resource Account
Check the validity of a Resource Account and return any problems that may cause it to not work as expected.
path Parameters
| orgId required | string The Organization ID. |
| accId required | string The Resource Account ID. |
Responses
Response samples
- 200
- 400
{- "identity_fields": [
- {
- "id": "string",
- "description": "string",
- "value": "string"
}
], - "warnings": [
- "string"
]
}Resources Types define the technology that Applications can have dependencies on.
Each Resource Type also defines a set of input parameters (inputs_schema), and a set of output data (outputs_schema). When provisioning a resource, these are treated as inputs and outputs respectively.
| category | string Category name (used to group similar resources on the UI). |
object A JSON Schema specifying the type-specific parameters for the driver (input). | |
| name | string Display name. |
object A JSON Schema specifying the type-specific data passed to the deployment (output). | |
| type required | string Unique resource type identifier (system-wide, across all organizations). It should start with the Humanitec Organization ID followed by "/". |
| use required | string Kind of dependency between resource of this type and a workload. It should be one of: |
{- "inputs_schema": {
- "values": {
- "properties": {
- "extensions": {
- "additionalProperties": {
- "properties": {
- "schema": {
- "type": "string"
}, - "version": {
- "type": "string"
}
}, - "type": "object"
}
}
}, - "type": "object"
}
}, - "name": "PostgreSQL",
- "outputs_schema": {
- "secrets": {
- "properties": {
- "password": {
- "type": "string"
}, - "username": {
- "type": "string"
}
}, - "required": [
- "username",
- "password"
], - "type": "object"
}, - "values": {
- "properties": {
- "host": {
- "type": "string"
}, - "name": {
- "type": "string"
}, - "port": {
- "maximum": 65535,
- "minimum": 0,
- "type": "integer"
}
}, - "required": [
- "name",
- "host",
- "port"
], - "type": "object"
}
}, - "type": "my-org/postgres",
- "use": "direct"
}Response samples
- 200
- 500
[- {
- "inputs_schema": {
- "values": {
- "properties": {
- "extensions": {
- "additionalProperties": {
- "properties": {
- "schema": {
- "type": "string"
}, - "version": {
- "type": "string"
}
}, - "type": "object"
}
}
}, - "type": "object"
}
}, - "name": "PostgreSQL",
- "outputs_schema": {
- "secrets": {
- "properties": {
- "password": {
- "type": "string"
}, - "username": {
- "type": "string"
}
}, - "required": [
- "username",
- "password"
], - "type": "object"
}, - "values": {
- "properties": {
- "host": {
- "type": "string"
}, - "name": {
- "type": "string"
}, - "port": {
- "maximum": 65535,
- "minimum": 0,
- "type": "integer"
}
}, - "required": [
- "name",
- "host",
- "port"
], - "type": "object"
}
}, - "type": "postgres",
- "use": "direct"
}
]Creates a new resources class.
path Parameters
| orgId required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ The organization ID. |
| typeId required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ The resource type. |
Request Body schema: application/json
| id required | string [ 2 .. 63 ] characters ^[a-z0-9][a-z0-9-]*[a-z0-9]$ ID of the resource class. |
| description required | string [ 0 .. 1024 ] characters A human readable description when this class should be used. |
Responses
Request samples
- Payload
{- "id": "string",
- "description": "string"
}Response samples
- 200
- 400
- 409
{- "id": "string",
- "resource_type": "string",
- "description": "string",
- "created_by": "string",
- "created_at": "2019-08-24T14:15:22Z"
}Get resource class by ID.
path Parameters
| orgId required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ The organization ID. |
| typeId required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ The resource type. |
| classId required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ The resource class ID. |
Responses
Response samples
- 200
- 404
{- "id": "string",
- "resource_type": "string",
- "description": "string",
- "created_by": "string",
- "created_at": "2019-08-24T14:15:22Z"
}Update a resource class description.
path Parameters
| orgId required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ The organization ID. |
| typeId required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ The resource type ID. |
| classId required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ The resource class ID. |
Request Body schema: application/json
| description required | string [ 0 .. 1024 ] characters New description for the resource class. |
Responses
Request samples
- Payload
{- "description": "string"
}Response samples
- 200
- 404
{- "id": "string",
- "resource_type": "string",
- "description": "string",
- "created_by": "string",
- "created_at": "2019-08-24T14:15:22Z"
}Delete a resource class.
path Parameters
| orgId required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ The organization ID. |
| typeId required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ The resource type. |
| classId required | string^[a-z0-9][a-z0-9-]+[a-z0-9]$ The resource class id. |
Responses
Response samples
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}An Automation Rule defining how and when artefacts in an environment should be updated.
| active | boolean Whether the rule will be processed or not. |
| artefacts_filter | Array of strings A list of artefact names to be processed by the rule. If the array is empty, it implies include all. If |
| exclude_artefacts_filter | boolean Whether the artefacts specified in |
| exclude_images_filter | boolean Deprecated DEPRECATED: Whether the images specified in |
| images_filter | Array of strings Deprecated DEPRECATED: A list of image IDs to be processed by the rule. If the array is empty, it implies include all. If |
| match | string Deprecated DEPRECATED: A regular expression applied to the branch or tag name depending on the value of |
| match_ref | string A regular expression applied to the ref of a new artefact version. Defaults to match all if omitted or empty. |
| type required | string^(?:update)$ Specifies the type of event. Currently, only updates to either branches or tags are supported. Must be |
| update_to | string^(?:branch|tag)$ Deprecated DEPRECATED: Specifies whether the update occurs on commit to branch or creation of tag. Must be one of |
{- "active": true,
- "exclude_artefacts_filter": false,
- "exclude_images_filter": false,
- "images_filter": [
- "sample-service"
], - "match": "^pr-[0-9]+-.*$",
- "match_ref": "^refs/heads/pr-[0-9]+-.*$",
- "type": "update",
- "update_to": "branch"
}List all Automation Rules in an Environment.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| envId required | string Example: development The Environment ID |
Responses
Response samples
- 200
[- {
- "active": true,
- "created_at": "2020-06-22T09:37:23.523Z",
- "exclude_artefacts_filter": false,
- "exclude_images_filter": false,
- "id": "923486d012f20324",
- "images_filter": [
- "sample-service"
], - "match": "^pr-[0-9]+-.*$",
- "match_ref": "^refs/heads/pr-[0-9]+-.*$",
- "type": "update",
- "update_to": "branch",
- "updated_at": "2020-06-22T09:37:23.523Z"
}
]Create a new Automation Rule for an Environment.
Items marked as deprecated are still supported (however not recommended) for use and are incompatible with properties of the latest api version. In particular an error is raised if images_filter (deprecated) and artefacts_filter are used in the same payload. The same is true for exclude_images_filter (deprecated) and exclude_artefacts_filter. match and update_to are still supported but will trigger an error if combined with match_ref.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| envId required | string Example: development The Environment ID |
Request Body schema: application/json
The definition of the Automation Rule.
| active | boolean Whether the rule will be processed or not. |
| artefacts_filter | Array of strings A list of artefact names to be processed by the rule. If the array is empty, it implies include all. If |
| exclude_artefacts_filter | boolean Whether the artefacts specified in |
| exclude_images_filter | boolean Deprecated DEPRECATED: Whether the images specified in |
| images_filter | Array of strings Deprecated DEPRECATED: A list of image IDs to be processed by the rule. If the array is empty, it implies include all. If |
| match | string Deprecated DEPRECATED: A regular expression applied to the branch or tag name depending on the value of |
| match_ref | string A regular expression applied to the ref of a new artefact version. Defaults to match all if omitted or empty. |
| type required | string^(?:update)$ Specifies the type of event. Currently, only updates to either branches or tags are supported. Must be |
| update_to | string^(?:branch|tag)$ Deprecated DEPRECATED: Specifies whether the update occurs on commit to branch or creation of tag. Must be one of |
Responses
Request samples
- Payload
{- "active": true,
- "exclude_artefacts_filter": false,
- "exclude_images_filter": false,
- "images_filter": [
- "sample-service"
], - "match": "^pr-[0-9]+-.*$",
- "match_ref": "^refs/heads/pr-[0-9]+-.*$",
- "type": "update",
- "update_to": "branch"
}Response samples
- 201
- 400
- 409
- 422
{- "active": true,
- "created_at": "2020-06-22T09:37:23.523Z",
- "exclude_artefacts_filter": false,
- "exclude_images_filter": false,
- "id": "923486d012f20324",
- "images_filter": [
- "sample-service"
], - "match": "^pr-[0-9]+-.*$",
- "match_ref": "^refs/heads/pr-[0-9]+-.*$",
- "type": "update",
- "update_to": "branch",
- "updated_at": "2020-06-22T09:37:23.523Z"
}Get a specific Automation Rule for an Environment.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| envId required | string Example: development The Environment ID |
| ruleId required | string The Automation Rule ID. |
Responses
Response samples
- 200
- 404
{- "active": true,
- "created_at": "2020-06-22T09:37:23.523Z",
- "exclude_artefacts_filter": false,
- "exclude_images_filter": false,
- "id": "923486d012f20324",
- "images_filter": [
- "sample-service"
], - "match": "^pr-[0-9]+-.*$",
- "match_ref": "^refs/heads/pr-[0-9]+-.*$",
- "type": "update",
- "update_to": "branch",
- "updated_at": "2020-06-22T09:37:23.523Z"
}Update an existing Automation Rule for an Environment.
Items marked as deprecated are still supported (however not recommended) for use and are incompatible with properties of the latest api version. In particular an error is raised if images_filter (deprecated) and artefacts_filter are used in the same payload. The same is true for exclude_images_filter (deprecated) and exclude_artefacts_filter. match and update_to are still supported but will trigger an error if combined with match_ref.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| envId required | string Example: development The Environment ID |
| ruleId required | string The Automation Rule ID. |
Request Body schema: application/json
The definition of the Automation Rule.
| active | boolean Whether the rule will be processed or not. |
| artefacts_filter | Array of strings A list of artefact names to be processed by the rule. If the array is empty, it implies include all. If |
| exclude_artefacts_filter | boolean Whether the artefacts specified in |
| exclude_images_filter | boolean Deprecated DEPRECATED: Whether the images specified in |
| images_filter | Array of strings Deprecated DEPRECATED: A list of image IDs to be processed by the rule. If the array is empty, it implies include all. If |
| match | string Deprecated DEPRECATED: A regular expression applied to the branch or tag name depending on the value of |
| match_ref | string A regular expression applied to the ref of a new artefact version. Defaults to match all if omitted or empty. |
| type required | string^(?:update)$ Specifies the type of event. Currently, only updates to either branches or tags are supported. Must be |
| update_to | string^(?:branch|tag)$ Deprecated DEPRECATED: Specifies whether the update occurs on commit to branch or creation of tag. Must be one of |
Responses
Request samples
- Payload
{- "active": true,
- "exclude_artefacts_filter": false,
- "exclude_images_filter": false,
- "images_filter": [
- "sample-service"
], - "match": "^pr-[0-9]+-.*$",
- "match_ref": "^refs/heads/pr-[0-9]+-.*$",
- "type": "update",
- "update_to": "branch"
}Response samples
- 200
- 400
- 404
- 422
{- "active": true,
- "created_at": "2020-06-22T09:37:23.523Z",
- "exclude_artefacts_filter": false,
- "exclude_images_filter": false,
- "id": "923486d012f20324",
- "images_filter": [
- "sample-service"
], - "match": "^pr-[0-9]+-.*$",
- "match_ref": "^refs/heads/pr-[0-9]+-.*$",
- "type": "update",
- "update_to": "branch",
- "updated_at": "2020-06-22T09:37:23.523Z"
}Delete Automation Rule from an Environment.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| envId required | string Example: development The Environment ID |
| ruleId required | string The Automation Rule ID. |
Responses
Response samples
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}Webhook is a special type of a Job. It performs an HTTPS request to a specified URL with specified headers.
| disabled | boolean or null Defines whether this job is currently disabled. |
object (JSONFieldRequest) | |
| id | string Job ID, unique within the Organization |
object (JSONFieldRequest) | |
Array of objects (EventBaseRequest) A list of Events by which the Job is triggered | |
| url | string or null The webhook's URL (without protocol, only HTTPS is supported). |
{- "disabled": true,
- "headers": {
- "property1": null,
- "property2": null
}, - "id": "string",
- "payload": {
- "property1": null,
- "property2": null
}, - "triggers": [
- {
- "scope": "string",
- "type": "string"
}
], - "url": "string"
}List Webhooks
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
Responses
Response samples
- 200
[- {
- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "disabled": true,
- "headers": {
- "property1": null,
- "property2": null
}, - "id": "string",
- "payload": {
- "property1": null,
- "property2": null
}, - "triggers": [
- {
- "scope": "string",
- "type": "string"
}
], - "url": "string"
}
]Create a new Webhook
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
Request Body schema: application/json
| disabled | boolean or null Defines whether this job is currently disabled. |
object (JSONFieldRequest) | |
| id | string Job ID, unique within the Organization |
object (JSONFieldRequest) | |
Array of objects (EventBaseRequest) A list of Events by which the Job is triggered | |
| url | string or null The webhook's URL (without protocol, only HTTPS is supported). |
Responses
Request samples
- Payload
{- "disabled": true,
- "headers": {
- "property1": null,
- "property2": null
}, - "id": "string",
- "payload": {
- "property1": null,
- "property2": null
}, - "triggers": [
- {
- "scope": "string",
- "type": "string"
}
], - "url": "string"
}Response samples
- 201
- 400
- 409
{- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "disabled": true,
- "headers": {
- "property1": null,
- "property2": null
}, - "id": "string",
- "payload": {
- "property1": null,
- "property2": null
}, - "triggers": [
- {
- "scope": "string",
- "type": "string"
}
], - "url": "string"
}Get a Webhook
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| jobId required | string The Webhook ID. |
Responses
Response samples
- 200
- 404
{- "created_at": "2020-06-22T09:37:23.523Z",
- "created_by": "string",
- "disabled": true,
- "headers": {
- "property1": null,
- "property2": null
}, - "id": "string",
- "payload": {
- "property1": null,
- "property2": null
}, - "triggers": [
- {
- "scope": "string",
- "type": "string"
}
], - "url": "string"
}Update a Webhook
path Parameters
| orgId required | string The Organization ID. |
| appId required | string The Application ID. |
| jobId required | string The Webhook ID. |
Request Body schema: application/json
| disabled | boolean or null Defines whether this job is currently disabled. |
object (JSONFieldRequest) | |
| id | string Job ID, unique within the Organization |
object (JSONFieldRequest) | |
Array of objects (EventBaseRequest) A list of Events by which the Job is triggered | |
| url | string or null The webhook's URL (without protocol, only HTTPS is supported). |
Responses
Request samples
- Payload
{- "disabled": true,
- "headers": {
- "property1": null,
- "property2": null
}, - "id": "string",
- "payload": {
- "property1": null,
- "property2": null
}, - "triggers": [
- {
- "scope": "string",
- "type": "string"
}
], - "url": "string"
}Response samples
- 200
- 400
- 404
{- "disabled": true,
- "headers": {
- "property1": null,
- "property2": null
}, - "payload": {
- "property1": null,
- "property2": null
}, - "triggers": [
- {
- "scope": "string",
- "type": "string"
}
], - "url": "string"
}An object containing the details of a Pipeline.
| id required | string The id of the Pipeline. |
| etag required | string The current entity tag value for this Pipeline. |
| org_id required | string The id of the Organization containing this Pipeline. |
| app_id required | string The id of the Application containing this Pipeline. |
| name required | string The name of the Pipeline. |
| status required | string The current status of the Pipeline. |
| version required | string The unique id of the current Pipeline Version. |
| created_at required | string <date-time> The date and time when the Pipeline was created. |
| trigger_types required | Array of strings The list of trigger types in the current schema. |
object The map of key value pipeline additional information |
{- "id": "sample-pipeline",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "name": "Sample Pipeline",
- "status": "active",
- "version": "01234567-89ab-cdef-0123-456789abcdef",
- "created_at": "2023-01-01T00:00:00Z",
- "trigger_types": [
- "pipeline_call"
], - "metadata": {
- "property1": "string",
- "property2": "string"
}
}List all Pipelines within an Organization. This can be filtered by Application.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
query Parameters
| app | Array of strings Example: app=sample-app An optional list of Application IDs. |
| per_page | integer [ 1 .. 100 ] Default: 50 Example: per_page=50 The maximum number of items to return in a page of results |
| page | string Example: page=AAAAAAAAAA== The page token to request from |
| trigger | string Example: trigger=pipeline_call An optional filter by trigger type. |
object Optional filter by pipeline metadata |
Responses
Response samples
- 200
- 400
- 404
[- {
- "id": "sample-pipeline",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "name": "Sample Pipeline",
- "status": "active",
- "version": "01234567-89ab-cdef-0123-456789abcdef",
- "created_at": "2023-01-01T00:00:00Z",
- "trigger_types": [
- "pipeline_call"
], - "metadata": {
- "property1": "string",
- "property2": "string"
}
}
]List Pipelines within an Application.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
query Parameters
| per_page | integer [ 1 .. 100 ] Default: 50 Example: per_page=50 The maximum number of items to return in a page of results |
| page | string Example: page=AAAAAAAAAA== The page token to request from |
| trigger | string Example: trigger=pipeline_call An optional filter by trigger type. |
object Optional filter by pipeline metadata |
Responses
Response samples
- 200
- 400
- 404
[- {
- "id": "sample-pipeline",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "name": "Sample Pipeline",
- "status": "active",
- "version": "01234567-89ab-cdef-0123-456789abcdef",
- "created_at": "2023-01-01T00:00:00Z",
- "trigger_types": [
- "pipeline_call"
], - "metadata": {
- "property1": "string",
- "property2": "string"
}
}
]Create a Pipeline within an Application.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
query Parameters
| dry_run | boolean Optionally validate the request but do not persist the actual Pipeline. |
Request Body schema: application/x-yaml
Responses
Response samples
- 201
- 400
- 404
- 409
{- "id": "sample-pipeline",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "name": "Sample Pipeline",
- "status": "active",
- "version": "01234567-89ab-cdef-0123-456789abcdef",
- "created_at": "2023-01-01T00:00:00Z",
- "trigger_types": [
- "pipeline_call"
], - "metadata": {
- "property1": "string",
- "property2": "string"
}
}Get a Pipeline within an Application.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
query Parameters
| version | string Example: version=01234567-89ab-cdef-0123-456789abcdef An optional Pipeline Version ID. |
Responses
Response samples
- 200
- 400
- 404
{- "id": "sample-pipeline",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "name": "Sample Pipeline",
- "status": "active",
- "version": "01234567-89ab-cdef-0123-456789abcdef",
- "created_at": "2023-01-01T00:00:00Z",
- "trigger_types": [
- "pipeline_call"
], - "metadata": {
- "property1": "string",
- "property2": "string"
}
}update a Pipeline within an Application.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
query Parameters
| dry_run | boolean Optionally validate the request but do not persist the update. |
header Parameters
| If-Match | string Example: 1234567890abcdef Indicate that the request should only succeed if there is an etag match |
Request Body schema: application/x-yaml
Responses
Response samples
- 200
- 400
- 404
- 409
- 412
{- "id": "sample-pipeline",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "name": "Sample Pipeline",
- "status": "active",
- "version": "01234567-89ab-cdef-0123-456789abcdef",
- "created_at": "2023-01-01T00:00:00Z",
- "trigger_types": [
- "pipeline_call"
], - "metadata": {
- "property1": "string",
- "property2": "string"
}
}Delete a pipeline within an application.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
header Parameters
| If-Match | string Example: 1234567890abcdef Indicate that the request should only succeed if there is an etag match |
Responses
Response samples
- 400
- 404
- 409
- 412
{- "error": "API-000",
- "message": "Could not validate token."
}List all versions of the pipeline
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
query Parameters
| per_page | integer [ 1 .. 100 ] Default: 50 Example: per_page=50 The maximum number of items to return in a page of results |
| page | string Example: page=AAAAAAAAAA== The page token to request from |
Responses
Response samples
- 200
- 400
- 404
[- {
- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "pipeline_id": "sample-pipeline",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "created_at": "2023-01-01T00:00:00Z"
}
]Get a pipeline schema.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
query Parameters
| version | string Example: version=01234567-89ab-cdef-0123-456789abcdef An optional Pipeline Version ID. |
header Parameters
| Accept | string |
Responses
Response samples
- 200
- 400
- 404
List the trigger matching criteria defined for Pipelines in this Application.
Lists the trigger matching criteria defined for Pipelines in this Application. Trigger matching criteria link requests in an environment to the appropriate Pipeline based on the trigger and inputs.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
query Parameters
| pipeline | string Example: pipeline=sample-pipeline An optional filter by Pipeline ID. |
object Example: match[env_type]=development Optional key value match filters on the criteria. | |
| per_page | integer [ 1 .. 100 ] Default: 50 Example: per_page=50 The maximum number of items to return in a page of results |
| page | string Example: page=AAAAAAAAAA== The page token to request from |
Responses
Response samples
- 200
- 400
[- {
- "trigger": "deployment_request",
- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "pipeline_id": "sample-pipeline",
- "pipeline_name": "Sample Pipeline",
- "env_type": "development",
- "app_id": "my-application",
- "env_id": "my-environment",
- "deployment_type": "deploy"
}
]Create a new trigger matching criteria for this Pipeline.
Create a new trigger matching criteria for this Pipeline. This must not conflict with an existing criteria for the same trigger on this or any other Pipeline that applies to this Application.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
Request Body schema: application/json
| env_type | string The Environment Type that this criteria will match. If defined, this criteria will only apply to Environments that have this type. |
| app_id | string The id of the Application for which this criteria matches. If this Pipeline is defined in an Application, then this value can only be null or the id of the Application. |
| env_id | string The exact id of the Environment which this criteria will match. |
| deployment_type | string The type of deployment that this criteria will match. Valid values are "deploy" and "redeploy". "redeploy" applies only to deployment request to redeploy a previous deployment id while "deploy" will apply to all other requests that include a Delta or Deployment Set. If not defined, all deployment types will match. |
Responses
Request samples
- Payload
{- "env_type": "development",
- "app_id": "my-application",
- "env_id": "my-environment",
- "deployment_type": "deploy",
- "trigger": "deployment_request"
}Response samples
- 201
- 400
- 404
- 409
{- "trigger": "deployment_request",
- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "pipeline_id": "sample-pipeline",
- "pipeline_name": "Sample Pipeline",
- "env_type": "development",
- "app_id": "my-application",
- "env_id": "my-environment",
- "deployment_type": "deploy"
}Get the Pipeline Criteria with the given id.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
| criteriaId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Criteria ID |
Responses
Response samples
- 200
- 400
- 404
{- "trigger": "deployment_request",
- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "pipeline_id": "sample-pipeline",
- "pipeline_name": "Sample Pipeline",
- "env_type": "development",
- "app_id": "my-application",
- "env_id": "my-environment",
- "deployment_type": "deploy"
}Delete the Pipeline Criteria with the given id.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
| criteriaId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Criteria ID |
Responses
Response samples
- 400
- 404
{- "error": "API-000",
- "message": "Could not validate token."
}Read the current state of a trigger batch
Read the current state of a trigger batch for a Pipeline if one exists
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
| batchType required | string Example: artefact The batch type, only artefact is implemented. |
Responses
Response samples
- 200
- 404
{- "items": [
- {
- "type": "string",
- "ref": "string"
}
], - "scheduled_at": "2019-08-24T14:15:22Z"
}Details of a Run within the Pipeline.
| id required | string The unique id of the Run. |
| etag required | string The current entity tag value for this Run. |
| org_id required | string The id of the Organization containing this Run. |
| app_id required | string The id of the Application containing this Run. |
| env_ids required | Array of strings Environments linked to this Pipeline Run through input parameters or step executions. |
| pipeline_id required | string The id of the Pipeline associated with the Run. |
| pipeline_version required | string The id of the Pipeline Version associated with the Run. |
| status required | string The current status of this Run. |
| status_message required | string A human-readable message indicating the reason for the status. |
| created_at required | string <date-time> The date and time when this Run was first created. |
| created_by required | string User id that created or triggered the Run. |
| executing_at | string <date-time> The date and time when this Run entered executing status. |
| cancellation_requested_at | string <date-time> The date and time when cancellation of this Run was requested. |
| completed_at | string <date-time> The date and time when this Run entered a successful, failed, or cancelled status. |
| timeout_seconds required | integer The timeout for this Run. |
| trigger required | string The trigger type that was triggered this Run to start. |
required | object The inputs that were provided for this Run. |
| run_as required | string The user id that the pipeline run is executing as when it calls Humanitec APIs. |
| concurrency_group | string The optional concurrency group for this run within the application |
required | object Aggregated events on which run's jobs are waiting for |
{- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "env_ids": [
- "development"
], - "pipeline_id": "sample-pipeline",
- "pipeline_version": "01234567-89ab-cdef-0123-456789abcdef",
- "status": "executing",
- "status_message": "Example text",
- "created_at": "2023-01-01T00:00:00Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "executing_at": "2023-01-01T00:00:00Z",
- "cancellation_requested_at": "2023-01-01T00:00:00Z",
- "completed_at": "2023-01-01T00:00:00Z",
- "timeout_seconds": 3600,
- "trigger": "pipeline_call",
- "inputs": {
- "fizz": "buzz"
}, - "run_as": "s-01234567-89ab-cdef-0123-456789abcdef",
- "concurrency_group": "my-group",
- "waiting_for": {
- "property1": "string",
- "property2": "string"
}
}List all pipeline runs within the Org. This can be filtered by app, pipeline, and status.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
query Parameters
| app | Array of strings Example: app=sample-app An optional list of Application IDs. |
| pipeline | Array of strings Example: pipeline=sample-pipeline An optional list of Pipeline IDs. |
| env | string Example: env=development An optional Environment ID |
| status | Array of strings Example: status=executing Optional filter by status. |
| completed | boolean Example: completed=true Optional filer by completed or not. |
| created_after | string <date-time> Example: created_after=2018-03-20T09:12:28Z Optional filter by creation after date time. |
| created_before | string <date-time> Example: created_before=2018-03-20T09:12:28Z Optional filter by creation before date time |
| per_page | integer [ 1 .. 100 ] Default: 50 Example: per_page=50 The maximum number of items to return in a page of results |
| page | string Example: page=AAAAAAAAAA== The page token to request from |
Responses
Response samples
- 200
- 400
- 404
[- {
- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "env_ids": [
- "development"
], - "pipeline_id": "sample-pipeline",
- "pipeline_version": "01234567-89ab-cdef-0123-456789abcdef",
- "status": "executing",
- "status_message": "Example text",
- "created_at": "2023-01-01T00:00:00Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "executing_at": "2023-01-01T00:00:00Z",
- "cancellation_requested_at": "2023-01-01T00:00:00Z",
- "completed_at": "2023-01-01T00:00:00Z",
- "timeout_seconds": 3600,
- "trigger": "pipeline_call",
- "inputs": {
- "fizz": "buzz"
}, - "run_as": "s-01234567-89ab-cdef-0123-456789abcdef",
- "concurrency_group": "my-group",
- "waiting_for": {
- "property1": "string",
- "property2": "string"
}
}
]Create a Pipeline Run in the appropriate Pipeline based on the trigger and inputs.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
query Parameters
| dry_run | boolean Optionally validate the request but do not persist the actual Pipeline Run. |
header Parameters
| Idempotency-Key | string Example: 0xr$P0Cu4@DB The HTTP Idempotency-Key |
Request Body schema: application/json
| env_id | string The target environment within the Application to deploy to. |
| environment | string Deprecated The target environment within the Application to deploy to. |
| delta_id | string A deployment delta to apply to the target environment. This delta must already exist. This field is mutually exclusive with "deployment_id" and "set_id". |
| deployment_id | string An existing deployment to redeploy into the target environment. The deployment set and value set will be copied. This field is mutually exclusive with "delta_id" and "set_id". |
| set_id | string A direct deployment set to apply to the target environment. This deployment set must already exist. This field is mutually exclusive with "delta_id" and "set_id". |
| value_set_version_id | string The exact value set version to use when deploying to the target environment. This value set version must exist. This field can only be used when "delta_id" or "set_id" is specified. |
| comment | string An optional comment to apply to the Deployment. |
Responses
Request samples
- Payload
{- "trigger": "deployment_request",
- "env_id": "development",
- "delta_id": "0123456789abcdef0123456789abcdef01234567",
- "comment": "My deployment"
}Response samples
- 201
- 400
- 404
- 409
- 422
{- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "env_ids": [
- "development"
], - "pipeline_id": "sample-pipeline",
- "pipeline_version": "01234567-89ab-cdef-0123-456789abcdef",
- "status": "executing",
- "status_message": "Example text",
- "created_at": "2023-01-01T00:00:00Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "executing_at": "2023-01-01T00:00:00Z",
- "cancellation_requested_at": "2023-01-01T00:00:00Z",
- "completed_at": "2023-01-01T00:00:00Z",
- "timeout_seconds": 3600,
- "trigger": "pipeline_call",
- "inputs": {
- "fizz": "buzz"
}, - "run_as": "s-01234567-89ab-cdef-0123-456789abcdef",
- "concurrency_group": "my-group",
- "waiting_for": {
- "property1": "string",
- "property2": "string"
}
}List runs within a pipeline.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
query Parameters
| env | string Example: env=development An optional Environment ID |
| status | Array of strings Example: status=executing Optional filter by status. |
| completed | boolean Example: completed=true Optional filer by completed or not. |
| created_after | string <date-time> Example: created_after=2018-03-20T09:12:28Z Optional filter by creation after date time. |
| created_before | string <date-time> Example: created_before=2018-03-20T09:12:28Z Optional filter by creation before date time |
| per_page | integer [ 1 .. 100 ] Default: 50 Example: per_page=50 The maximum number of items to return in a page of results |
| page | string Example: page=AAAAAAAAAA== The page token to request from |
Responses
Response samples
- 200
- 400
- 404
[- {
- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "env_ids": [
- "development"
], - "pipeline_id": "sample-pipeline",
- "pipeline_version": "01234567-89ab-cdef-0123-456789abcdef",
- "status": "executing",
- "status_message": "Example text",
- "created_at": "2023-01-01T00:00:00Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "executing_at": "2023-01-01T00:00:00Z",
- "cancellation_requested_at": "2023-01-01T00:00:00Z",
- "completed_at": "2023-01-01T00:00:00Z",
- "timeout_seconds": 3600,
- "trigger": "pipeline_call",
- "inputs": {
- "fizz": "buzz"
}, - "run_as": "s-01234567-89ab-cdef-0123-456789abcdef",
- "concurrency_group": "my-group",
- "waiting_for": {
- "property1": "string",
- "property2": "string"
}
}
]Create a run within a pipeline.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
query Parameters
| dry_run | boolean Optionally validate the request but do not persist the actual Pipeline Run. |
header Parameters
| Idempotency-Key | string Example: 0xr$P0Cu4@DB The HTTP Idempotency-Key |
Request Body schema: application/json
required | object The inputs provided for this Run. |
Responses
Request samples
- Payload
{- "inputs": {
- "fizz": "buzz"
}
}Response samples
- 201
- 400
- 404
- 409
- 422
{- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "env_ids": [
- "development"
], - "pipeline_id": "sample-pipeline",
- "pipeline_version": "01234567-89ab-cdef-0123-456789abcdef",
- "status": "executing",
- "status_message": "Example text",
- "created_at": "2023-01-01T00:00:00Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "executing_at": "2023-01-01T00:00:00Z",
- "cancellation_requested_at": "2023-01-01T00:00:00Z",
- "completed_at": "2023-01-01T00:00:00Z",
- "timeout_seconds": 3600,
- "trigger": "pipeline_call",
- "inputs": {
- "fizz": "buzz"
}, - "run_as": "s-01234567-89ab-cdef-0123-456789abcdef",
- "concurrency_group": "my-group",
- "waiting_for": {
- "property1": "string",
- "property2": "string"
}
}Get a run within an pipeline.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
| runId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Run ID |
Responses
Response samples
- 200
- 404
{- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "env_ids": [
- "development"
], - "pipeline_id": "sample-pipeline",
- "pipeline_version": "01234567-89ab-cdef-0123-456789abcdef",
- "status": "executing",
- "status_message": "Example text",
- "created_at": "2023-01-01T00:00:00Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "executing_at": "2023-01-01T00:00:00Z",
- "cancellation_requested_at": "2023-01-01T00:00:00Z",
- "completed_at": "2023-01-01T00:00:00Z",
- "timeout_seconds": 3600,
- "trigger": "pipeline_call",
- "inputs": {
- "fizz": "buzz"
}, - "run_as": "s-01234567-89ab-cdef-0123-456789abcdef",
- "concurrency_group": "my-group",
- "waiting_for": {
- "property1": "string",
- "property2": "string"
}
}Deleting a completed Run within a Pipeline.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
| runId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Run ID |
header Parameters
| If-Match | string Example: 1234567890abcdef Indicate that the request should only succeed if there is an etag match |
Responses
Response samples
- 400
- 404
- 409
- 412
{- "error": "API-000",
- "message": "Could not validate token."
}Cancel a Run within an Pipeline.
Attempts to cancel the specified Run. If the Run is in a queued state, this cancellation will be applied immediately. If the Run is executing, the cancellation will be stored and will be resolved by the next Job or Step that supports in-flight cancellation. Runs that are in any other state, are not cancellable.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
| runId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Run ID |
header Parameters
| If-Match | string Example: 1234567890abcdef Indicate that the request should only succeed if there is an etag match |
Responses
Response samples
- 400
- 404
- 409
- 412
{- "error": "API-000",
- "message": "Could not validate token."
}Restart a Run within an Pipeline by cloning it with the same trigger and inputs.
Attempts to copy and restart the specified Run. The run must be in a completed state.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
| runId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Run ID |
header Parameters
| Idempotency-Key | string Example: 0xr$P0Cu4@DB The HTTP Idempotency-Key |
Responses
Response samples
- 201
- 400
- 404
- 409
- 422
{- "id": "01234567-89ab-cdef-0123-456789abcdef",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "env_ids": [
- "development"
], - "pipeline_id": "sample-pipeline",
- "pipeline_version": "01234567-89ab-cdef-0123-456789abcdef",
- "status": "executing",
- "status_message": "Example text",
- "created_at": "2023-01-01T00:00:00Z",
- "created_by": "01234567-89ab-cdef-0123-456789abcdef",
- "executing_at": "2023-01-01T00:00:00Z",
- "cancellation_requested_at": "2023-01-01T00:00:00Z",
- "completed_at": "2023-01-01T00:00:00Z",
- "timeout_seconds": 3600,
- "trigger": "pipeline_call",
- "inputs": {
- "fizz": "buzz"
}, - "run_as": "s-01234567-89ab-cdef-0123-456789abcdef",
- "concurrency_group": "my-group",
- "waiting_for": {
- "property1": "string",
- "property2": "string"
}
}List the details of the jobs within a pipeline run.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
| runId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Run ID |
query Parameters
| status | Array of strings Example: status=executing Optional filter by status. |
| per_page | integer [ 1 .. 100 ] Default: 50 Example: per_page=50 The maximum number of items to return in a page of results |
| page | string Example: page=AAAAAAAAAA== The page token to request from |
Responses
Response samples
- 200
- 404
[- {
- "id": "my-job",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "pipeline_id": "sample-pipeline",
- "pipeline_version": "01234567-89ab-cdef-0123-456789abcdef",
- "run_id": "01234567-89ab-cdef-0123-456789abcdef",
- "status": "executing",
- "waiting_for": "application.environment.deployment(test-deployment-id)",
- "status_message": "Example text",
- "created_at": "2023-01-01T00:00:00Z",
- "updated_at": "2023-01-01T00:00:00Z",
- "cancellation_requested_at": "2023-01-01T00:00:00Z",
- "completed_at": "2023-01-01T00:00:00Z",
- "timeout_seconds": 3600
}
]List the details of a Job including Step information
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
| runId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Run ID |
| jobId required | string Example: deploy The Job ID |
Responses
Response samples
- 200
- 404
{- "id": "my-job",
- "etag": "1234567890abcdef",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "pipeline_id": "sample-pipeline",
- "pipeline_version": "01234567-89ab-cdef-0123-456789abcdef",
- "run_id": "01234567-89ab-cdef-0123-456789abcdef",
- "status": "executing",
- "waiting_for": "application.environment.deployment(test-deployment-id)",
- "status_message": "Example text",
- "created_at": "2023-01-01T00:00:00Z",
- "updated_at": "2023-01-01T00:00:00Z",
- "cancellation_requested_at": "2023-01-01T00:00:00Z",
- "completed_at": "2023-01-01T00:00:00Z",
- "timeout_seconds": 3600,
- "steps": [
- {
- "index": 0,
- "name": "string",
- "uses": "string",
- "status": "executing",
- "status_message": "Example text",
- "created_at": "2023-01-01T00:00:00Z",
- "completed_at": "2023-01-01T00:00:00Z",
- "timeout_seconds": 3600,
- "related_entities": {
- "env_id": "my-environment",
- "deployment_id": "0123456789abcdef"
}
}
]
}Get a page of log output for a given step within a job.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
| runId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Run ID |
| jobId required | string Example: deploy The Job ID |
| stepIndex required | integer The index of the step within the Job |
query Parameters
| page | string Example: page=AAAAAAAAAA== The page token to request from |
Responses
Response samples
- 200
- 400
- 404
[- {
- "at": "2023-01-01T00:00:00Z",
- "level": "INFO",
- "message": "Example message"
}
]An approval object
| id required | string The id of the approval object. |
| org_id required | string The id of the Organization. |
| app_id required | string The id of the Application. |
| pipeline_id required | string The id of the Pipeline. |
| run_id required | string The id of the Pipeline's Run. |
| job_id required | string The id of the Run's Job. |
| env_id required | string The environment for which the approver needs to have deploy permission to approve the job. |
| message required | string A human-readable message indicating the reason for approval. |
| created_at required | string <date-time> The date and time when the approval request was created. |
| status required | string Enum: "waiting" "approved" "denied" "cancelled" The current status of the approval request. |
| approved_by | string The user who approved or denied the request. |
| approved_at | string <date-time> The date and time when the request was approved or denied. |
{- "id": "string",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "pipeline_id": "sample-pipeline",
- "run_id": "01234567-89ab-cdef-0123-456789abcdef",
- "job_id": "deploy",
- "env_id": "production",
- "message": "Promoting app to production",
- "created_at": "2023-01-01T00:00:00Z",
- "status": "waiting",
- "approved_by": "0123456789ab-cdef-0123-456789abcdef",
- "approved_at": "2023-01-01T00:00:00Z"
}List of the approval requests
List of the approval requests with in an app.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
query Parameters
| per_page | integer [ 1 .. 100 ] Default: 50 Example: per_page=50 The maximum number of items to return in a page of results |
| page | string Example: page=AAAAAAAAAA== The page token to request from |
| pipeline | Array of strings Example: pipeline=sample-pipeline An optional list of Pipeline IDs. |
| run | Array of strings Example: run=sample-run An optional Pipeline Run ID. |
| status | string Example: status=denied Optional filter by status. |
Responses
Response samples
- 200
- 400
[- {
- "id": "string",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "pipeline_id": "sample-pipeline",
- "run_id": "01234567-89ab-cdef-0123-456789abcdef",
- "job_id": "deploy",
- "env_id": "production",
- "message": "Promoting app to production",
- "created_at": "2023-01-01T00:00:00Z",
- "status": "waiting",
- "approved_by": "0123456789ab-cdef-0123-456789abcdef",
- "approved_at": "2023-01-01T00:00:00Z"
}
]Get an approval request
Get an approval request.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
| runId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Run ID |
| jobId required | string Example: deploy The Job ID |
| approvalId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Approval ID |
Responses
Response samples
- 200
- 404
{- "id": "string",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "pipeline_id": "sample-pipeline",
- "run_id": "01234567-89ab-cdef-0123-456789abcdef",
- "job_id": "deploy",
- "env_id": "production",
- "message": "Promoting app to production",
- "created_at": "2023-01-01T00:00:00Z",
- "status": "waiting",
- "approved_by": "0123456789ab-cdef-0123-456789abcdef",
- "approved_at": "2023-01-01T00:00:00Z"
}Approve the approval request
Approve the approval requested.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
| runId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Run ID |
| jobId required | string Example: deploy The Job ID |
| approvalId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Approval ID |
Responses
Response samples
- 200
- 400
- 403
- 404
{- "id": "string",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "pipeline_id": "sample-pipeline",
- "run_id": "01234567-89ab-cdef-0123-456789abcdef",
- "job_id": "deploy",
- "env_id": "production",
- "message": "Promoting app to production",
- "created_at": "2023-01-01T00:00:00Z",
- "status": "waiting",
- "approved_by": "0123456789ab-cdef-0123-456789abcdef",
- "approved_at": "2023-01-01T00:00:00Z"
}Deny the approval request
Deny the approval requested.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID |
| pipelineId required | string Example: sample-pipeline The Pipeline ID |
| runId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Run ID |
| jobId required | string Example: deploy The Job ID |
| approvalId required | string Example: 01234567-89ab-cdef-0123-456789abcdef The Approval ID |
Responses
Response samples
- 200
- 400
- 403
- 404
{- "id": "string",
- "org_id": "sample-org",
- "app_id": "sample-app",
- "pipeline_id": "sample-pipeline",
- "run_id": "01234567-89ab-cdef-0123-456789abcdef",
- "job_id": "deploy",
- "env_id": "production",
- "message": "Promoting app to production",
- "created_at": "2023-01-01T00:00:00Z",
- "status": "waiting",
- "approved_by": "0123456789ab-cdef-0123-456789abcdef",
- "approved_at": "2023-01-01T00:00:00Z"
}UserProfile holds the profile information of a user
| created_at required | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... The time the user was first registered with Humanitec |
string The email address of the user from the profile | |
| id required | string The User ID for this user |
| name required | string The name the user goes by |
| type required | string The type of the account. Could be user, service or system |
{- "created_at": "2020-12-19T09:32:46Z",
- "id": "d510224a-4641-48fd-8054-68efd3537ee2",
- "name": "Jo Trigg",
- "type": "user"
}Response samples
- 200
{- "created_at": "2020-12-19T09:32:46Z",
- "id": "d510224a-4641-48fd-8054-68efd3537ee2",
- "name": "Jo Trigg",
- "properties": {
- "dont_show_welcome_screen": true
}
}Updates the extended profile of the current user.
Request Body schema: application/json
| created_at | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... The time the user was first registered with Humanitec |
string The email address of the user from the profile | |
| id | string The User ID for this user |
| name | string The name the user goes by |
object | |
object | |
| type | string The type of the account. Could be user, service or system |
Responses
Request samples
- Payload
{- "created_at": "2020-12-19T09:32:46Z",
- "id": "d510224a-4641-48fd-8054-68efd3537ee2",
- "name": "Jo Trigg",
- "properties": {
- "dont_show_welcome_screen": true
}
}Response samples
- 200
- 400
{- "created_at": "2020-12-19T09:32:46Z",
- "id": "d510224a-4641-48fd-8054-68efd3537ee2",
- "name": "Jo Trigg",
- "properties": {
- "dont_show_welcome_screen": true
}
}Creates a new service user.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
Request Body schema: application/json
string The email address that should get notifications about this service user. (Optional) | |
| name required | string The name that should be shown for this service user. |
| role required | string The role that the service user should have on the organization it is created in |
Responses
Request samples
- Payload
{- "name": "CI Robot",
- "role": "manager"
}Response samples
- 200
- 400
{- "created_at": "2020-12-19T09:32:46Z",
- "id": "d510224a-4641-48fd-8054-68efd3537ee2",
- "name": "Jo Trigg",
- "type": "user"
}UserRole holds the mapping of role to user for a particular object.
| role | string The role that this user holds |
| user | string The user ID that hold the role |
| created_at | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... The time the user was first registered with Humanitec |
string The email address of the user from the profile | |
| id | string The User ID for this user |
| invite | string The status of an invitation (If applicable) |
| name | string The name the user goes by |
| type | string The type of the account. Could be user, service or system |
{- "role": "manager",
- "user": "61048226-642c-438e-974f-ce5c013d94f8",
- "created_at": "2020-12-19T09:32:46Z",
- "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
- "invite": "accepted",
- "name": "Jo Trigg",
- "type": "user"
}List Users with roles in an App
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string The Application ID. |
Responses
Response samples
- 200
[- {
- "role": "manager",
- "user": "61048226-642c-438e-974f-ce5c013d94f8",
- "created_at": "2020-12-19T09:32:46Z",
- "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
- "invite": "accepted",
- "name": "Jo Trigg",
- "type": "user"
}
]Adds a User to an Application with a Role
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string The Application ID. |
Request Body schema: application/json
The user ID and the role
| role | string The role that this user holds |
| user | string The user ID that hold the role |
| created_at | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... The time the user was first registered with Humanitec |
string The email address of the user from the profile | |
| id | string The User ID for this user |
| invite | string The status of an invitation (If applicable) |
| name | string The name the user goes by |
| type | string The type of the account. Could be user, service or system |
Responses
Request samples
- Payload
{- "id": "61048226-642c-438e-974f-ce5c013d94f8",
- "role": "manager"
}Response samples
- 200
- 400
{- "role": "manager",
- "user": "61048226-642c-438e-974f-ce5c013d94f8",
- "created_at": "2020-12-19T09:32:46Z",
- "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
- "invite": "accepted",
- "name": "Jo Trigg",
- "type": "user"
}Get the role of a User on an Application
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string The Application ID. |
| userId required | string The User ID |
Responses
Response samples
- 200
- 400
{- "role": "manager",
- "user": "61048226-642c-438e-974f-ce5c013d94f8",
- "created_at": "2020-12-19T09:32:46Z",
- "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
- "invite": "accepted",
- "name": "Jo Trigg",
- "type": "user"
}Remove the role of a User on an Application
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string The Application ID. |
| userId required | string The User ID |
Responses
Response samples
- 400
{- "error": "API-000",
- "message": "Could not validate token."
}Update the role of a User on an Application
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| appId required | string The Application ID. |
| userId required | string The User ID |
Request Body schema: application/json
The new user role
| role | string |
Responses
Request samples
- Payload
{- "role": "user"
}Response samples
- 200
- 400
{- "role": "manager",
- "user": "61048226-642c-438e-974f-ce5c013d94f8",
- "created_at": "2020-12-19T09:32:46Z",
- "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
- "invite": "accepted",
- "name": "Jo Trigg",
- "type": "user"
}List Users with roles in an Environment Type
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| envType required | string The Environment Type. |
Responses
Response samples
- 200
[- {
- "role": "manager",
- "user": "61048226-642c-438e-974f-ce5c013d94f8",
- "created_at": "2020-12-19T09:32:46Z",
- "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
- "invite": "accepted",
- "name": "Jo Trigg",
- "type": "user"
}
]Adds a User to an Environment Type with a Role
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| envType required | string The Environment Type. |
Request Body schema: application/json
The user ID and the role
| role | string The role that this user holds |
| user | string The user ID that hold the role |
| created_at | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... The time the user was first registered with Humanitec |
string The email address of the user from the profile | |
| id | string The User ID for this user |
| invite | string The status of an invitation (If applicable) |
| name | string The name the user goes by |
| type | string The type of the account. Could be user, service or system |
Responses
Request samples
- Payload
{- "id": "61048226-642c-438e-974f-ce5c013d94f8",
- "role": "manager"
}Response samples
- 200
- 400
{- "role": "manager",
- "user": "61048226-642c-438e-974f-ce5c013d94f8",
- "created_at": "2020-12-19T09:32:46Z",
- "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
- "invite": "accepted",
- "name": "Jo Trigg",
- "type": "user"
}Get the role of a User on an Environment Type
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| envType required | string The Environment Type. |
| userId required | string The User ID |
Responses
Response samples
- 200
- 400
{- "role": "manager",
- "user": "61048226-642c-438e-974f-ce5c013d94f8",
- "created_at": "2020-12-19T09:32:46Z",
- "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
- "invite": "accepted",
- "name": "Jo Trigg",
- "type": "user"
}Remove the role of a User on an Environment Type
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| envType required | string The Environment Type. |
| userId required | string The User ID |
Responses
Response samples
- 400
{- "error": "API-000",
- "message": "Could not validate token."
}Update the role of a User on an Environment Type
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| envType required | string The Environment Type. |
| userId required | string The User ID |
Request Body schema: application/json
The new user role
| role | string |
Responses
Request samples
- Payload
{- "role": "user"
}Response samples
- 200
- 400
{- "role": "manager",
- "user": "61048226-642c-438e-974f-ce5c013d94f8",
- "created_at": "2020-12-19T09:32:46Z",
- "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
- "invite": "accepted",
- "name": "Jo Trigg",
- "type": "user"
}Invites a user to an Organization with a specified role.
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
Request Body schema: application/json
The email and the desired role
| email required | string The email address of the user from the profile. |
| role required | string The role that this user would hold. |
Responses
Request samples
- Payload
{- "role": "manager"
}Response samples
- 200
- 400
[- {
- "role": "manager",
- "user": "61048226-642c-438e-974f-ce5c013d94f8",
- "created_at": "2020-12-19T09:32:46Z",
- "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
- "invite": "accepted",
- "name": "Jo Trigg",
- "type": "user"
}
]List Users with roles in an Organization
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
Responses
Response samples
- 200
[- {
- "role": "manager",
- "user": "61048226-642c-438e-974f-ce5c013d94f8",
- "created_at": "2020-12-19T09:32:46Z",
- "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
- "invite": "accepted",
- "name": "Jo Trigg",
- "type": "user"
}
]Get the role of a User on an Organization
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| userId required | string The User ID |
Responses
Response samples
- 200
- 400
{- "role": "manager",
- "user": "61048226-642c-438e-974f-ce5c013d94f8",
- "created_at": "2020-12-19T09:32:46Z",
- "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
- "invite": "accepted",
- "name": "Jo Trigg",
- "type": "user"
}Remove the role of a User on an Organization
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| userId required | string The User ID |
Responses
Response samples
- 400
{- "error": "API-000",
- "message": "Could not validate token."
}Update the role of a User on an Organization
path Parameters
| orgId required | string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID |
| userId required | string The User ID |
Request Body schema: application/json
The new user the role
| role | string |
Responses
Request samples
- Payload
{- "role": "user"
}Response samples
- 200
- 400
{- "role": "manager",
- "user": "61048226-642c-438e-974f-ce5c013d94f8",
- "created_at": "2020-12-19T09:32:46Z",
- "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
- "invite": "accepted",
- "name": "Jo Trigg",
- "type": "user"
}Holds metadata about a token. expires_at is excluded if token does not expire.
| created_at required | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... |
| created_by required | string |
| description required | string |
| expires_at | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... |
| id required | string |
| type required | string |
{- "created_at": "2021-04-30T19:47:01Z",
- "description": "Humanitec API Calls from CircleCI Pipelines",
- "expires_at": "2022-04-30T19:47:01Z",
- "id": "circle-ci-token",
- "type": "static",
- "user_id": "a7a04740ae985f12af58545e4edbac6a"
}Response samples
- 200
[- {
- "created_at": "2021-04-30T19:47:01Z",
- "description": "Humanitec API Calls from CircleCI Pipelines",
- "expires_at": "2022-04-30T19:47:01Z",
- "id": "circle-ci-token",
- "type": "static",
- "user_id": "a7a04740ae985f12af58545e4edbac6a"
}
]Creates a new static token for a user.
This is only supported for users of type service.
path Parameters
| userId required | string The user ID. |
Request Body schema: application/json
The definition of the token.
| description | string A description of the token. (Optional) |
| expires_at | string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}... The time the token expires. If not set, the token will not expire. (Optional) |
| id required | string Identifier of the token. Must be unique for the user. |
| type required | string The type of the token. Can only be "static". |
Responses
Request samples
- Payload
{- "description": "Humanitec API Calls from CircleCI Pipelines",
- "expires_at": "2022-04-30T19:47:01Z",
- "id": "circle-ci-token",
- "type": "static"
}Response samples
- 200
- 400
{- "token": "a7a04740ae985f12af58545e4edbac6a",
- "type": "jwt"
}Gets a specific token associated with a user
path Parameters
| userId required | string The user ID. |
| tokenId required | string The token ID. |
Responses
Response samples
- 200
{- "created_at": "2021-04-30T19:47:01Z",
- "description": "Humanitec API Calls from CircleCI Pipelines",
- "expires_at": "2022-04-30T19:47:01Z",
- "id": "circle-ci-token",
- "type": "static",
- "user_id": "a7a04740ae985f12af58545e4edbac6a"
}