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:
- Log into Humanitec at https://app.humanitec.io
- Go to Organization Settings
- Select API tokens
- 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.
Code | Meaning |
---|---|
200 | Success |
201 | Success (In future, 201 will be replaced by 200 ) |
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
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.
Code | Meaning |
---|---|
400 | General error. (Body will contain details) |
401 | Attempt to access protected resource without Authorization Header. |
403 | The Bearer or JWT does not grant access to the requested resource. |
404 | Resource not found. |
405 | Method not allowed |
409 | Conflict. Usually indicated a resource with that ID already exists. |
422 | Unprocessable Entity. The body was not valid JSON, was empty or contained an object different from what was expected. |
429 | Too many requests - request rate limit has been reached. |
500 | Internal Error. If it occurs repeatedly, contact support. |
Contact Support: Name: API Support Email: apiteam@humanitec.com
-
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
-
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
-
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
-
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
-
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
-
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
-
orgs-{org Id}-apps-{app Id}-values-{key} - Delete Shared Value for an Application DELETE {{baseUrl}}/orgs/:orgId/apps/:appId/values/:key
-
orgs-{org Id}-apps-{app Id}-values - List Shared Values in an Application GET {{baseUrl}}/orgs/:orgId/apps/:appId/values
-
orgs-{org Id}-apps-{app Id}-values - Create a Shared Value for an Application POST {{baseUrl}}/orgs/:orgId/apps/:appId/values
-
orgs-{org Id}-apps-{app Id} - Delete an Application DELETE {{baseUrl}}/orgs/:orgId/apps/:appId