Humanitec API (0.28.13)

Download OpenAPI specification:Download

Find out more about how to use Humanitec in your every-day development work.

Introduction

The Humanitec API allows you to automate and integrate Humanitec into your developer and operational workflows. The API is a REST based API. It is based around a set of concepts:

Core
External Resources
Sets and Deltas

Authentication

Almost all requests made to the Humanitec API require Authentication. See our Developer Docs on API Authentication for instructions.

Content Types

The Humanitec API, unless explicitly specified, only accepts content types of application/json and will always return valid application/json or an empty response.

Response Codes

Success

Any response code in the 2xx range should be regarded as success.

Code	Meaning
`200`	Success
`201`	Success, a new resource was created
`204`	Success, but no content in response

Note: We plan to simplify the interface by replacing 201 with 200 status codes.

Failure

Any response code in the 4xx range should be regarded as an error that can be rectified by the client. 5xx error codes indicate errors that cannot be corrected by the client.

Code	Meaning
`400`	General error. (Body will contain details)
`401`	Attempt to access protected resource without `Authorization` Header.
`403`	The `Bearer` or `JWT` does not grant access to the requested resource.
`404`	Resource not found.
`405`	Method not allowed
`409`	Conflict. Usually indicated a resource with that ID already exists.
`422`	Unprocessable Entity. The body was not valid JSON, was empty or contained an object different from what was expected.
`429`	Too many requests - request rate limit has been reached.
`500`	Internal Error. If it occurs repeatedly, contact support.

Agents

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
required

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

Content type

application/json

{"id": "agent-id",
"public_key": "-----BEGIN PUBLIC KEY-----\n...-----END PUBLIC KEY-----",
"description": "One of my agents."
}

Response samples

200
400
409

Content type

application/json

{"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

Content type

application/json

[{"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

Content type

application/json

{"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
required

description

required

string

A description to show future users. It can be empty.

Responses

Request samples

Payload

Content type

application/json

{"description": "One of my agents."
}

Response samples

200
400
404

Content type

application/json

{"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

Content type

application/json

[{"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
required

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

Content type

application/json

{"public_key": "-----BEGIN PUBLIC KEY-----\n...-----END PUBLIC KEY-----"
}

Response samples

200
400
404
409

Content type

application/json

{"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

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Applications

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",
"created_by": "[email protected]",
"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

Content type

application/json

[{"created_at": "2020-06-15T09:32:03Z",
"created_by": "[email protected]",
"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
required

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.
skip_environment_creation	boolean If true, no environment will be created with the application.

Responses

Request samples

Payload

Content type

application/json

{"env": {"id": "string",
"name": "string",
"type": "string"
},
"id": "string",
"name": "string",
"skip_environment_creation": true
}

Response samples

201
400
401
409

Content type

application/json

{"created_at": "2020-06-15T09:32:03Z",
"created_by": "[email protected]",
"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

Content type

application/json

{"created_at": "2020-06-15T09:32:03Z",
"created_by": "[email protected]",
"envs": {"id": "development",
"name": "Development",
"type": "development"
},
"id": "my-app",
"name": "My Awesome App"
}

Update metadata of an existing Application

Update metadata of an existing Application in the specified Organization.

path Parameters

orgId required	string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID
appId required	string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID

Request Body schema: application/json
required

The Application patch request. Only the field name can be updated.

name

required

string

The Human-friendly name for the Application.

Responses

Request samples

Payload

Content type

application/json

{"description": "Example Environment Type description"
}

Response samples

200
404

Content type

application/json

{"created_at": "2020-06-15T09:32:03Z",
"created_by": "[email protected]",
"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

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Artefact

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

Content type

application/json

{ }

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

Content type

application/json

{"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

Content type

application/json

[{"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

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Artefact Version

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 `name`.
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

Content type

application/json

[{"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:
application/json
required

The data needed to register a new Artefact Version within the organization.

type required	string The Artefact Version type. container
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

Content type

application/json

Example

container

{"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

Content type

application/json

Example

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",
"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

Content type

application/json

Example

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",
"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

Content type

application/json

[{"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
required

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

Content type

application/json

{"archived": true
}

Response samples

200
400
401
403
404

Content type

application/json

Example

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",
"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
required

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 An optional set of resource types overrides that will be applied in the deployment set.
	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

Content type

application/json

{"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
},
"resource_type_aliases": {"s3": "my-org/s3"
},
"extensions": {"apiVersion": "humanitec.org/v1b1",
"profile": "humanitec/default-module",
"spec": {"labels": {"my-label": "my-value"
}
}
}
}

Response samples

200
400

Content type

application/json

{"modules": {"property1": { },
"property2": { }
},
"shared": {"property1": { },
"property2": { }
}
}

Audit Logs

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

Content type

application/json

[{"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
}
]

Container Logs

A container log entry.

container_id required	string
level required	string
payload required	string
timestamp required	string
workload_id required	string

{"container_id": "string",
"level": "string",
"payload": "string",
"timestamp": "string",
"workload_id": "string"
}

Get container log entries for the environment

path Parameters

orgId required	string The Organization ID
appId required	string The Application ID
envId required	string The Environment ID

query Parameters

workload_id	string filter by workload ID
container_id	string filter by container ID
deployment_id	string filter by deployment ID
timestamp_from	string filter by min time, RFC 3339 format, e.g. "2021-10-02T15:01:23.045Z"
timestamp_to	string filter by max time, RFC 3330 format, e.g. "2021-10-02T15:01:23.045Z"
limit	string limit log entries returned
asc	boolean if true request results in ascending order, default order is descending
invert	boolean if true reverse the order of the log entries in the output

Responses

Response samples

200

Content type

application/json

[{"container_id": "string",
"level": "string",
"payload": "string",
"timestamp": "string",
"workload_id": "string"
}
]

Deployments

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",
"created_by": "[email protected]",
"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

Content type

application/json

[{ }
]

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
required

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

Content type

application/json

{"comment": "Updated version of module-one to v0.3.1",
"delta_id": "df1ad41807b0390a9b0eaf8688e1f5baece9d764"
}

Response samples

201
400
404
409

Content type

application/json

{"comment": "Updated version of module-one to v0.3.1",
"created_at": "2020-05-22T14:58:07Z",
"created_by": "[email protected]",
"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

Content type

application/json

{ }

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

Content type

application/json

[{"code": "CLD-001",
"message": "Incorrect credentials",
"object_id": "my-service",
"scope": "workload"
}
]

Environment Types

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"
}

List all Environment Types

Lists all Environment Types in an Organization.

path Parameters

orgId

required

string

The Organization ID.

Responses

Response samples

200

Content type

application/json

[{"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
required

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

Content type

application/json

{"description": "Environments used for automated QA.",
"id": "qa-automation"
}

Response samples

201
400
401
409

Content type

application/json

{"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

Content type

application/json

{"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

Content type

application/json

{"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
required

description

string or null

Responses

Request samples

Payload

Content type

application/json

{"description": "Example Environment Type description"
}

Response samples

200
401
404

Content type

application/json

{"description": "Environments used for automated QA.",
"id": "qa-automation"
}

Environments

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.
status required	string Enum: "active" "deleting" The status of the environment
status_changed_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 status was last changed.
status_message	string The message associated with the status of the environment

{"created_at": "2020-05-22T14:58:07Z",
"created_by": "[email protected]",
"status": "active",
"status_changed_at": "2020-05-22T14:59:01Z",
"from_deploy": {"comment": "Updated version of module-one to v0.3.1",
"created_at": "2020-05-22T14:58:07Z",
"created_by": "[email protected]",
"delta_id": "df1ad41807b0390a9b0eaf8688e1f5baece9d764",
"env_id": "my-env",
"from_id": "42d4b302fd3c",
"id": "67f1619a57d",
"status": "in progress",
"status_changed_at": "2020-05-22T14:59:01Z"
},
"id": "feature-test",
"last_deploy": {"comment": "Updated version of module-one to v0.3.1",
"created_at": "2020-05-22T14:58:07Z",
"created_by": "[email protected]",
"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"
}

List all Environments.

Lists all of the Environments in the Application.

path Parameters

orgId required	string The Organization ID.
appId required	string The Application ID.

Responses

Response samples

200

Content type

application/json

[{ }
]

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
required

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

Content type

application/json

{"from_deploy_id": "e80db1a327208c1a",
"id": "awesome-feature",
"name": "Awesome Feature Dev",
"namespace": "awesome-namespace",
"type": "development"
}

Response samples

201
400
404
409

Content type

application/json

{ }

Get a specific Environment.

Gets 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.

Responses

Response samples

200
404

Content type

application/json

{ }

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

Content type

application/json

{"name": "string"
}

Response samples

200
404

Content type

application/json

{ }

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

Content type

application/json

{"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
required

The Deployment ID to rebase to.

string

Responses

Request samples

Payload

Content type

application/json

"string"

Response samples

400
404

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Image

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

Content type

application/json

[{"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

Content type

application/json

{"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

Content type

application/json

[{"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
required

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

Content type

application/json

{"branch": "master",
"commit": "884bccaa807ea27cc1997a7492a3b6279fd7bd55",
"image": "registry.humanitec.io/my-org/my-service:1.2.7",
"tags": ["string"
]
}

Response samples

400
401
403

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Keys

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
required

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

string

Responses

Request samples

Payload

Content type

application/json

"-----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

Content type

application/json

{"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

Content type

application/json

[{"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"
}
]

Delete a public key associated to an organization.

path Parameters

orgId required	string The organization ID.
keyId required	string The public key ID.

Responses

Response samples

403
404

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

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

Content type

application/json

{"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"
}

Organization

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"
}

List active organizations the user has access to.

Responses

Response samples

200
403

Content type

application/json

[{"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

Content type

application/json

{"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"
}

Registry

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: `public` `basic` `google_gcr` `amazon_ecr` `secret_ref`

{"created_at": "2020-05-22T14:53:27Z",
"created_by": "[email protected]",
"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

Content type

application/json

[{"created_at": "2020-05-22T14:53:27Z",
"created_by": "[email protected]",
"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
required

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: `public` `basic` `google_gcr` `amazon_ecr` `secret_ref`

Responses

Request samples

Payload

Content type

application/json

{"created_at": "2020-05-22T14:53:27Z",
"created_by": "[email protected]",
"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

Content type

application/json

{"created_at": "2020-05-22T14:53:27Z",
"created_by": "[email protected]",
"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

Content type

application/json

{"created_at": "2020-05-22T14:53:27Z",
"created_by": "[email protected]",
"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

Content type

application/json

{"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
required

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: `public` `basic` `google_gcr` `amazon_ecr` `secret_ref`

Responses

Request samples

Payload

Content type

application/json

{"created_at": "2020-05-22T14:53:27Z",
"created_by": "[email protected]",
"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

Content type

application/json

{"created_at": "2020-05-22T14:53:27Z",
"created_by": "[email protected]",
"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

Content type

application/json

{"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": ""
}

Runtime Information

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 <= 50 characters ^[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

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

[{"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
required

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
	Array of objects (ResourceDefinitions) List of the definitions with their type that should be used by the resource graph nodes generated based on the context.

Responses

Request samples

Payload

Content type

application/json

{"app_id": "sample-app",
"env_id": "sample-env",
"env_type": "development",
"expected_definitions": [{"type": "string",
"id": "string"
}
]
}

Response samples

200

Content type

application/json

{"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

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

Content type

application/json

[{"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
required

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

Content type

application/json

{"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

Content type

application/json

{"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

Content type

application/json

{"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"
}
}

Delete the Secret Store.

path Parameters

orgId required	string The Organization ID.
storeId required	string The Secret Store ID.

Responses

Response samples

404

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Update the Secret Store.

path Parameters

orgId required	string The Organization ID.
storeId required	string The Secret Store ID.

Request Body schema: application/json
required

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

Content type

application/json

{"awssm": {"auth": {"secret_access_key": "s0mE_te$t_wrIte_kee"
},
"region": "us-east-1"
},
"primary": true
}

Response samples

200
400
404

Content type

application/json

{"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

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
400

Content type

application/json

[{"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
required

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

Content type

application/json

{"description": "string",
"is_secret": true,
"key": "string",
"value": "string",
"secret_ref": {"store": "string",
"ref": "string",
"version": "string",
"value": "string"
}
}

Response samples

201
400
409

Content type

application/json

{"description": "The message to show me.",
"is_secret": false,
"key": "MY_MSG",
"value": "Hello World"
}

Delete all Shared Value for an Environment

All Shared Values will be deleted. If the Shared Values are marked as a secret, they will also be deleted.

path Parameters

orgId required	string The Organization ID.
appId required	string The Application ID.
envId required	string The Environment ID.

Responses

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
required

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

Content type

application/json

{"description": "string",
"value": "string",
"is_secret": true,
"key": "string",
"secret_ref": {"store": "string",
"ref": "string",
"version": "string",
"value": "string"
}
}

Response samples

200
400
404

Content type

application/json

{"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

Content type

application/json

{"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
required

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

Content type

application/json

{"description": "string",
"value": "string",
"secret_ref": {"store": "string",
"ref": "string",
"version": "string",
"value": "string"
}
}

Response samples

200
400
404

Content type

application/json

{"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

Content type

application/json

[{"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
required

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

Content type

application/json

{"description": "string",
"is_secret": true,
"key": "string",
"value": "string",
"secret_ref": {"store": "string",
"ref": "string",
"version": "string",
"value": "string"
}
}

Response samples

201
400
409

Content type

application/json

{"description": "The message to show me.",
"is_secret": false,
"key": "MY_MSG",
"value": "Hello World"
}

Delete all Shared Value for an App

All Shared Values will be deleted. If the Shared Values are marked as a secret, they will also be deleted.

path Parameters

orgId required	string The Organization ID.
appId required	string The Application ID.

Responses

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
required

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

Content type

application/json

{"description": "string",
"value": "string",
"is_secret": true,
"key": "string",
"secret_ref": {"store": "string",
"ref": "string",
"version": "string",
"value": "string"
}
}

Response samples

200
400
404

Content type

application/json

{"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

Content type

application/json

{"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
required

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

Content type

application/json

{"description": "string",
"value": "string",
"secret_ref": {"store": "string",
"ref": "string",
"version": "string",
"value": "string"
}
}

Response samples

200
400
404

Content type

application/json

{"description": "The message to show me.",
"is_secret": false,
"key": "MY_MSG",
"value": "Hello World"
}

Shared Value Set Version

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

Content type

application/json

[{"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

Content type

application/json

{"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
required

comment

string

Responses

Request samples

Payload

Content type

application/json

{"comment": "string"
}

Response samples

400
404

Content type

application/json

{"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
required

comment

string

Responses

Request samples

Payload

Content type

application/json

{"comment": "string"
}

Response samples

200
404

Content type

application/json

{"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
required

comment

string

Responses

Request samples

Payload

Content type

application/json

{"comment": "string"
}

Response samples

200
400
404

Content type

application/json

{"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

Content type

application/json

[{"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

Content type

application/json

{"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
required

comment

string

Responses

Request samples

Payload

Content type

application/json

{"comment": "string"
}

Response samples

400
404

Content type

application/json

{"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
required

comment

string

Responses

Request samples

Payload

Content type

application/json

{"comment": "string"
}

Response samples

200
404

Content type

application/json

{"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
required

comment

string

Responses

Request samples

Payload

Content type

application/json

{"comment": "string"
}

Response samples

200
400
404

Content type

application/json

{"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"
}
}
}

Deployment Deltas

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 <= 50 characters ^[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

Content type

application/json

[{"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 <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID

Request Body schema: application/json
required

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

Content type

application/json

{"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

Content type

application/json

Example

"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 <= 50 characters ^[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

Content type

application/json

{"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 <= 50 characters ^[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
required

An array of Deltas.

The Deltas in the request are combined, meaning the current Delta is updated in turn by each Delta in the request. Once all Deltas have been combined, the resulting Delta is simplified.

All Modules in the modules.add property are replaced with the new Delta's values. If the value of a Module is null, and the ID is in the modules.remove list, it is removed from the modules.remove list.
All IDs listed in modules.remove are combined. Any ID in modules.remove and also in modules.add are removed from modules.add
The lists of JSON Patches in modules.update are concatenated or created in modules.updates.

Simplification involves:

Applying any entries in modules.updates that have matching IDs in modules.add to the modules.add entry and removing the modules.update entry.
Reducing the number of JSON Patches in each modules.update entry to the smallest set that has the same effect.

Extension to JSON Patch

If a JSON Patch entry needs to be removed, without side effects, the value of the remove action can be set to `{"scope": "delta"}. This will result in the remove action being used during simplification but be discarded before the Delta is finalized.

If the user making the request is not the user who created the Delta and they are not already on the contributors list, they will be added to the contributors list.

NOTE: If the id or metadata properties are specified, they will be ignored.

Array

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

Content type

application/json

[{"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

Content type

application/json

{"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 <= 50 characters ^[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
required

An array of Deltas.

The Deltas in the request are combined, meaning the current Delta is updated in turn by each Delta in the request. Once all Deltas have been combined, the resulting Delta is simplified.

All Modules in the modules.add property are replaced with the new Delta's values. If the value of a Module is null, and the ID is in the modules.remove list, it is removed from the modules.remove list.
All IDs listed in modules.remove are combined. Any ID in modules.remove and also in modules.add are removed from modules.add
The lists of JSON Patches in modules.update are concatenated or created in modules.updates.

Simplification involves:

Applying any entries in modules.updates that have matching IDs in modules.add to the modules.add entry and removing the modules.update entry.
Reducing the number of JSON Patches in each modules.update entry to the smallest set that has the same effect.

Extension to JSON Patch

If a JSON Patch entry needs to be removed, without side effects, the value of the remove action can be set to `{"scope": "delta"}. This will result in the remove action being used during simplification but be discarded before the Delta is finalized.

If the user making the request is not the user who created the Delta and they are not already on the contributors list, they will be added to the contributors list.

NOTE: If the id or metadata properties are specified, they will be ignored.

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

Content type

application/json

{"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

Content type

application/json

{"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 <= 50 characters ^[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
required

Either true or false.

boolean

Responses

Request samples

Payload

Content type

application/json

true

Response samples

400
404

Content type

application/json

{"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 <= 50 characters ^[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
required

The new Environment ID. (NOTE: The string must still be JSON encoded.)

string (EnvironmentID) ^[a-z0-9](?:-?[a-z0-9]+)+$

Responses

Request samples

Payload

Content type

application/json

"new-env"

Response samples

400
404

Content type

application/json

{"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 <= 50 characters ^[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
required

The new name.(NOTE: The string must still be JSON encoded.)

string

Responses

Request samples

Payload

Content type

application/json

"Update for ticket #s 2568 & 2572"

Response samples

400
404

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Deployment Sets

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 <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID

Responses

Response samples

200
404

Content type

application/json

[{"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 <= 50 characters ^[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

Content type

application/json

Example

SetResponse

{"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 <= 50 characters ^[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
required

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

Content type

application/json

{"modules": {"remove": ["module-one"
]
}
}

Response samples

200
400
404

Content type

application/json

"string"

Get Resource Inputs for the given Deployment Set

path Parameters

orgId required	string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID
appId required	string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID
setId required	string ID of the Deployment Set.

Responses

Response samples

200
400
404

Content type

application/json

[{"class": "cloudsql",
"id": "shared.postgres",
"resource": {"host": "127.0.0.1",
"name": "my-database"
},
"type": "postgres"
}
]

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 <= 50 characters ^[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

Content type

application/json

{"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

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

Content type

application/json

[{"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
required

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

Content type

application/json

{"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

Content type

application/json

{"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

Content type

application/json

{"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
required

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

Content type

application/json

{"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

Content type

application/json

{"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

Content type

application/json

{"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

Content type

application/json

[{"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

Content type

application/json

{"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:

file with application/x-gzip content 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
required

Workload profile chart version.

file	string <binary>

Responses

Response samples

201
400
409

Content type

application/json

{"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

Content type

application/json

[{"created_at": "2020-06-22T09:37:23.523Z",
"created_by": "string",
"org_id": "string",
"id": "string",
"version": "string"
}
]

Active Resources

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).
scheduled_deletion	boolean Deletion is scheduled for this resource.
	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.
provisioned_internally	boolean Indicates if a resource was provisioned internally (default to false)

{"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.

query Parameters

scheduled_deletion

boolean

If set to true or false, filters resources scheduled or not scheduled for deletion correspondingly.

Responses

Response samples

200
500

Content type

application/json

[{"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 true, will detach an active resource. The resource continues to exist and is not deleted, but it is no longer connected to the Platform Orchestrator. Detaching can be done for any active resource. In case that the resource is an active one (i.e. not marked to be deleted), it would stay in use until the next deployment. Detaching active resources can cause inconsistent status (e.g. detaching a k8s-cluster might make it impossible to retrieve runtime information by or un-pause an environment) If the resource has been provisioned via the Humanitec Operator, this does not delete the resource CR in the cluster. This must be done manually.

Responses

Response samples

400
404
409

Content type

application/json

{"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 <= 50 characters ^[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
required

target_def_version_id

required

string or null

The Resource Definition Version pinned to this resource to be provisioned from.

Responses

Request samples

Payload

Content type

application/json

{"target_def_version_id": "01234567-89ab-cdef-0123-4567890abcdef"
}

Response samples

200
400
404

Content type

application/json

{"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

Content type

application/json

[{"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"
}
]

Resource Drivers

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 `driver_type`.
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 `driver://` schema of the format `driver://{orgId}/{driverId}`. Only members of the organization the driver belongs to can see `target`.
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",
"target": "https://drivers.example.com/route53/",
"template": "",
"type": "dns"
}

List Resource Drivers.

path Parameters

orgId

required

string

The Organization ID.

Responses

Response samples

200
500

Content type

application/json

[{"account_types": ["gcp",
"aws"
],
"id": "route53",
"inputs_schema": { },
"is_public": false,
"org_id": "test-org",
"target": "https://drivers.example.com/route53/",
"template": "",
"type": "dns"
}
]

Register a new Resource Driver.

path Parameters

orgId

required

string

The Organization ID.

Request Body schema: application/json
required

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 `driver_type`.
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 `driver://` schema of the format `driver://{orgId}/{driverId}`. Only members of the organization the driver belongs to can see 'target'.
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

Content type

application/json

{"account_types": ["gcp",
"aws"
],
"id": "route53",
"inputs_schema": { },
"is_public": false,
"target": "https://drivers.example.com/route53/",
"template": "",
"type": "dns"
}

Response samples

200
400
409
500

Content type

application/json

{"account_types": ["gcp",
"aws"
],
"id": "route53",
"inputs_schema": { },
"is_public": false,
"org_id": "test-org",
"target": "https://drivers.example.com/route53/",
"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

Content type

application/json

{"account_types": ["gcp",
"aws"
],
"id": "route53",
"inputs_schema": { },
"is_public": false,
"org_id": "test-org",
"target": "https://drivers.example.com/route53/",
"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
required

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 `driver://` schema of the format `driver://{orgId}/{driverId}`. Only members of the organization the driver belongs to can see 'target'.
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

Content type

application/json

{"account_types": ["gcp",
"aws"
],
"inputs_schema": { },
"is_public": false,
"target": "https://drivers.example.com/route53/",
"template": "{{ mustToRawJson .driver }}",
"type": "dns"
}

Response samples

200
400
404
500

Content type

application/json

{"account_types": ["gcp",
"aws"
],
"id": "route53",
"inputs_schema": { },
"is_public": false,
"org_id": "test-org",
"target": "https://drivers.example.com/route53/",
"template": "",
"type": "dns"
}

Delete a Resources Driver.

path Parameters

orgId required	string The Organization ID.
driverId required	string The Resources Driver ID to delete.

Responses

Response samples

500

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

MatchingCriteria

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 `default`.
env_id	string (Optional) The ID of the Environment that the Resources should belong to. If `env_type` is also set, it must match the Type of the Environment for the Criteria to match.
env_type	string (Optional) The Type of the Environment that the Resources should belong to. If `env_id` is also set, it must have an Environment Type that matches this parameter for the Criteria to match.
id required	string Matching Criteria ID
res_id	string (Optional) The ID of the Resource in the Deployment Set. The ID is normally a `.` separated path to the definition in the set, e.g. `modules.my-module.externals.my-database`.

{"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
required

Matching Criteria rules.

Array

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 `default`.
env_id	string (Optional) The ID of the Environment that the Resources should belong to. If `env_type` is also set, it must match the Type of the Environment for the Criteria to match.
env_type	string (Optional) The Type of the Environment that the Resources should belong to. If `env_id` is also set, it must have an Environment Type that matches this parameter for the Criteria to match.
res_id	string (Optional) The ID of the Resource in the Deployment Set. The ID is normally a `.` separated path to the definition in the set, e.g. `modules.my-module.externals.my-database`.

Responses

Request samples

Payload

Content type

application/json

[{"env_id": "production"
}
]

Response samples

200
400
404
409
500

Content type

application/json

[{"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
required

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 `default`.
env_id	string (Optional) The ID of the Environment that the Resources should belong to. If `env_type` is also set, it must match the Type of the Environment for the Criteria to match.
env_type	string (Optional) The Type of the Environment that the Resources should belong to. If `env_id` is also set, it must have an Environment Type that matches this parameter for the Criteria to match.
res_id	string (Optional) The ID of the Resource in the Deployment Set. The ID is normally a `.` separated path to the definition in the set, e.g. `modules.my-module.externals.my-database`.

Responses

Request samples

Payload

Content type

application/json

{"env_id": "production"
}

Response samples

200
400
404
409
500

Content type

application/json

{"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 true, the Matching Criteria is deleted immediately, even if this action affects existing Active Resources.

Responses

Response samples

404
409
500

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Definitions

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",
"created_by": "[email protected]",
"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

Content type

application/json

[{"created_at": "2020-05-23T12:32:16Z",
"created_by": "[email protected]",
"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
required

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

Content type

application/json

{"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

Content type

application/json

{"created_at": "2020-05-23T12:32:16Z",
"created_by": "[email protected]",
"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

Content type

application/json

{"created_at": "2020-05-23T12:32:16Z",
"created_by": "[email protected]",
"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
required

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

Content type

application/json

{"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

Content type

application/json

{"created_at": "2020-05-23T12:32:16Z",
"created_by": "[email protected]",
"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 true, will mark the Resource Definition for deletion, even if it affects existing Active Resources.

Responses

Response samples

404
409
500

Content type

application/json

{"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
required

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

Content type

application/json

{"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

Content type

application/json

{"created_at": "2020-05-23T12:32:16Z",
"created_by": "[email protected]",
"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
required

Matching Criteria rules.

Array

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 `default`.
env_id	string (Optional) The ID of the Environment that the Resources should belong to. If `env_type` is also set, it must match the Type of the Environment for the Criteria to match.
env_type	string (Optional) The Type of the Environment that the Resources should belong to. If `env_id` is also set, it must have an Environment Type that matches this parameter for the Criteria to match.
res_id	string (Optional) The ID of the Resource in the Deployment Set. The ID is normally a `.` separated path to the definition in the set, e.g. `modules.my-module.externals.my-database`.

Responses

Request samples

Payload

Content type

application/json

[{"env_id": "production"
}
]

Response samples

200
400
404
409
500

Content type

application/json

[{"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
required

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 `default`.
env_id	string (Optional) The ID of the Environment that the Resources should belong to. If `env_type` is also set, it must match the Type of the Environment for the Criteria to match.
env_type	string (Optional) The Type of the Environment that the Resources should belong to. If `env_id` is also set, it must have an Environment Type that matches this parameter for the Criteria to match.
res_id	string (Optional) The ID of the Resource in the Deployment Set. The ID is normally a `.` separated path to the definition in the set, e.g. `modules.my-module.externals.my-database`.

Responses

Request samples

Payload

Content type

application/json

{"env_id": "production"
}

Response samples

200
400
404
409
500

Content type

application/json

{"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 true, the Matching Criteria is deleted immediately, even if this action affects existing Active Resources.

Responses

Response samples

404
409
500

Content type

application/json

{"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

Content type

application/json

[{"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"
}
]

Definition Versions

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 `created`, `updated` or `deleted`.
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",
"created_by": "[email protected]",
"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

Content type

application/json

[{"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",
"created_by": "[email protected]",
"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

Content type

application/json

{"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",
"created_by": "[email protected]",
"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
required

archived

boolean

Indicates whether to set this version archived or non-archived. Optional, true if not specified.

Responses

Request samples

Payload

Content type

application/json

{"archive": true
}

Response samples

400
404

Content type

application/json

{"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

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Resources Dependency

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
required

Resources to provision.

Array

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

Content type

application/json

[{"class": "cloudsql",
"id": "shared.postgres",
"resource": {"host": "127.0.0.1",
"name": "my-database"
},
"type": "postgres"
}
]

Response samples

200
400
500

Content type

application/json

[{"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 <= 50 characters ^[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
required

Resources to provision.

Array

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

Content type

application/json

[{"class": "cloudsql",
"id": "shared.postgres",
"resource": {"host": "127.0.0.1",
"name": "my-database"
},
"type": "postgres"
}
]

Response samples

200
400

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

{"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

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"
}

List Resource Account Types available to the organization.

path Parameters

orgId

required

string

The Organization ID.

Responses

Response samples

200

Content type

application/json

[{"name": "GCP",
"type": "gcp"
}
]

Resource Accounts

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

Content type

application/json

[{"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

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

Content type

application/json

{"credentials": {"password": "***",
"username": "***"
},
"id": "gcp-dev-postgres",
"name": "GCP Dev Postgres",
"type": "gcp-service-account"
}

Response samples

200
400
401
409
500

Content type

application/json

{"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

Content type

application/json

{"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

Content type

application/json

{"details": {"referencing_resources": {"resource_definitions": [{"created_at": "2020-05-23T12:32:16Z",
"created_by": "[email protected]",
"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
required

	object Credentials associated with the account.
name	string Display name.

Responses

Request samples

Payload

Content type

application/json

{"credentials": {"password": "***",
"username": "***"
},
"name": "GCP Dev Postgres"
}

Response samples

200
400
404
500

Content type

application/json

{"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

Content type

application/json

{"identity_fields": [{"id": "string",
"description": "string",
"value": "string"
}
],
"warnings": ["string"
]
}

Resources Types

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: `direct`, `indirect`, `implicit`.

{"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"
}

List Resource Types.

path Parameters

orgId

required

string

The Organization ID.

Responses

Response samples

200
500

Content type

application/json

[{"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"
}
]

ResourceClass

List resource classes.

path Parameters

orgId

required

string^[a-z0-9][a-z0-9-]+[a-z0-9]$

The organization ID.

Responses

Response samples

200

Content type

application/json

[{"id": "string",
"resource_type": "string",
"description": "string",
"created_by": "string",
"created_at": "2019-08-24T14:15:22Z"
}
]

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
required

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

Content type

application/json

{"id": "string",
"description": "string"
}

Response samples

200
400
409

Content type

application/json

{"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

Content type

application/json

{"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
required

description

required

string [ 0 .. 1024 ] characters

New description for the resource class.

Responses

Request samples

Payload

Content type

application/json

{"description": "string"
}

Response samples

200
404

Content type

application/json

{"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

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Automation Rules

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` is true, this list describes the artefacts to exclude.
exclude_artefacts_filter	boolean Whether the artefacts specified in `artefacts_filter` should be excluded (true) or included (false) in the automation rule.
exclude_images_filter	boolean Deprecated DEPRECATED: Whether the images specified in `images_filter` should be excluded (true) or included (false) in the automation rule.
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 `exclude_images_filter` is true, this list describes images to exclude.
match	string Deprecated DEPRECATED: A regular expression applied to the branch or tag name depending on the value of `update_to`. Defaults to match all if omitted or empty.
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"`.
update_to	string^(?:branch\|tag)$ Deprecated DEPRECATED: Specifies whether the update occurs on commit to branch or creation of tag. Must be one of `"branch"` or `"tag"`.

{"active": true,
"artefacts_filter": ["http://registry.org/sample-service"
],
"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 <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID
envId required	string Example: development The Environment ID

Responses

Response samples

200

Content type

application/json

[{"active": true,
"artefacts_filter": ["http://registry.org/sample-service"
],
"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 <= 50 characters ^[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
required

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` is true, this list describes the artefacts to exclude.
exclude_artefacts_filter	boolean Whether the artefacts specified in `artefacts_filter` should be excluded (true) or included (false) in the automation rule.
exclude_images_filter	boolean Deprecated DEPRECATED: Whether the images specified in `images_filter` should be excluded (true) or included (false) in the automation rule.
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 `exclude_images_filter` is true, this list describes images to exclude.
match	string Deprecated DEPRECATED: A regular expression applied to the branch or tag name depending on the value of `update_to`. Defaults to match all if omitted or empty.
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"`.
update_to	string^(?:branch\|tag)$ Deprecated DEPRECATED: Specifies whether the update occurs on commit to branch or creation of tag. Must be one of `"branch"` or `"tag"`.

Responses

Request samples

Payload

Content type

application/json

{"active": true,
"artefacts_filter": ["http://registry.org/sample-service"
],
"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

Content type

application/json

{"active": true,
"artefacts_filter": ["http://registry.org/sample-service"
],
"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 <= 50 characters ^[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

Content type

application/json

{"active": true,
"artefacts_filter": ["http://registry.org/sample-service"
],
"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 <= 50 characters ^[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
required

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` is true, this list describes the artefacts to exclude.
exclude_artefacts_filter	boolean Whether the artefacts specified in `artefacts_filter` should be excluded (true) or included (false) in the automation rule.
exclude_images_filter	boolean Deprecated DEPRECATED: Whether the images specified in `images_filter` should be excluded (true) or included (false) in the automation rule.
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 `exclude_images_filter` is true, this list describes images to exclude.
match	string Deprecated DEPRECATED: A regular expression applied to the branch or tag name depending on the value of `update_to`. Defaults to match all if omitted or empty.
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"`.
update_to	string^(?:branch\|tag)$ Deprecated DEPRECATED: Specifies whether the update occurs on commit to branch or creation of tag. Must be one of `"branch"` or `"tag"`.

Responses

Request samples

Payload

Content type

application/json

{"active": true,
"artefacts_filter": ["http://registry.org/sample-service"
],
"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

Content type

application/json

{"active": true,
"artefacts_filter": ["http://registry.org/sample-service"
],
"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 <= 50 characters ^[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

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Webhooks

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"
}

Deletes all Jobs for the Application

path Parameters

orgId required	string The Organization ID.
appId required	string The Application ID.

Responses

List Webhooks

path Parameters

orgId required	string The Organization ID.
appId required	string The Application ID.

Responses

Response samples

200

Content type

application/json

[{"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
required

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

Content type

application/json

{"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

Content type

application/json

{"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

Content type

application/json

{"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"
}

Delete 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

404

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

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
required

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

Content type

application/json

{"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

Content type

application/json

{"disabled": true,
"headers": {"property1": null,
"property2": null
},
"payload": {"property1": null,
"property2": null
},
"triggers": [{"scope": "string",
"type": "string"
}
],
"url": "string"
}

List Events

path Parameters

orgId

required

string

The Organization ID.

Responses

Response samples

200

Content type

application/json

[{"properties": ["string"
],
"scope": "string",
"type": "string"
}
]

Pipelines

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

Content type

application/json

[{"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 <= 50 characters ^[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

Content type

application/json

[{"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 <= 50 characters ^[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
required

object

Responses

Response samples

201
400
404
409

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

{"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 <= 50 characters ^[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
required

object

Responses

Response samples

200
400
404
409
412

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

[{"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 <= 50 characters ^[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

Content type

application/x.humanitec-pipelines-v1.0+yaml

No sample

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 <= 50 characters ^[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

Content type

application/json

[{"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 <= 50 characters ^[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
required

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

Content type

application/json

{"env_type": "development",
"app_id": "my-application",
"env_id": "my-environment",
"deployment_type": "deploy",
"trigger": "deployment_request"
}

Response samples

201
400
404
409

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Gets the latest pipeline schema

path Parameters

orgId

required

string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$

Example: sample-org

The Organization ID

Responses

Response samples

200
400

Content type

application/json

{ }

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 <= 50 characters ^[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

Content type

application/json

{"items": [{"type": "string",
"ref": "string"
}
],
"scheduled_at": "2019-08-24T14:15:22Z"
}

Pipeline Runs

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 ordered newest to oldest. 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

Content type

application/json

[{"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 <= 50 characters ^[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
required

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

Content type

application/json

{"trigger": "deployment_request",
"env_id": "development",
"delta_id": "0123456789abcdef0123456789abcdef01234567",
"comment": "My deployment"
}

Response samples

201
400
404
409
422

Content type

application/json

{"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 ordered newest to oldest.

path Parameters

orgId required	string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID
appId required	string <= 50 characters ^[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

Content type

application/json

[{"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 <= 50 characters ^[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

required

object

The inputs provided for this Run.

Responses

Request samples

Payload

Content type

application/json

{"inputs": {"fizz": "buzz"
}
}

Response samples

201
400
404
409
422

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

[{"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 <= 50 characters ^[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

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

[{"at": "2023-01-01T00:00:00Z",
"level": "INFO",
"message": "Example message"
}
]

Pipeline Approvals

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 <= 50 characters ^[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

Content type

application/json

[{"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 <= 50 characters ^[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

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

{"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 <= 50 characters ^[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

Content type

application/json

{"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"
}

User Profiles

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
email	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",
"email": "[email protected]",
"id": "d510224a-4641-48fd-8054-68efd3537ee2",
"name": "Jo Trigg",
"type": "user"
}

Gets the extended profile of the current user

Responses

Response samples

200

Content type

application/json

{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"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
required

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
email	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

Content type

application/json

{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "d510224a-4641-48fd-8054-68efd3537ee2",
"name": "Jo Trigg",
"properties": {"dont_show_welcome_screen": true
}
}

Response samples

200
400

Content type

application/json

{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"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
required

email	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

Content type

application/json

{"name": "CI Robot",
"role": "manager"
}

Response samples

200
400

Content type

application/json

{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "d510224a-4641-48fd-8054-68efd3537ee2",
"name": "Jo Trigg",
"type": "user"
}

User Roles

Holds the mapping of role for a subject on a particular object.

id required	string^[a-z0-9](?:-?[a-z0-9]+)+$ The User or Group Id
role required	string The role that this User or Group holds

{"id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
"role": "manager"
}

List Users or Groups 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 <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID

query Parameters

type	string (SubjectTypeEnum) Enum: "user" "group" Type of Subject. Either User or Group

Responses

Response samples

200
403
404

Content type

application/json

[{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
"invite": "accepted",
"name": "Jo Trigg",
"role": "manager",
"type": "user"
}
]

Adds a User or a Group 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 <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID

Request Body schema: application/json
required

The User or Group ID and the role

id required	string^[a-z0-9](?:-?[a-z0-9]+)+$ The User or Group Id
role required	string The role that this User or Group holds

Responses

Request samples

Payload

Content type

application/json

{"id": "61048226-642c-438e-974f-ce5c013d94f8",
"role": "manager"
}

Response samples

200
400
403
404

Content type

application/json

{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
"invite": "accepted",
"name": "Jo Trigg",
"role": "manager",
"type": "user"
}

Get the role of a User or a Group 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 <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID
userId required	string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: 61048226-642c-438e-974f-ce5c013d94f8 The User or Group Id.

Responses

Response samples

200
400
403
404

Content type

application/json

{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
"invite": "accepted",
"name": "Jo Trigg",
"role": "manager",
"type": "user"
}

Remove the role of a User or a Group 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 <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID
userId required	string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: 61048226-642c-438e-974f-ce5c013d94f8 The User or Group Id.

Responses

Response samples

400
403
404

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Update the role of a User or a Group 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 <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-app The Application ID
userId required	string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: 61048226-642c-438e-974f-ce5c013d94f8 The User or Group Id.

Request Body schema: application/json
required

The new User or Group role

role

required

string

Responses

Request samples

Payload

Content type

application/json

{"role": "user"
}

Response samples

200
400
403
404

Content type

application/json

{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
"invite": "accepted",
"name": "Jo Trigg",
"role": "manager",
"type": "user"
}

List Users and Groups 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^[a-z0-9](?:-?[a-z0-9]+)+$ The Environment Type.

query Parameters

type	string (SubjectTypeEnum) Enum: "user" "group" Type of Subject. Either User or Group

Responses

Response samples

200
403
404

Content type

application/json

[{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
"invite": "accepted",
"name": "Jo Trigg",
"role": "manager",
"type": "user"
}
]

Adds a User or a Group 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^[a-z0-9](?:-?[a-z0-9]+)+$ The Environment Type.

Request Body schema: application/json
required

The User or Group ID and the role

id required	string^[a-z0-9](?:-?[a-z0-9]+)+$ The User or Group Id
role required	string The role that this User or Group holds

Responses

Request samples

Payload

Content type

application/json

{"id": "61048226-642c-438e-974f-ce5c013d94f8",
"role": "manager"
}

Response samples

200
400
403
404

Content type

application/json

{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
"invite": "accepted",
"name": "Jo Trigg",
"role": "manager",
"type": "user"
}

Get the role of a User or a Group 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^[a-z0-9](?:-?[a-z0-9]+)+$ The Environment Type.
userId required	string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: 61048226-642c-438e-974f-ce5c013d94f8 The User or Group Id.

Responses

Response samples

200
400
403
404

Content type

application/json

{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
"invite": "accepted",
"name": "Jo Trigg",
"role": "manager",
"type": "user"
}

Remove the role of a User or a Group 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^[a-z0-9](?:-?[a-z0-9]+)+$ The Environment Type.
userId required	string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: 61048226-642c-438e-974f-ce5c013d94f8 The User or Group Id.

Responses

Response samples

400
403
404

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Update the role of a User or a Group 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^[a-z0-9](?:-?[a-z0-9]+)+$ The Environment Type.
userId required	string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: 61048226-642c-438e-974f-ce5c013d94f8 The User or Group Id.

Request Body schema: application/json
required

The new User or Group role

role

required

string

Responses

Request samples

Payload

Content type

application/json

{"role": "user"
}

Response samples

200
400
403
404

Content type

application/json

{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
"invite": "accepted",
"name": "Jo Trigg",
"role": "manager",
"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
required

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

Content type

application/json

{"email": "[email protected]",
"role": "manager"
}

Response samples

200
400

Content type

application/json

[{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
"invite": "accepted",
"name": "Jo Trigg",
"role": "manager",
"type": "user"
}
]

List Users and Groups with roles in an Organization

path Parameters

orgId

required

string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$

Example: sample-org

The Organization ID

query Parameters

type	string (SubjectTypeEnum) Enum: "user" "group" Type of Subject. Either User or Group

Responses

Response samples

200
403
404

Content type

application/json

[{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
"invite": "accepted",
"name": "Jo Trigg",
"role": "manager",
"type": "user"
}
]

Get the role of a User or a Group 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^[a-z0-9](?:-?[a-z0-9]+)+$ Example: 61048226-642c-438e-974f-ce5c013d94f8 The User or Group Id.

Responses

Response samples

200
400
403
404

Content type

application/json

{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
"invite": "accepted",
"name": "Jo Trigg",
"role": "manager",
"type": "user"
}

Remove the role of a User or a Group 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^[a-z0-9](?:-?[a-z0-9]+)+$ Example: 61048226-642c-438e-974f-ce5c013d94f8 The User or Group Id.

Responses

Response samples

400
403
404

Content type

application/json

{"error": "API-000",
"message": "Could not validate token."
}

Update the role of a User or a Group 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^[a-z0-9](?:-?[a-z0-9]+)+$ Example: 61048226-642c-438e-974f-ce5c013d94f8 The User or Group Id.

Request Body schema: application/json
required

The new User or Group role

role

required

string

Responses

Request samples

Payload

Content type

application/json

{"role": "user"
}

Response samples

200
400
403
404

Content type

application/json

{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
"invite": "accepted",
"name": "Jo Trigg",
"role": "manager",
"type": "user"
}

Get the permissions of a User or Group on the objects in an Organization

path Parameters

orgId required	string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID
userId required	string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: 61048226-642c-438e-974f-ce5c013d94f8 The User or Group Id.

Responses

Response samples

200
403
404

Content type

application/json

{"objects": {"property1": {"permissions": ["string"
]
},
"property2": {"permissions": ["string"
]
}
}
}

User Groups

GroupRequest holds the definition of a new group.

group_id required	string The name of the group in the IdP.
idp_id required	string^[a-z0-9](?:-?[a-z0-9]+)+$ The IdP id.
role required	string (OrganizationRole) Enum: "administrator" "manager" "member" "artefactContributor" "orgViewer" Roles that can be assumed by an entity on an organization.

{"group_id": "my-idp-group",
"idp_id": "my-idp",
"role": "manager"
}

Create a group in 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
required

The group metadata and the role.

group_id required	string The name of the group in the IdP.
idp_id required	string^[a-z0-9](?:-?[a-z0-9]+)+$ The IdP id.
role required	string (OrganizationRole) Enum: "administrator" "manager" "member" "artefactContributor" "orgViewer" Roles that can be assumed by an entity on an organization.

Responses

Request samples

Payload

Content type

application/json

{"group_id": "my-idp-group",
"idp_id": "my-idp",
"role": "manager"
}

Response samples

200
400
403
409

Content type

application/json

{"id": "g-d510224a-4641-48fd-8054-68efd3537ee2",
"group_id": "my-idp-group",
"idp_id": "my-idp",
"role": "manager"
}

List users in a group.

path Parameters

orgId required	string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID
groupId required	string^g-[a-z0-9](?:-?[a-z0-9]+)+$ Example: g-61048226-642c-438e-974f-ce5c013d94f8 The Group Id.

Responses

Response samples

200
400
404

Content type

application/json

[{"created_at": "2020-12-19T09:32:46Z",
"email": "[email protected]",
"id": "d510224a-4641-48fd-8054-68efd3537ee2",
"name": "Jo Trigg",
"type": "user"
}
]

Get the groups in an organization a user belongs to.

path Parameters

orgId required	string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$ Example: sample-org The Organization ID
userId required	string^[a-z0-9](?:-?[a-z0-9]+)+$ Example: 61048226-642c-438e-974f-ce5c013d94f8 The User or Group Id.

Responses

Response samples

200
400
403
404

Content type

application/json

[{"id": "g-d510224a-4641-48fd-8054-68efd3537ee2",
"group_id": "my-idp-group",
"idp_id": "my-idp"
}
]

Token Info

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"
}

Lists tokens associated with a user

path Parameters

userId

required

string

The user ID.

Responses

Response samples

200

Content type

application/json

[{"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
required

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

Content type

application/json

{"description": "Humanitec API Calls from CircleCI Pipelines",
"expires_at": "2022-04-30T19:47:01Z",
"id": "circle-ci-token",
"type": "static"
}

Response samples

200
400

Content type

application/json

{"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

Content type

application/json

{"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"
}

Deletes a specific token associated with a user

This endpoint deletes a user's session token. The deleted token can no longer be used to access the API. All other tokens for this user can still be used.

path Parameters

userId required	string The user ID.
tokenId required	string The token ID.

Humanitec API (0.28.13)

Introduction

Authentication

Content Types

Response Codes

Success

Failure

Agents

Register a new Agent under an Organization.

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

List all the agents in an Organization.

path Parameters

query Parameters

Responses

Response samples

Delete an Agent (and its keys) stored under an Organization.

path Parameters

Responses

Response samples

Update the description of an Agent.

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

List all the keys registered under an Agent in an Organization.

path Parameters

Responses

Response samples

Register a new Key under an Agent in an Organization.

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete a key registered under a Agent.

path Parameters

Responses

Response samples

Applications

List all Applications in an Organization.

path Parameters

Responses

Response samples

Add a new Application to an Organization

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get an existing Application

path Parameters

Responses

Response samples

Update metadata of an existing Application

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete an Application

path Parameters

Responses

Response samples

Artefact

Get the spec of this Workload Artefact Version

path Parameters

header Parameters

Responses

Response samples

Get the Humanitec module definition of this Workload Artefact Version as a deployment set

path Parameters

header Parameters

Responses

Response samples

List all Artefacts.

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema:
application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required