Humanitec logo
API docs by Redocly

Humanitec API (0.26.25)

Download OpenAPI specification:Download

Humanitec Support: support@humanitec.com
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
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

Content type
application/json
{
  • "id": "agent-id",
  • "public_key": "-----BEGIN PUBLIC KEY-----\n...-----END PUBLIC KEY-----",
  • "description": "One of my agents."
}

Response samples

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

Content type
application/json
[
  • {
    }
]

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

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
description
required
string

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

Responses

Request samples

Content type
application/json
{
  • "description": "One of my agents."
}

Response samples

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

Content type
application/json
[
  • {
    }
]

Register a new Key under an Agent in an Organization.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

agentId
required
string
Example: my-agent

The Agent id.

Request Body schema: application/json
public_key
required
string

A pcks8 RSA public key PEM encoded (as the ones produced by openssl), whose module length is greater or equal than 4096 bits.

Responses

Request samples

Content type
application/json
{
  • "public_key": "-----BEGIN PUBLIC KEY-----\n...-----END PUBLIC KEY-----"
}

Response samples

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

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": "a.user@example.com",
  • "envs": [
    ],
  • "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

Content type
application/json
[
  • {
    }
]

Add a new Application to an Organization

Creates a new Application, then adds it to the specified Organization.

path Parameters
orgId
required
string

The Organization ID.

Request Body schema: application/json

The request ID, Human-friendly name and environment of the Application.

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

The ID which refers to a specific application.

name
required
string

The Human-friendly name for the Application.

Responses

Request samples

Content type
application/json
{
  • "env": {
    },
  • "id": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "2020-06-15T09:32:03Z",
  • "created_by": "a-user@example.com",
  • "envs": {
    },
  • "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

Content type
application/json
{
  • "created_at": "2020-06-15T09:32:03Z",
  • "created_by": "a-user@example.com",
  • "envs": {
    },
  • "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

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

Content type
{ }

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

Content type
{
  • "modules": {
    },
  • "shared": {
    }
}

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

Content type
application/json
[
  • {
    }
]

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

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

Content type
application/json
[
  • {
    }
]

Register a new Artefact Version with your organization.

path Parameters
orgId
required
string
Example: sample-org

The organization ID.

query Parameters
vcs
string
Example: vcs=git

(Optional) Which version control system the version comes from. Default value is "git". If this parameter is not supplied or its value is "git", the provided ref, if not empty, is checked to ensure that it has the prefix "refs/".

dry_run
boolean

Optionally validate the request but do not persist the actual artefact. If the Accept type is set to "application/x.workload-deployment-set+json" or "application/x.workload-deployment-set+x-yaml", the generated deployment set will be returned.

header Parameters
Accept
string

Indicates which content types the client is able to understand.

Request Body schema:

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

type
required
string

The Artefact Version type.

name
required
string

The Artefact name.

version
string

(Optional) The Artefact Version.

ref
string

(Optional) The ref the Artefact Version was built from.

commit
string^[0-9a-f]{5,40}$

(Optional) The commit ID the Artefact Version was built on.

digest
string

(Optional) The Artefact Version digest.

Responses

Request samples

Content type
Example
{
  • "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

Content type
Example
{
  • "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

Content type
application/json
Example
{
  • "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

Content type
application/json
[
  • {
    }
]

Update Version of an Artefact.

Update the version of a specified Artefact registered with your organization".

path Parameters
orgId
required
string
Example: sample-org

The organization ID.

artefactId
required
string
Example: da97af75-2e7c-4ef3-bec0-755ce1e8dd29

The Artefact ID.

versionId
required
string
Example: da97af75-2e7c-4ef3-bec0-755ce1e8dd29

The Version ID.

Request Body schema: application/json

The Artefact Version Update Request. Only the field archive can be updated.

archived
required
boolean or null

The Value of the archived value.

Responses

Request samples

Content type
application/json
{
  • "archived": true
}

Response samples

Content type
application/json
Example
{
  • "archived": false,
  • "artefact_id": "01234567-89ab-cdef-0123-456789abcdef",
  • "commit": "060c3d6530a881afb808f105f36af25e1ad1b2f3",
  • "created_at": "2020-06-22T09:37:23.523Z",
  • "created_by": "01234567-89ab-cdef-0123-456789abcdef",
  • "id": "01234567-89ab-cdef-0123-456789abcdef",
  • "name": "registry.humanitec.io/my-org/my-service",
  • "ref": "refs/heads/main",
  • "updated_at": "2020-06-22T09:37:23.523Z",
  • "updated_by": "01234567-89ab-cdef-0123-456789abcdef",
  • "version": "1.2.7",
  • "digest": "sha256:8414aa82208bc4c2761dc149df67e25c6b8a9380e5d8c4e7b5c84ca2d04bb244",
  • "type": "container"
}

Convert a Score specification, optional overrides, and extensions into the contents for a deployment set.

path Parameters
orgId
required
string
Example: sample-org

The organization ID.

Request Body schema: application/json

The Score specification, optional overrides, and extensions.

required
object

A Json object containing the workload specification. Score v1b1 is expected.

image
string

An optional default image to assign to any containers in the workload that do not have an image set or whose image is '.'

object

An optional Json object containing the workload overrides. Score v1b1 is expected.

object

An optional set of path overrides that will be applied to the workload.

object (ScoreHumanitecExtensions)

Humanitec workload extensions for the Workload Artefact Version. These can be used to override the profile, or workload module spec and resource attributes.

Responses

Request samples

Content type
application/json
{
  • "spec": {
    },
  • "image": "busybox:latest",
  • "overrides": {
    },
  • "property_overrides": {
    },
  • "extensions": {
    }
}

Response samples

Content type
application/json
{
  • "modules": {
    },
  • "shared": {
    }
}

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

Content type
application/json
[
  • {
    }
]

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": "a.user@example.com",
  • "delta_id": "df1ad41807b0390a9b0eaf8688e1f5baece9d764",
  • "env_id": "my-env",
  • "from_id": "42d4b302fd3c",
  • "id": "67f1619a57d",
  • "status": "in progress",
  • "status_changed_at": "2020-05-22T14:59:01Z"
}

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

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

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

Content type
application/json
{
  • "comment": "Updated version of module-one to v0.3.1",
  • "delta_id": "df1ad41807b0390a9b0eaf8688e1f5baece9d764"
}

Response samples

Content type
application/json
{
  • "comment": "Updated version of module-one to v0.3.1",
  • "created_at": "2020-05-22T14:58:07Z",
  • "created_by": "a.user@example.com",
  • "delta_id": "df1ad41807b0390a9b0eaf8688e1f5baece9d764",
  • "env_id": "my-env",
  • "from_id": "42d4b302fd3c",
  • "id": "67f1619a57d",
  • "status": "in progress",
  • "status_changed_at": "2020-05-22T14:59:01Z"
}

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

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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
[
  • {
    }
]

Add a new Environment Type

Adds a new Environment Type to an Organization.

path Parameters
orgId
required
string

The Organization ID.

Request Body schema: application/json

New Environment Type.

description
string

A Human-readable description of the Environment Type

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

The ID of the Environment Type. (Must be unique within an Organization.)

Responses

Request samples

Content type
application/json
{
  • "description": "Environments used for automated QA.",
  • "id": "qa-automation"
}

Response samples

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

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

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
description
string or null

Responses

Request samples

Content type
application/json
{
  • "description": "Example Environment Type description"
}

Response samples

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.

{
  • "created_at": "2020-05-22T14:58:07Z",
  • "created_by": "a.user@example.com",
  • "from_deploy": {
    },
  • "id": "feature-test",
  • "last_deploy": {
    },
  • "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

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

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

Content type
application/json
{
  • "from_deploy_id": "e80db1a327208c1a",
  • "id": "awesome-feature",
  • "name": "Awesome Feature Dev",
  • "namespace": "awesome-namespace",
  • "type": "development"
}

Response samples

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

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

Content type
application/json
{
  • "name": "string"
}

Response samples

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

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

The Deployment ID to rebase to.

string

Responses

Request samples

Content type
application/json
"string"

Response samples

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": [
    ],
  • "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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{
  • "added_at": "2020-06-22T09:37:23.523Z",
  • "builds": [
    ],
  • "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

Content type
application/json
[
  • {
    }
]

Add a new Image Build

DEPRECATED: This endpoint exists for historical compatibility and should not be used. Please use the Artefact API instead.

This endpoint is used by Continuous Integration (CI) pipelines to notify Humanitec that a new Image Build is available.

If there is no Image with ID imageId, it will be automatically created.

path Parameters
orgId
required
string
Example: sample-org

The organization ID.

imageId
required
string
Example: sample-app

The Image ID.

Request Body schema: application/json

The metadata associated with the build.

branch
string

The branch name of the branch the build was built on

commit
string

The commit ID that this build was built from.

image
string^((?:[\w.\-_]+(?:(?::\d+|)(?=/[a-z0-9._-]+/[a...

The fully qualified Image URL including registry, repository and tag.

tags
Array of strings

The tag that the build was built from.

Responses

Request samples

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

Response samples

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

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

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

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

Content type
application/json
[
  • {
    }
]

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

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

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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{
  • "created_at": "2020-06-22T09:37:23.523Z",
  • "created_by": "string",
  • "id": "string",
  • "logo": {
    },
  • "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": "a.user@example.com",
  • "enable_ci": false,
  • "id": "humanitec",
  • "registry": "registry.humanitec.io",
  • "secrets": {
    },
  • "type": "basic"
}

Lists available registries for the organization.

path Parameters
orgId
required
string

Unique (alpha-numerical) organization identifier.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a new registry record.

path Parameters
orgId
required
string

Unique (alpha-numerical) organization identifier.

Request Body schema: application/json

A new record details.

object (AccountCredsRequest)

AccountCreds represents an account credentials (either, username- or token-based).

enable_ci
boolean

Indicates if registry secrets and credentials should be exposed to CI agents.

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

Registry ID, unique within the Organization.

registry
required
string

Registry name, usually in a "{domain}" or "{domain}/{project}" format.

object (ClusterSecretsMapRequest)

ClusterSecretsMap stores a list of Kuberenetes secret references for the target deployment clusters.

type
required
string

Registry type, describes the registry authentication method, and defines the schema for the credentials.

Supported values:

  • public

  • basic

  • google_gcr

  • amazon_ecr

  • secret_ref

Responses

Request samples

Content type
application/json
{
  • "created_at": "2020-05-22T14:53:27Z",
  • "created_by": "a.user@example.com",
  • "enable_ci": false,
  • "id": "humanitec",
  • "registry": "registry.humanitec.io",
  • "secrets": {
    },
  • "type": "basic"
}

Response samples

Content type
application/json
{
  • "created_at": "2020-05-22T14:53:27Z",
  • "created_by": "a.user@example.com",
  • "enable_ci": false,
  • "id": "humanitec",
  • "registry": "registry.humanitec.io",
  • "secrets": {
    },
  • "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

Content type
application/json
{
  • "created_at": "2020-05-22T14:53:27Z",
  • "created_by": "a.user@example.com",
  • "enable_ci": false,
  • "id": "humanitec",
  • "registry": "registry.humanitec.io",
  • "secrets": {
    },
  • "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

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

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

Content type
application/json
{
  • "created_at": "2020-05-22T14:53:27Z",
  • "created_by": "a.user@example.com",
  • "enable_ci": false,
  • "id": "humanitec",
  • "registry": "registry.humanitec.io",
  • "secrets": {
    },
  • "type": "basic"
}

Response samples

Content type
application/json
{
  • "created_at": "2020-05-22T14:53:27Z",
  • "created_by": "a.user@example.com",
  • "enable_ci": false,
  • "id": "humanitec",
  • "registry": "registry.humanitec.io",
  • "secrets": {
    },
  • "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

Content type
application/json
{
  • "expires": "2020-05-22T14:53:27Z",
  • "password": "",
  • "registry": "registry.io/project",
  • "secrets": {
    },
  • "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": {
    },
  • "namespace": "string"
}

Get Runtime information about the environment.

Runtime info are fetched from the cluster provisioned by the Orchestrator with Resource Id k8s-cluster-runtime. If no cluster with that id is found, the system fetches information from a cluster provisioned with the default Resource Id k8s-cluster.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

envId
required
string
Example: development

The Environment ID

Responses

Response samples

Content type
{
  • "modules": {
    },
  • "namespace": "string"
}

Get Runtime information about specific multiple environments.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

query Parameters
id
Array of strings

Filter environments by ID (required). Up to 5 ids can be supplied per request.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Provision and check the cluster connectivity in an environment

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

Request Body schema: application/json

Parameters required to start a cluster provisioning and connection check.

app_id
required
string

The application Id to test

env_id
required
string

The environment Id to test

env_type
required
string

The environment type to test

Responses

Request samples

Content type
application/json
{
  • "app_id": "sample-app",
  • "env_id": "sample-env",
  • "env_type": "development"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "resource_summaries": [
    ],
  • "conditions": [
    ]
}

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": {
    },
  • "azurekv": {
    },
  • "created_at": "2020-06-22T09:37:23.523Z",
  • "created_by": "string",
  • "gcpsm": {
    },
  • "humanitec": { },
  • "id": "string",
  • "primary": true,
  • "updated_at": "2020-06-22T09:37:23.523Z",
  • "updated_by": "string",
  • "vault": {
    }
}

Get list of Secret Stores for the given organization.

path Parameters
orgId
required
string

The Organization ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Secret Store for the given organization.

path Parameters
orgId
required
string

The Organization ID.

Request Body schema: application/json

Secret Store data.

object (AWSSMRequest)

AWS Secret Manager specification.

object (AzureKVRequest)

Azure Key Vault specification.

object (GCPSMRequest)

GCP Secret Manager specification.

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

The Secret Store ID.

primary
required
boolean

Defines whether the Secret Store is the primary secret management system for the organization.

object (VaultRequest)

Vault specification.

Responses

Request samples

Content type
application/json
{
  • "awssm": {
    },
  • "id": "my-aws-secret-manager",
  • "primary": true
}

Response samples

Content type
application/json
{
  • "awssm": {
    },
  • "azurekv": {
    },
  • "created_at": "2020-06-22T09:37:23.523Z",
  • "created_by": "string",
  • "gcpsm": {
    },
  • "humanitec": { },
  • "id": "string",
  • "primary": true,
  • "updated_at": "2020-06-22T09:37:23.523Z",
  • "updated_by": "string",
  • "vault": {
    }
}

Get the Secret Store.

path Parameters
orgId
required
string

The Organization ID.

storeId
required
string

The Secret Store ID.

Responses

Response samples

Content type
application/json
{
  • "awssm": {
    },
  • "azurekv": {
    },
  • "created_at": "2020-06-22T09:37:23.523Z",
  • "created_by": "string",
  • "gcpsm": {
    },
  • "humanitec": { },
  • "id": "string",
  • "primary": true,
  • "updated_at": "2020-06-22T09:37:23.523Z",
  • "updated_by": "string",
  • "vault": {
    }
}

Delete the Secret Store.

path Parameters
orgId
required
string

The Organization ID.

storeId
required
string

The Secret Store ID.

Responses

Response samples

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

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

Content type
application/json
{
  • "awssm": {
    },
  • "primary": true
}

Response samples

Content type
application/json
{
  • "awssm": {
    },
  • "azurekv": {
    },
  • "created_at": "2020-06-22T09:37:23.523Z",
  • "created_by": "string",
  • "gcpsm": {
    },
  • "humanitec": { },
  • "id": "string",
  • "primary": true,
  • "updated_at": "2020-06-22T09:37:23.523Z",
  • "updated_by": "string",
  • "vault": {
    }
}

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

Content type
application/json
[
  • {
    }
]

Create a Shared Value for an Environment

The Shared Value created will only be available to the specific Environment.

If a Value is marked as a secret, it will be securely stored. It will not be possible to retrieve the value again through the API. The value of the secret can however be updated.

path Parameters
orgId
required
string

The Organization ID.

appId
required
string

The Application ID.

envId
required
string

The Environment ID.

Request Body schema: application/json

Definition of the new Shared Value.

description
required
string or null
is_secret
boolean
key
required
string^[A-Za-z0-9_.-]+$
value
string or null
object or null (SecretReference)

It stores sensitive value in the organization primary store or a reference to a sensitive value stored in a store registered under the organization.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "is_secret": true,
  • "key": "string",
  • "value": "string",
  • "secret_ref": {
    }
}

Response samples

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

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

Content type
application/json
{
  • "description": "string",
  • "value": "string",
  • "is_secret": true,
  • "key": "string",
  • "secret_ref": {
    }
}

Response samples

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

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

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

Content type
application/json
{
  • "description": "string",
  • "value": "string",
  • "secret_ref": {
    }
}

Response samples

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

Content type
application/json
[
  • {
    }
]

Create a Shared Value for an Application

The Shared Value created will be available to all Environments in that Application.

If a Value is marked as a secret, it will be securely stored. It will not be possible to retrieve the value again through the API. The value of the secret can however be updated.

path Parameters
orgId
required
string

The Organization ID.

appId
required
string

The Application ID.

Request Body schema: application/json

Definition of the new Shared Value.

description
required
string or null
is_secret
boolean
key
required
string^[A-Za-z0-9_.-]+$
value
string or null
object or null (SecretReference)

It stores sensitive value in the organization primary store or a reference to a sensitive value stored in a store registered under the organization.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "is_secret": true,
  • "key": "string",
  • "value": "string",
  • "secret_ref": {
    }
}

Response samples

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

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

Content type
application/json
{
  • "description": "string",
  • "value": "string",
  • "is_secret": true,
  • "key": "string",
  • "secret_ref": {
    }
}

Response samples

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

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

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

Content type
application/json
{
  • "description": "string",
  • "value": "string",
  • "secret_ref": {
    }
}

Response samples

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

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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{
  • "change": [
    ],
  • "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": {
    }
}

Purge the value of a specific Shared Value from the App Environment Version history.

Purging permanently removes the value of a specific Shared Value in an application. A purged value is no longer accessible, can't be restored and can't be used by deployments referencing a Value Set Version where the value was present.

Learn more about purging in our docs.

path Parameters
orgId
required
string

The Organization ID.

appId
required
string

The Application ID.

envId
required
string

The Environment ID.

valueSetVersionId
required
string <uuid>

The ValueSetVersion ID.

key
required
string

Key of the value to be purged.

Request Body schema: application/json
comment
string

Responses

Request samples

Content type
application/json
{
  • "comment": "string"
}

Response samples

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
comment
string

Responses

Request samples

Content type
application/json
{
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "change": [
    ],
  • "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": {
    }
}

Restore a specific key from the Value Set Version in an Environment of an App

Restore the values of a single Shared Value in an Environment from a specific version.

Learn more about reverting in our docs.

path Parameters
orgId
required
string

The Organization ID.

appId
required
string

The Application ID.

envId
required
string

The Environment ID.

valueSetVersionId
required
string <uuid>

The ValueSetVersion ID.

key
required
string

Key of the value to be restored.

Request Body schema: application/json
comment
string

Responses

Request samples

Content type
application/json
{
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "change": [
    ],
  • "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": {
    }
}

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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{
  • "change": [
    ],
  • "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": {
    }
}

Purge the value of a specific Shared Value from the App Version history.

Purging permanently removes the value of a specific Shared Value in an Application. A purged value is no longer accessible, can't be restored and can't be used by deployments referencing a Value Set Version where the value was present.

Learn more about purging in our docs.

path Parameters
orgId
required
string

The Organization ID.

appId
required
string

The Application ID.

valueSetVersionId
required
string <uuid>

The ValueSetVersion ID.

key
required
string

Key of the value to be purged.

Request Body schema: application/json
comment
string

Responses

Request samples

Content type
application/json
{
  • "comment": "string"
}

Response samples

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
comment
string

Responses

Request samples

Content type
application/json
{
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "change": [
    ],
  • "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": {
    }
}

Restore a specific key from the Value Set Version in an App

Restore the values of a single Shared Value in an application from a specific version.

Learn more about reverting in our docs.

path Parameters
orgId
required
string

The Organization ID.

appId
required
string

The Application ID.

valueSetVersionId
required
string <uuid>

The ValueSetVersion ID.

key
required
string

Key of the value to be restored.

Request Body schema: application/json
comment
string

Responses

Request samples

Content type
application/json
{
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "change": [
    ],
  • "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": {
    }
}

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

List Deltas in an Application

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

query Parameters
archived
boolean

If true, return archived Deltas.

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

Only return Deltas associated with the specified Environment.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new Delta

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

Request Body schema: application/json

A Deployment Delta to create.

The Deployment Delta will be added with the provided content of modules and the 'env_id' and 'name' properties of the 'metadata' property.

NOTE: If the id property is specified, it will be ignored. A new ID will be generated and returned in the response.

id
string

Ignored, but can be provided.

object (DeltaMetadataRequest)
object (ModuleDeltasRequest)

ModuleDeltas groups the different operations together.

Array of objects or null (UpdateActionRequest)

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "modules": {
    }
}

Response samples

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^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

deltaId
required
string

ID of the Delta to fetch.

Responses

Response samples

Content type
application/json
{
  • "id": "49393b5004d072000b8abfd910c61685eb9235f5",
  • "metadata": { },
  • "modules": {
    }
}

Update an existing Delta

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

deltaId
required
string

ID of the Delta to update.

Request Body schema: application/json

An array of Deltas.

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

  • All Modules in the modules.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

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "49393b5004d072000b8abfd910c61685eb9235f5",
  • "metadata": { },
  • "modules": {
    }
}

Update an existing Delta

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

deltaId
required
string

ID of the Delta to update.

Request Body schema: application/json

An array of Deltas.

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

  • All Modules in the modules.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

Content type
application/json
{
  • "id": "49393b5004d072000b8abfd910c61685eb9235f5",
  • "metadata": { },
  • "modules": {
    }
}

Response samples

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^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

deltaId
required
string

ID of the Deployment Delta.

Request Body schema: application/json

Either true or false.

boolean

Responses

Request samples

Content type
application/json
true

Response samples

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^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

deltaId
required
string

ID of the Deployment Delta.

Request Body schema: application/json

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

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

Responses

Request samples

Content type
application/json
"new-env"

Response samples

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^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

deltaId
required
string

ID of the Deployment Delta.

Request Body schema: application/json

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

string

Responses

Request samples

Content type
application/json
"Update for ticket #s 2568 & 2572"

Response samples

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

Get all Deployment Sets

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a Deployment Set

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

setId
required
string

ID of the Deployment Set.

query Parameters
diff
string

ID of the Deployment Set to compared against.

Responses

Response samples

Content type
application/json
Example
{
  • "modules": {
    }
}

Apply a Deployment Delta to a Deployment Set

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

setId
required
string

ID of the Deployment Set.

Request Body schema: application/json

The Delta to apply to the Set.

NOTE: The id parameter is ignored if provided. The request body should be the full Delta.

id
string

Ignored, but can be provided.

object (DeltaMetadataRequest)
object (ModuleDeltasRequest)

ModuleDeltas groups the different operations together.

Array of objects or null (UpdateActionRequest)

Responses

Request samples

Content type
application/json
{
  • "modules": {
    }
}

Response samples

Content type
application/json
"string"

Get the difference between 2 Deployment Sets

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

setId
required
string

ID of the Deployment Set.

sourceSetId
required
string

ID of the Deployment Set to diff against.

Responses

Response samples

Content type
application/json
{
  • "modules": {
    }
}

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": {
    },
  • "version": "string",
  • "workload_profile_chart": {
    }
}

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

Content type
application/json
[
  • {
    }
]

Create new Workload Profile

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

Request Body schema: application/json

Workload profile details.

id
required
string

Workload Profile ID

description
string

Describes the workload profile

deprecation_message
string

A not-empty string indicates that the workload profile is deprecated.

required
object (WorkloadProfileSpecDefinition)

Workload spec definition

version
string

Version identifier. The version must be unique, but the API doesn't not enforce any ordering. Currently workloads will always use the latest update.

If no identifier is provided, the each update will generate a random version identifier.

required
object (WorkloadProfileChartReference)

References a workload profile chart.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "description": "string",
  • "deprecation_message": "string",
  • "spec_definition": {
    },
  • "version": "string",
  • "workload_profile_chart": {
    }
}

Response samples

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": {
    },
  • "spec_schema": null,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string",
  • "version": "string",
  • "workload_profile_chart": {
    }
}

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

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": {
    },
  • "spec_schema": null,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string",
  • "version": "string",
  • "workload_profile_chart": {
    }
}

Update a Workload Profile

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

profileQid
required
string

The Workload Profile ID.

Request Body schema: application/json

Workload profile details.

description
string

Describes the workload profile

deprecation_message
string

A not-empty string indicates that the workload profile is deprecated.

required
object (WorkloadProfileSpecDefinition)

Workload spec definition

version
string

Version identifier. The version must be unique, but the API doesn't not enforce any ordering. Currently workloads will always use the latest update.

If no identifier is provided, the each update will generate a random version identifier.

required
object (WorkloadProfileChartReference)

References a workload profile chart.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "deprecation_message": "string",
  • "spec_definition": {
    },
  • "version": "string",
  • "workload_profile_chart": {
    }
}

Response samples

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": {
    },
  • "spec_schema": null,
  • "updated_at": "2019-08-24T14:15:22Z",
  • "updated_by": "string",
  • "version": "string",
  • "workload_profile_chart": {
    }
}

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

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

Content type
application/json
[
  • {
    }
]

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

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": {
    },
  • "spec_schema": null,
  • "workload_profile_chart": {
    },
  • "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:

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

Workload profile chart version.

file
string <binary>

Responses

Response samples

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

Content type
application/json
[
  • {
    }
]

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

object

Secret references from the resource provisioning output.

status
required
string

Current resource status: 'pending', 'active', or 'deleting'.

type
required
string

The Resource Type of the resource

updated_at
required
string <date-time>

The time the resource was last provisioned as part of a deployment.

{
  • "app_id": "test-app",
  • "class": "default",
  • "def_id": "gcp-dev-postgres",
  • "def_version_id": "01234567-89ab-cdef-0123-4567890abcdef",
  • "deploy_id": "172a1013b",
  • "env_id": "gcp-dev",
  • "env_type": "development",
  • "gu_res_id": "7bd3966c9ff8eaa66c5cce855c03d715857c3440",
  • "org_id": "test-org",
  • "res_id": "modules.my-module.externals.my-db",
  • "resource": {
    },
  • "secret_refs": {
    },
  • "type": "postgres",
  • "updated_at": "2020-06-23T16:53:12Z"
}

List Active Resources provisioned in an environment.

path Parameters
orgId
required
string

The Organization ID.

appId
required
string

The Application ID.

envId
required
string

The Environment ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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

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^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

envId
required
string
Example: development

The Environment ID

type
required
string

The Resource Type, may include a resource class: {type}.{class}.

resId
required
string

The Resource ID.

Request Body schema: application/json
target_def_version_id
required
string or null

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

Responses

Request samples

Content type
application/json
{
  • "target_def_version_id": "01234567-89ab-cdef-0123-4567890abcdef"
}

Response samples

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

Content type
application/json
[
  • {
    }
]

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": [
    ],
  • "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

Content type
application/json
[
  • {
    }
]

Register a new Resource Driver.

path Parameters
orgId
required
string

The Organization ID.

Request Body schema: application/json

Resources Driver details.

account_types
required
Array of strings

List of resources accounts types supported by the driver

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

The ID for this driver. Is used as 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

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "account_types": [
    ],
  • "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

Content type
application/json
{
  • "account_types": [
    ],
  • "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
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

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "account_types": [
    ],
  • "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

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

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

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Add a new Matching Criteria to a Resource Definition.

Matching Criteria are combined with Resource Type to select a specific definition. Matching Criteria can be set for any combination of Application ID, Environment ID, Environment Type, and Resource ID. In the event of multiple matches, the most specific match is chosen.

For example, given 3 sets of matching criteria for the same type:

 1. {"env_type":"test"}
 2. {"env_type":"development"}
 3. {"env_type":"test", "app_id":"my-app"}

If, a resource of that type was needed in an Application my-app, Environment qa-team with Type test and Resource ID modules.my-module-externals.my-resource, there would be two resource definitions matching the criteria: #1 & #3. Definition #3 will be chosen because its matching criteria is the most specific.

path Parameters
orgId
required
string

The Organization ID.

defId
required
string

The Resource Definition ID.

Request Body schema: application/json

Matching Criteria rules.

app_id
string

(Optional) The ID of the Application that the Resources should belong to.

class
string

(Optional) The class of the Resource in the Deployment Set. Can not be empty, if is not defined, set to 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

Content type
application/json
{
  • "env_id": "production"
}

Response samples

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

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": "a.user@example.com",
  • "criteria": [
    ],
  • "driver_account": "gcp-dev-cloudsql",
  • "driver_inputs": {
    },
  • "driver_type": "humanitec/postgres-cloudsql",
  • "id": "dev-postgres",
  • "is_default": false,
  • "is_deleted": false,
  • "name": "Dev Postgres Instance",
  • "org_id": "test-org",
  • "provision": {
    },
  • "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

Content type
application/json
[
  • {
    }
]

Create a new Resource Definition.

path Parameters
orgId
required
string

The Organization ID.

Request Body schema: application/json

The Resource Definition details.

Array of objects (MatchingCriteriaRuleRequest)

(Optional) The criteria to use when looking for a Resource Definition during the deployment.

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

(Optional) Security account required by the driver.

object (ValuesSecretsRefsRequest)

ValuesSecretsRefs stores data that should be passed around split by sensitivity.

driver_type
required
string

The driver to be used to create the resource.

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

The Resource Definition ID.

name
required
string

The display name.

object

(Optional) A map where the keys are resType#resId (if resId is omitted, the same id of the current resource definition is used) of the resources that should be provisioned when the current resource is provisioned. This also specifies if the resources have a dependency on the current resource.

type
required
string

The Resource Type.

Responses

Request samples

Content type
application/json
{
  • "criteria": [ ],
  • "driver_account": "gcp-dev-cloudsql",
  • "driver_inputs": {
    },
  • "driver_type": "humanitec/cloudsql",
  • "id": "dev-postgres",
  • "name": "Dev Postgres Instance",
  • "provision": {
    },
  • "type": "postgres"
}

Response samples

Content type
application/json
{
  • "created_at": "2020-05-23T12:32:16Z",
  • "created_by": "a.user@example.com",
  • "criteria": [
    ],
  • "driver_account": "gcp-dev-cloudsql",
  • "driver_inputs": {
    },
  • "driver_type": "humanitec/postgres-cloudsql",
  • "id": "dev-postgres",
  • "is_default": false,
  • "is_deleted": false,
  • "name": "Dev Postgres Instance",
  • "org_id": "test-org",
  • "provision": {
    },
  • "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

Content type
application/json
{
  • "created_at": "2020-05-23T12:32:16Z",
  • "created_by": "a.user@example.com",
  • "criteria": [
    ],
  • "driver_account": "gcp-dev-cloudsql",
  • "driver_inputs": {
    },
  • "driver_type": "humanitec/postgres-cloudsql",
  • "id": "dev-postgres",
  • "is_default": false,
  • "is_deleted": false,
  • "name": "Dev Postgres Instance",
  • "org_id": "test-org",
  • "provision": {
    },
  • "type": "postgres"
}

Update a Resource Definition.

path Parameters
orgId
required
string

The Organization ID.

defId
required
string

The Resource Definition ID.

Request Body schema: application/json

The Resource Definition record details.

The PUT operation updates a resource definition using the provided payload. An empty driver_account or driver_inputs property will unset the existing values.

If driver_type changes and an Active Resource which uses this Resource Definition exists, the resource provisioned with the previous used driver_type will be deleted. As driver_type can't be empty, an empty driver_type means existing value will be used.

Currently the resource can't be changed.

driver_type
string

(Optional) The driver to be used to create the resource.

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

(Optional) Security account required by the driver.

object (ValuesSecretsRefsRequest)

ValuesSecretsRefs stores data that should be passed around split by sensitivity.

name
required
string

The display name.

object

(Optional) A map where the keys are resType#resId (if resId is omitted, the same id of the current resource definition is used) of the resources that should be provisioned when the current resource is provisioned. This also specifies if the resources have a dependency on the current resource or if they have the same dependent resources.

proposed
boolean

(Optional) If true, the new definition version should be created as "proposed" version (not active).

Responses

Request samples

Content type
application/json
{
  • "driver_type": "humanitec/terraform",
  • "driver_account": "gcp-dev-cloudsql",
  • "driver_inputs": {
    },
  • "name": "Dev Postgres Instance",
  • "provision": {
    }
}

Response samples

Content type
application/json
{
  • "created_at": "2020-05-23T12:32:16Z",
  • "created_by": "a.user@example.com",
  • "criteria": [
    ],
  • "driver_account": "gcp-dev-cloudsql",
  • "driver_inputs": {
    },
  • "driver_type": "humanitec/postgres-cloudsql",
  • "id": "dev-postgres",
  • "is_default": false,
  • "is_deleted": false,
  • "name": "Dev Postgres Instance",
  • "org_id": "test-org",
  • "provision": {
    },
  • "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

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

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

Content type
application/json
{
  • "driver_account": "gcp-dev-cloudsql",
  • "driver_inputs": {
    },
  • "provision": {
    }
}

Response samples

Content type
application/json
{
  • "created_at": "2020-05-23T12:32:16Z",
  • "created_by": "a.user@example.com",
  • "criteria": [
    ],
  • "driver_account": "gcp-dev-cloudsql",
  • "driver_inputs": {
    },
  • "driver_type": "humanitec/postgres-cloudsql",
  • "id": "dev-postgres",
  • "is_default": false,
  • "is_deleted": false,
  • "name": "Dev Postgres Instance",
  • "org_id": "test-org",
  • "provision": {
    },
  • "type": "postgres"
}

Update all Matching Criteria of a Resource Definition.

Matching Criteria are combined with Resource Type to select a specific definition. Matching Criteria can be set for any combination of Application ID, Environment ID, Environment Type, and Resource ID. In the event of multiple matches, the most specific match is chosen.

For example, given 3 sets of matching criteria for the same type:

 1. {"env_type":"test"}
 2. {"env_type":"development"}
 3. {"env_type":"test", "app_id":"my-app"}

If, a resource of that type was needed in an Application my-app, Environment qa-team with Type test and Resource ID modules.my-module-externals.my-resource, there would be two resource definitions matching the criteria: #1 & #3. Definition #3 will be chosen because its matching criteria is the most specific.

path Parameters
orgId
required
string

The Organization ID.

defId
required
string

The Resource Definition ID.

Request Body schema: application/json

Matching Criteria rules.

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

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Add a new Matching Criteria to a Resource Definition.

Matching Criteria are combined with Resource Type to select a specific definition. Matching Criteria can be set for any combination of Application ID, Environment ID, Environment Type, and Resource ID. In the event of multiple matches, the most specific match is chosen.

For example, given 3 sets of matching criteria for the same type:

 1. {"env_type":"test"}
 2. {"env_type":"development"}
 3. {"env_type":"test", "app_id":"my-app"}

If, a resource of that type was needed in an Application my-app, Environment qa-team with Type test and Resource ID modules.my-module-externals.my-resource, there would be two resource definitions matching the criteria: #1 & #3. Definition #3 will be chosen because its matching criteria is the most specific.

path Parameters
orgId
required
string

The Organization ID.

defId
required
string

The Resource Definition ID.

Request Body schema: application/json

Matching Criteria rules.

app_id
string

(Optional) The ID of the Application that the Resources should belong to.

class
string

(Optional) The class of the Resource in the Deployment Set. Can not be empty, if is not defined, set to 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

Content type
application/json
{
  • "env_id": "production"
}

Response samples

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

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

Content type
application/json
[
  • {
    }
]

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": {
    },
  • "provision": {
    },
  • "created_at": "2020-05-23T12:32:16Z",
  • "created_by": "a.user@example.com",
  • "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

Content type
application/json
[
  • {
    }
]

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

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": {
    },
  • "provision": {
    },
  • "created_at": "2020-05-23T12:32:16Z",
  • "created_by": "a.user@example.com",
  • "action": "created",
  • "archived": false,
  • "active": true,
  • "proposed": false
}

Mark/unmark the Resource Definition Version as archived.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

defId
required
string
Example: sample-def

The Resource Definition ID.

defVersionId
required
string
Example: 01234567-89ab-cdef-0123-4567890abcdef

The Resource Definition Version ID.

Request Body schema: application/json
archived
boolean

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

Responses

Request samples

Content type
application/json
{
  • "archive": true
}

Response samples

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

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": {
    },
  • "type": "postgres"
}

Lists the resource objects that hold the information needed to provision the resources specified in the request and the resources they depend on. Deprecated

This endpoint is deprecated. Use /orgs/{orgId}/apps/{appId}/envs/{envId}/resources/graphs instead.

path Parameters
orgId
required
string

The Organization ID.

appId
required
string

The Application ID.

envId
required
string

The Environment ID.

Request Body schema: application/json

Resources to provision.

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

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Create a Dependency Graph which is composed by the resource objects that hold the information needed to provision the resources specified in the request and the resources they depend on.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

envId
required
string
Example: development

The Environment ID

Request Body schema: application/json

Resources to provision.

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

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "01234567-89ab-cdef-0123-4567890abcdef",
  • "hash": "string",
  • "nodes": [
    ],
  • "created_at": "2020-06-22T09:37:23.523Z",
  • "used_at": "2020-06-22T09:37:23.523Z"
}

Retrieve a Dependency Graph by its ID.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

envId
required
string
Example: development

The Environment ID

graphId
required
string
Example: 01234567-89ab-cdef-0123-4567890abcdef

The Dependency Graph ID.

Responses

Response samples

Content type
application/json
{
  • "id": "01234567-89ab-cdef-0123-4567890abcdef",
  • "hash": "string",
  • "nodes": [
    ],
  • "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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
[
  • {
    }
]

Create a new Resource Account in the organization.

path Parameters
orgId
required
string

The Organization ID.

query Parameters
dry_run
boolean
Example: dry_run=true

Validate the request but do not persist the change.

check_credential
boolean
Example: check_credential=true

Validate that the Account credential authenticates successfully.

Request Body schema: application/json
required
object

Credentials associated with the account.

id
required
string

Unique identifier for the account (in scope of the organization it belongs to).

name
required
string

Display name.

type
required
string

The type of the account

Responses

Request samples

Content type
application/json
{
  • "credentials": {
    },
  • "id": "gcp-dev-postgres",
  • "name": "GCP Dev Postgres",
  • "type": "gcp-service-account"
}

Response samples

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

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

Content type
application/json
{
  • "details": {
    },
  • "error": "string",
  • "message": "string"
}

Update a Resource Account.

path Parameters
orgId
required
string

The Organization ID.

accId
required
string

The Resource Account ID.

query Parameters
dry_run
boolean
Example: dry_run=true

Validate the request but do not persist the change.

check_credential
boolean
Example: check_credential=true

Validate that the Account credential authenticates successfully.

Request Body schema: application/json
object

Credentials associated with the account.

name
string

Display name.

Responses

Request samples

Content type
application/json
{
  • "credentials": {
    },
  • "name": "GCP Dev Postgres"
}

Response samples

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

Content type
application/json
{
  • "identity_fields": [
    ],
  • "warnings": [
    ]
}

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": {
    },
  • "name": "PostgreSQL",
  • "outputs_schema": {
    },
  • "type": "my-org/postgres",
  • "use": "direct"
}

List Resource Types.

path Parameters
orgId
required
string

The Organization ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

ResourceClass

List resource classes.

path Parameters
orgId
required
string^[a-z0-9][a-z0-9-]+[a-z0-9]$

The organization ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a new resources class.

path Parameters
orgId
required
string^[a-z0-9][a-z0-9-]+[a-z0-9]$

The organization ID.

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

The resource type.

Request Body schema: application/json
id
required
string [ 2 .. 63 ] characters ^[a-z0-9][a-z0-9-]*[a-z0-9]$

ID of the resource class.

description
required
string [ 0 .. 1024 ] characters

A human readable description when this class should be used.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "description": "string"
}

Response samples

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

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
description
required
string [ 0 .. 1024 ] characters

New description for the resource class.

Responses

Request samples

Content type
application/json
{
  • "description": "string"
}

Response samples

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

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": [],
  • "exclude_artefacts_filter": false,
  • "exclude_images_filter": false,
  • "images_filter": [
    ],
  • "match": "^pr-[0-9]+-.*$",
  • "match_ref": "^refs/heads/pr-[0-9]+-.*$",
  • "type": "update",
  • "update_to": "branch"
}

List all Automation Rules in an Environment.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

envId
required
string
Example: development

The Environment ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new Automation Rule for an Environment.

Items marked as deprecated are still supported (however not recommended) for use and are incompatible with properties of the latest api version. In particular an error is raised if images_filter (deprecated) and artefacts_filter are used in the same payload. The same is true for exclude_images_filter (deprecated) and exclude_artefacts_filter. match and update_to are still supported but will trigger an error if combined with match_ref.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

envId
required
string
Example: development

The Environment ID

Request Body schema: application/json

The definition of the Automation Rule.

active
boolean

Whether the rule will be processed or not.

artefacts_filter
Array of strings

A list of artefact names to be processed by the rule. If the array is empty, it implies include all. If exclude_artefacts_filter 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

Content type
application/json
{
  • "active": true,
  • "artefacts_filter": [],
  • "exclude_artefacts_filter": false,
  • "exclude_images_filter": false,
  • "images_filter": [
    ],
  • "match": "^pr-[0-9]+-.*$",
  • "match_ref": "^refs/heads/pr-[0-9]+-.*$",
  • "type": "update",
  • "update_to": "branch"
}

Response samples

Content type
application/json
{
  • "active": true,
  • "artefacts_filter": [],
  • "created_at": "2020-06-22T09:37:23.523Z",
  • "exclude_artefacts_filter": false,
  • "exclude_images_filter": false,
  • "id": "923486d012f20324",
  • "images_filter": [
    ],
  • "match": "^pr-[0-9]+-.*$",
  • "match_ref": "^refs/heads/pr-[0-9]+-.*$",
  • "type": "update",
  • "update_to": "branch",
  • "updated_at": "2020-06-22T09:37:23.523Z"
}

Get a specific Automation Rule for an Environment.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

envId
required
string
Example: development

The Environment ID

ruleId
required
string

The Automation Rule ID.

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "artefacts_filter": [],
  • "created_at": "2020-06-22T09:37:23.523Z",
  • "exclude_artefacts_filter": false,
  • "exclude_images_filter": false,
  • "id": "923486d012f20324",
  • "images_filter": [
    ],
  • "match": "^pr-[0-9]+-.*$",
  • "match_ref": "^refs/heads/pr-[0-9]+-.*$",
  • "type": "update",
  • "update_to": "branch",
  • "updated_at": "2020-06-22T09:37:23.523Z"
}

Update an existing Automation Rule for an Environment.

Items marked as deprecated are still supported (however not recommended) for use and are incompatible with properties of the latest api version. In particular an error is raised if images_filter (deprecated) and artefacts_filter are used in the same payload. The same is true for exclude_images_filter (deprecated) and exclude_artefacts_filter. match and update_to are still supported but will trigger an error if combined with match_ref.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

envId
required
string
Example: development

The Environment ID

ruleId
required
string

The Automation Rule ID.

Request Body schema: application/json

The definition of the Automation Rule.

active
boolean

Whether the rule will be processed or not.

artefacts_filter
Array of strings

A list of artefact names to be processed by the rule. If the array is empty, it implies include all. If exclude_artefacts_filter 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

Content type
application/json
{
  • "active": true,
  • "artefacts_filter": [],
  • "exclude_artefacts_filter": false,
  • "exclude_images_filter": false,
  • "images_filter": [
    ],
  • "match": "^pr-[0-9]+-.*$",
  • "match_ref": "^refs/heads/pr-[0-9]+-.*$",
  • "type": "update",
  • "update_to": "branch"
}

Response samples

Content type
application/json
{
  • "active": true,
  • "artefacts_filter": [],
  • "created_at": "2020-06-22T09:37:23.523Z",
  • "exclude_artefacts_filter": false,
  • "exclude_images_filter": false,
  • "id": "923486d012f20324",
  • "images_filter": [
    ],
  • "match": "^pr-[0-9]+-.*$",
  • "match_ref": "^refs/heads/pr-[0-9]+-.*$",
  • "type": "update",
  • "update_to": "branch",
  • "updated_at": "2020-06-22T09:37:23.523Z"
}

Delete Automation Rule from an Environment.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

envId
required
string
Example: development

The Environment ID

ruleId
required
string

The Automation Rule ID.

Responses

Response samples

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": {
    },
  • "id": "string",
  • "payload": {
    },
  • "triggers": [
    ],
  • "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

Content type
application/json
[
  • {
    }
]

Create a new Webhook

path Parameters
orgId
required
string

The Organization ID.

appId
required
string

The Application ID.

Request Body schema: application/json
disabled
boolean or null

Defines whether this job is currently disabled.

object (JSONFieldRequest)
id
string

Job ID, unique within the Organization

object (JSONFieldRequest)
Array of objects (EventBaseRequest)

A list of Events by which the Job is triggered

url
string or null

The webhook's URL (without protocol, only HTTPS is supported).

Responses

Request samples

Content type
application/json
{
  • "disabled": true,
  • "headers": {
    },
  • "id": "string",
  • "payload": {
    },
  • "triggers": [
    ],
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "2020-06-22T09:37:23.523Z",
  • "created_by": "string",
  • "disabled": true,
  • "headers": {
    },
  • "id": "string",
  • "payload": {
    },
  • "triggers": [
    ],
  • "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

Content type
application/json
{
  • "created_at": "2020-06-22T09:37:23.523Z",
  • "created_by": "string",
  • "disabled": true,
  • "headers": {
    },
  • "id": "string",
  • "payload": {
    },
  • "triggers": [
    ],
  • "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

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

Content type
application/json
{
  • "disabled": true,
  • "headers": {
    },
  • "id": "string",
  • "payload": {
    },
  • "triggers": [
    ],
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "disabled": true,
  • "headers": {
    },
  • "payload": {
    },
  • "triggers": [
    ],
  • "url": "string"
}

List Events

path Parameters
orgId
required
string

The Organization ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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": [
    ],
  • "metadata": {
    }
}

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

Content type
application/json
[
  • {
    }
]

List Pipelines within an Application.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

query Parameters
per_page
integer [ 1 .. 100 ]
Default: 50
Example: per_page=50

The maximum number of items to return in a page of results

page
string
Example: page=AAAAAAAAAA==

The page token to request from

trigger
string
Example: trigger=pipeline_call

An optional filter by trigger type.

object

Optional filter by pipeline metadata

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Pipeline within an Application.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

query Parameters
dry_run
boolean

Optionally validate the request but do not persist the actual Pipeline.

Request Body schema: application/x-yaml
object

Responses

Response samples

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": [
    ],
  • "metadata": {
    }
}

Get a Pipeline within an Application.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

pipelineId
required
string
Example: sample-pipeline

The Pipeline ID

query Parameters
version
string
Example: version=01234567-89ab-cdef-0123-456789abcdef

An optional Pipeline Version ID.

Responses

Response samples

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": [
    ],
  • "metadata": {
    }
}

update a Pipeline within an Application.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

pipelineId
required
string
Example: sample-pipeline

The Pipeline ID

query Parameters
dry_run
boolean

Optionally validate the request but do not persist the update.

header Parameters
If-Match
string
Example: 1234567890abcdef

Indicate that the request should only succeed if there is an etag match

Request Body schema: application/x-yaml
object

Responses

Response samples

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": [
    ],
  • "metadata": {
    }
}

Delete a pipeline within an application.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

pipelineId
required
string
Example: sample-pipeline

The Pipeline ID

header Parameters
If-Match
string
Example: 1234567890abcdef

Indicate that the request should only succeed if there is an etag match

Responses

Response samples

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^[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

Content type
application/json
[
  • {
    }
]

Get a pipeline schema.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

pipelineId
required
string
Example: sample-pipeline

The Pipeline ID

query Parameters
version
string
Example: version=01234567-89ab-cdef-0123-456789abcdef

An optional Pipeline Version ID.

header Parameters
Accept
string

Responses

Response samples

Content type
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^[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

Content type
application/json
[
  • {
    }
]

Create a new trigger matching criteria for this Pipeline.

Create a new trigger matching criteria for this Pipeline. This must not conflict with an existing criteria for the same trigger on this or any other Pipeline that applies to this Application.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

pipelineId
required
string
Example: sample-pipeline

The Pipeline ID

Request Body schema: application/json
env_type
string

The Environment Type that this criteria will match. If defined, this criteria will only apply to Environments that have this type.

app_id
string

The id of the Application for which this criteria matches. If this Pipeline is defined in an Application, then this value can only be null or the id of the Application.

env_id
string

The exact id of the Environment which this criteria will match.

deployment_type
string

The type of deployment that this criteria will match. Valid values are "deploy" and "redeploy". "redeploy" applies only to deployment request to redeploy a previous deployment id while "deploy" will apply to all other requests that include a Delta or Deployment Set. If not defined, all deployment types will match.

Responses

Request samples

Content type
application/json
{
  • "env_type": "development",
  • "app_id": "my-application",
  • "env_id": "my-environment",
  • "deployment_type": "deploy",
  • "trigger": "deployment_request"
}

Response samples

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^[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

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^[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

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

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^[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

Content type
application/json
{
  • "items": [
    ],
  • "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": [
    ],
  • "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": {
    },
  • "run_as": "s-01234567-89ab-cdef-0123-456789abcdef",
  • "concurrency_group": "my-group",
  • "waiting_for": {
    }
}

List all pipeline runs within the Org. This can be filtered by app, pipeline, and status.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

query Parameters
app
Array of strings
Example: app=sample-app

An optional list of Application IDs.

pipeline
Array of strings
Example: pipeline=sample-pipeline

An optional list of Pipeline IDs.

env
string
Example: env=development

An optional Environment ID

status
Array of strings
Example: status=executing

Optional filter by status.

completed
boolean
Example: completed=true

Optional filer by completed or not.

created_after
string <date-time>
Example: created_after=2018-03-20T09:12:28Z

Optional filter by creation after date time.

created_before
string <date-time>
Example: created_before=2018-03-20T09:12:28Z

Optional filter by creation before date time

per_page
integer [ 1 .. 100 ]
Default: 50
Example: per_page=50

The maximum number of items to return in a page of results

page
string
Example: page=AAAAAAAAAA==

The page token to request from

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a Pipeline Run in the appropriate Pipeline based on the trigger and inputs.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

query Parameters
dry_run
boolean

Optionally validate the request but do not persist the actual Pipeline Run.

header Parameters
Idempotency-Key
string
Example: 0xr$P0Cu4@DB

The HTTP Idempotency-Key

Request Body schema: application/json
env_id
string

The target environment within the Application to deploy to.

environment
string
Deprecated

The target environment within the Application to deploy to.

delta_id
string

A deployment delta to apply to the target environment. This delta must already exist. This field is mutually exclusive with "deployment_id" and "set_id".

deployment_id
string

An existing deployment to redeploy into the target environment. The deployment set and value set will be copied. This field is mutually exclusive with "delta_id" and "set_id".

set_id
string

A direct deployment set to apply to the target environment. This deployment set must already exist. This field is mutually exclusive with "delta_id" and "set_id".

value_set_version_id
string

The exact value set version to use when deploying to the target environment. This value set version must exist. This field can only be used when "delta_id" or "set_id" is specified.

comment
string

An optional comment to apply to the Deployment.

Responses

Request samples

Content type
application/json
{
  • "trigger": "deployment_request",
  • "env_id": "development",
  • "delta_id": "0123456789abcdef0123456789abcdef01234567",
  • "comment": "My deployment"
}

Response samples

Content type
application/json
{
  • "id": "01234567-89ab-cdef-0123-456789abcdef",
  • "etag": "1234567890abcdef",
  • "org_id": "sample-org",
  • "app_id": "sample-app",
  • "env_ids": [
    ],
  • "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": {
    },
  • "run_as": "s-01234567-89ab-cdef-0123-456789abcdef",
  • "concurrency_group": "my-group",
  • "waiting_for": {
    }
}

List runs within a pipeline.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

pipelineId
required
string
Example: sample-pipeline

The Pipeline ID

query Parameters
env
string
Example: env=development

An optional Environment ID

status
Array of strings
Example: status=executing

Optional filter by status.

completed
boolean
Example: completed=true

Optional filer by completed or not.

created_after
string <date-time>
Example: created_after=2018-03-20T09:12:28Z

Optional filter by creation after date time.

created_before
string <date-time>
Example: created_before=2018-03-20T09:12:28Z

Optional filter by creation before date time

per_page
integer [ 1 .. 100 ]
Default: 50
Example: per_page=50

The maximum number of items to return in a page of results

page
string
Example: page=AAAAAAAAAA==

The page token to request from

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a run within a pipeline.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

pipelineId
required
string
Example: sample-pipeline

The Pipeline ID

query Parameters
dry_run
boolean

Optionally validate the request but do not persist the actual Pipeline Run.

header Parameters
Idempotency-Key
string
Example: 0xr$P0Cu4@DB

The HTTP Idempotency-Key

Request Body schema: application/json
required
object

The inputs provided for this Run.

Responses

Request samples

Content type
application/json
{
  • "inputs": {
    }
}

Response samples

Content type
application/json
{
  • "id": "01234567-89ab-cdef-0123-456789abcdef",
  • "etag": "1234567890abcdef",
  • "org_id": "sample-org",
  • "app_id": "sample-app",
  • "env_ids": [
    ],
  • "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": {
    },
  • "run_as": "s-01234567-89ab-cdef-0123-456789abcdef",
  • "concurrency_group": "my-group",
  • "waiting_for": {
    }
}

Get a run within an pipeline.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

pipelineId
required
string
Example: sample-pipeline

The Pipeline ID

runId
required
string
Example: 01234567-89ab-cdef-0123-456789abcdef

The Run ID

Responses

Response samples

Content type
application/json
{
  • "id": "01234567-89ab-cdef-0123-456789abcdef",
  • "etag": "1234567890abcdef",
  • "org_id": "sample-org",
  • "app_id": "sample-app",
  • "env_ids": [
    ],
  • "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": {
    },
  • "run_as": "s-01234567-89ab-cdef-0123-456789abcdef",
  • "concurrency_group": "my-group",
  • "waiting_for": {
    }
}

Deleting a completed Run within a Pipeline.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

pipelineId
required
string
Example: sample-pipeline

The Pipeline ID

runId
required
string
Example: 01234567-89ab-cdef-0123-456789abcdef

The Run ID

header Parameters
If-Match
string
Example: 1234567890abcdef

Indicate that the request should only succeed if there is an etag match

Responses

Response samples

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^[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

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^[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

Content type
application/json
{
  • "id": "01234567-89ab-cdef-0123-456789abcdef",
  • "etag": "1234567890abcdef",
  • "org_id": "sample-org",
  • "app_id": "sample-app",
  • "env_ids": [
    ],
  • "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": {
    },
  • "run_as": "s-01234567-89ab-cdef-0123-456789abcdef",
  • "concurrency_group": "my-group",
  • "waiting_for": {
    }
}

List the details of the jobs within a pipeline run.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

pipelineId
required
string
Example: sample-pipeline

The Pipeline ID

runId
required
string
Example: 01234567-89ab-cdef-0123-456789abcdef

The Run ID

query Parameters
status
Array of strings
Example: status=executing

Optional filter by status.

per_page
integer [ 1 .. 100 ]
Default: 50
Example: per_page=50

The maximum number of items to return in a page of results

page
string
Example: page=AAAAAAAAAA==

The page token to request from

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List the details of a Job including Step information

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

pipelineId
required
string
Example: sample-pipeline

The Pipeline ID

runId
required
string
Example: 01234567-89ab-cdef-0123-456789abcdef

The Run ID

jobId
required
string
Example: deploy

The Job ID

Responses

Response samples

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

Get a page of log output for a given step within a job.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

pipelineId
required
string
Example: sample-pipeline

The Pipeline ID

runId
required
string
Example: 01234567-89ab-cdef-0123-456789abcdef

The Run ID

jobId
required
string
Example: deploy

The Job ID

stepIndex
required
integer

The index of the step within the Job

query Parameters
page
string
Example: page=AAAAAAAAAA==

The page token to request from

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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^[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

Content type
application/json
[
  • {
    }
]

Get an approval request

Get an approval request.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-app

The Application ID

pipelineId
required
string
Example: sample-pipeline

The Pipeline ID

runId
required
string
Example: 01234567-89ab-cdef-0123-456789abcdef

The Run ID

jobId
required
string
Example: deploy

The Job ID

approvalId
required
string
Example: 01234567-89ab-cdef-0123-456789abcdef

The Approval ID

Responses

Response samples

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^[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

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^[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

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": "jo.trigg@awesomecorp.com",
  • "id": "d510224a-4641-48fd-8054-68efd3537ee2",
  • "name": "Jo Trigg",
  • "type": "user"
}

Gets the extended profile of the current user

Responses

Response samples

Content type
application/json
{
  • "created_at": "2020-12-19T09:32:46Z",
  • "email": "jo.trigg@awesomecorp.com",
  • "id": "d510224a-4641-48fd-8054-68efd3537ee2",
  • "name": "Jo Trigg",
  • "properties": {
    }
}

Updates the extended profile of the current user.

Request Body schema: application/json
created_at
string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...

The time the user was first registered with Humanitec

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

Content type
application/json
{
  • "created_at": "2020-12-19T09:32:46Z",
  • "email": "jo.trigg@awesomecorp.com",
  • "id": "d510224a-4641-48fd-8054-68efd3537ee2",
  • "name": "Jo Trigg",
  • "properties": {
    }
}

Response samples

Content type
application/json
{
  • "created_at": "2020-12-19T09:32:46Z",
  • "email": "jo.trigg@awesomecorp.com",
  • "id": "d510224a-4641-48fd-8054-68efd3537ee2",
  • "name": "Jo Trigg",
  • "properties": {
    }
}

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

Content type
application/json
{
  • "name": "CI Robot",
  • "role": "manager"
}

Response samples

Content type
application/json
{
  • "created_at": "2020-12-19T09:32:46Z",
  • "email": "jo.trigg@awesomecorp.com",
  • "id": "d510224a-4641-48fd-8054-68efd3537ee2",
  • "name": "Jo Trigg",
  • "type": "user"
}

User Roles

UserRole holds the mapping of role to user for a particular object.

role
string

The role that this user holds

user
string

The user ID that hold the role

created_at
string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...

The time the user was first registered with Humanitec

email
string

The email address of the user from the profile

id
string

The User ID for this user

invite
string

The status of an invitation (If applicable)

name
string

The name the user goes by

type
string

The type of the account. Could be user, service or system

{
  • "role": "manager",
  • "user": "61048226-642c-438e-974f-ce5c013d94f8",
  • "created_at": "2020-12-19T09:32:46Z",
  • "email": "jo.trigg@awesomecorp.com",
  • "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
  • "invite": "accepted",
  • "name": "Jo Trigg",
  • "type": "user"
}

List Users with roles in an App

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string

The Application ID.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Adds a User to an Application with a Role

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string

The Application ID.

Request Body schema: application/json

The user ID and the role

role
string

The role that this user holds

user
string

The user ID that hold the role

created_at
string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...

The time the user was first registered with Humanitec

email
string

The email address of the user from the profile

id
string

The User ID for this user

invite
string

The status of an invitation (If applicable)

name
string

The name the user goes by

type
string

The type of the account. Could be user, service or system

Responses

Request samples

Content type
application/json
{
  • "id": "61048226-642c-438e-974f-ce5c013d94f8",
  • "role": "manager"
}

Response samples

Content type
application/json
{
  • "role": "manager",
  • "user": "61048226-642c-438e-974f-ce5c013d94f8",
  • "created_at": "2020-12-19T09:32:46Z",
  • "email": "jo.trigg@awesomecorp.com",
  • "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
  • "invite": "accepted",
  • "name": "Jo Trigg",
  • "type": "user"
}

Get the role of a User on an Application

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string

The Application ID.

userId
required
string

The User ID

Responses

Response samples

Content type
application/json
{
  • "role": "manager",
  • "user": "61048226-642c-438e-974f-ce5c013d94f8",
  • "created_at": "2020-12-19T09:32:46Z",
  • "email": "jo.trigg@awesomecorp.com",
  • "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
  • "invite": "accepted",
  • "name": "Jo Trigg",
  • "type": "user"
}

Remove the role of a User on an Application

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string

The Application ID.

userId
required
string

The User ID

Responses

Response samples

Content type
application/json
{
  • "error": "API-000",
  • "message": "Could not validate token."
}

Update the role of a User on an Application

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

appId
required
string

The Application ID.

userId
required
string

The User ID

Request Body schema: application/json

The new user role

role
string

Responses

Request samples

Content type
application/json
{
  • "role": "user"
}

Response samples

Content type
application/json
{
  • "role": "manager",
  • "user": "61048226-642c-438e-974f-ce5c013d94f8",
  • "created_at": "2020-12-19T09:32:46Z",
  • "email": "jo.trigg@awesomecorp.com",
  • "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
  • "invite": "accepted",
  • "name": "Jo Trigg",
  • "type": "user"
}

List Users with roles in an Environment Type

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

envType
required
string

The Environment Type.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Adds a User to an Environment Type with a Role

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

envType
required
string

The Environment Type.

Request Body schema: application/json

The user ID and the role

role
string

The role that this user holds

user
string

The user ID that hold the role

created_at
string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...

The time the user was first registered with Humanitec

email
string

The email address of the user from the profile

id
string

The User ID for this user

invite
string

The status of an invitation (If applicable)

name
string

The name the user goes by

type
string

The type of the account. Could be user, service or system

Responses

Request samples

Content type
application/json
{
  • "id": "61048226-642c-438e-974f-ce5c013d94f8",
  • "role": "manager"
}

Response samples

Content type
application/json
{
  • "role": "manager",
  • "user": "61048226-642c-438e-974f-ce5c013d94f8",
  • "created_at": "2020-12-19T09:32:46Z",
  • "email": "jo.trigg@awesomecorp.com",
  • "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
  • "invite": "accepted",
  • "name": "Jo Trigg",
  • "type": "user"
}

Get the role of a User on an Environment Type

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

envType
required
string

The Environment Type.

userId
required
string

The User ID

Responses

Response samples

Content type
application/json
{
  • "role": "manager",
  • "user": "61048226-642c-438e-974f-ce5c013d94f8",
  • "created_at": "2020-12-19T09:32:46Z",
  • "email": "jo.trigg@awesomecorp.com",
  • "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
  • "invite": "accepted",
  • "name": "Jo Trigg",
  • "type": "user"
}

Remove the role of a User on an Environment Type

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

envType
required
string

The Environment Type.

userId
required
string

The User ID

Responses

Response samples

Content type
application/json
{
  • "error": "API-000",
  • "message": "Could not validate token."
}

Update the role of a User on an Environment Type

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

envType
required
string

The Environment Type.

userId
required
string

The User ID

Request Body schema: application/json

The new user role

role
string

Responses

Request samples

Content type
application/json
{
  • "role": "user"
}

Response samples

Content type
application/json
{
  • "role": "manager",
  • "user": "61048226-642c-438e-974f-ce5c013d94f8",
  • "created_at": "2020-12-19T09:32:46Z",
  • "email": "jo.trigg@awesomecorp.com",
  • "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
  • "invite": "accepted",
  • "name": "Jo Trigg",
  • "type": "user"
}

Invites a user to an Organization with a specified role.

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

Request Body schema: application/json

The email and the desired role

email
required
string

The email address of the user from the profile.

role
required
string

The role that this user would hold.

Responses

Request samples

Content type
application/json
{
  • "email": "jane.gonzales@example.com",
  • "role": "manager"
}

Response samples

Content type
application/json
[
  • {
    }
]

List Users with roles in an Organization

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the role of a User on an Organization

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

userId
required
string

The User ID

Responses

Response samples

Content type
application/json
{
  • "role": "manager",
  • "user": "61048226-642c-438e-974f-ce5c013d94f8",
  • "created_at": "2020-12-19T09:32:46Z",
  • "email": "jo.trigg@awesomecorp.com",
  • "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
  • "invite": "accepted",
  • "name": "Jo Trigg",
  • "type": "user"
}

Remove the role of a User on an Organization

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

userId
required
string

The User ID

Responses

Response samples

Content type
application/json
{
  • "error": "API-000",
  • "message": "Could not validate token."
}

Update the role of a User on an Organization

path Parameters
orgId
required
string <= 50 characters ^[a-z0-9](?:-?[a-z0-9]+)+$
Example: sample-org

The Organization ID

userId
required
string

The User ID

Request Body schema: application/json

The new user the role

role
string

Responses

Request samples

Content type
application/json
{
  • "role": "user"
}

Response samples

Content type
application/json
{
  • "role": "manager",
  • "user": "61048226-642c-438e-974f-ce5c013d94f8",
  • "created_at": "2020-12-19T09:32:46Z",
  • "email": "jo.trigg@awesomecorp.com",
  • "id": "730c1f96-8ee5-4bff-8c22-898e0530b924",
  • "invite": "accepted",
  • "name": "Jo Trigg",
  • "type": "user"
}

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

Content type
application/json
[
  • {
    }
]

Creates a new static token for a user.

This is only supported for users of type service.

path Parameters
userId
required
string

The user ID.

Request Body schema: application/json

The definition of the token.

description
string

A description of the token. (Optional)

expires_at
string (Simplified extended ISO format date/time string.) ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}...

The time the token expires. If not set, the token will not expire. (Optional)

id
required
string

Identifier of the token. Must be unique for the user.

type
required
string

The type of the token. Can only be "static".

Responses

Request samples

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

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

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.

Responses