Humanitec Public API

Number of APIs: 104

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. Humanitec provides 2 ways of authenticating with the API: Bearer and JWT.

Bearer Authentication

This form of authentication makes use of a static token. It is intended to be used when machines interact with the Humanitec API. Bearer tokens should be used for very narrow purposes. This allows for the token to be revoked if it is compromised and so limit the scope of exposure. New Bearer tokens can be obtained via the UI:

  1. Log into Humanitec at https://app.humanitec.io
  2. Go to Organization Settings
  3. Select API tokens
  4. Enter a name for the new token and click on Generate new token

The token is passed to the API via the Authorization header. Assuming the issued token is HUMANITEC_TOKEN, the request could be made as follows:

    curl -H 'Authorization: Bearer HUMANITEC_TOKEN' https://api.humanitec.io/orgs/my-org/apps

JWT Authentication

This form of authentication makes use of a JSON Web Token (JWT). It is intended to be used when humans interact with the Humanitec API. JWTs expire after a period of time. This means that a new JWT will need to be generated regularly. This makes them well suited to working in short sessions, but not for automation. (See Bearer Authentication.) The token is passed to the API via the Authorization header. Assuming the issued token is HUMANITEC_JWT, the request could be made as follows:

    curl -H 'Authorization: JWT HUMANITEC_JWT' https://api.humanitec.io/orgs/my-org/apps

Content Types

All of the Humanitec API unless explicitly 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.

CodeMeaning
200Success
201Success (In future, 201 will be replaced by 200)
204Success, 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 should be regarded as an error which can be rectified by the client. 5xx error codes indicate errors that cannot be corrected by the client.

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

Contact Support: Name: API Support Email: apiteam@humanitec.com

  1. orgs-{org Id}-apps-{app Id}-envs-{env Id}-runtime - Get a Runtime information for the environment GET {{baseUrl}}/orgs/:orgId/apps/:appId/envs/:envId/runtime

  2. orgs-{org Id}-apps-{app Id}-envs-{env Id}-runtime - Set number of replicas for the environment's modules PATCH {{baseUrl}}/orgs/:orgId/apps/:appId/envs/:envId/runtime/replicas

  3. orgs-{org Id}-apps-{app Id}-envs-{env Id}-values-{key} - Update Shared Value for an Environment PUT {{baseUrl}}/orgs/:orgId/apps/:appId/envs/:envId/values/:key

  4. orgs-{org Id}-apps-{app Id}-envs-{env Id}-values-{key} - Delete Shared Value for an Environment DELETE {{baseUrl}}/orgs/:orgId/apps/:appId/envs/:envId/values/:key

  5. orgs-{org Id}-apps-{app Id}-envs-{env Id}-values - List Shared Values in an Environment GET {{baseUrl}}/orgs/:orgId/apps/:appId/envs/:envId/values

  6. orgs-{org Id}-apps-{app Id}-envs-{env Id}-values - Create a Shared Value for an Environment POST {{baseUrl}}/orgs/:orgId/apps/:appId/envs/:envId/values

  7. orgs-{org Id}-apps-{app Id}-values-{key} - Delete Shared Value for an Application DELETE {{baseUrl}}/orgs/:orgId/apps/:appId/values/:key

  8. orgs-{org Id}-apps-{app Id}-values - List Shared Values in an Application GET {{baseUrl}}/orgs/:orgId/apps/:appId/values

  9. orgs-{org Id}-apps-{app Id}-values - Create a Shared Value for an Application POST {{baseUrl}}/orgs/:orgId/apps/:appId/values

  10. orgs-{org Id}-apps-{app Id} - Delete an Application DELETE {{baseUrl}}/orgs/:orgId/apps/:appId