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.
openapi: 3.0.0
info:
title: Humanitec AccountType Application API
version: 0.28.24
description: '# 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](https://developer.humanitec.com/platform-orchestrator/reference/api-references/#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. |
'
contact:
name: Humanitec Support
email: support@humanitec.com
x-logo:
url: humanitec-logo.png
altText: Humanitec logo
servers:
- url: https://api.humanitec.io/
tags:
- name: Application
x-displayName: Applications
description: '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.
<SchemaDefinition schemaRef="#/components/schemas/ApplicationRequest" />
'
paths:
/orgs/{orgId}/apps:
get:
tags:
- Application
summary: List all Applications in an Organization.
operationId: listApplications
description: Listing or lists of all Applications that exist within a specific Organization.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
responses:
'200':
description: Possibly empty list of Applications.
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ApplicationResponse'
type: array
example:
- created_at: '2020-06-15T09:32:03Z'
created_by: a-user@example.com
envs:
id: development
name: Development
type: development
id: my-app
name: My Awesome App
post:
tags:
- Application
summary: Add a new Application to an Organization
operationId: createApplication
description: Creates a new Application, then adds it to the specified Organization.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
requestBody:
description: 'The request ID, Human-friendly name and environment of the Application.
'
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationCreationRequest'
responses:
'201':
description: 'The Application requested.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationResponse'
example:
created_at: '2020-06-15T09:32:03Z'
created_by: a-user@example.com
envs:
id: development
name: Development
type: development
id: my-app
name: My Awesome App
'400':
description: 'The request body was unparseable.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'401':
description: 'The Authorization header was not present or invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'409':
description: 'The supplied `id` clashes with an existing Application.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
/orgs/{orgId}/apps/{appId}:
get:
tags:
- Application
summary: Get an existing Application
operationId: getApplication
description: Gets a specific Application in the specified Organization by ID.
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: appId
in: path
description: 'The Application ID.
'
required: true
schema:
type: string
responses:
'200':
description: 'The Application requested.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationResponse'
example:
created_at: '2020-06-15T09:32:03Z'
created_by: a-user@example.com
envs:
id: development
name: Development
type: development
id: my-app
name: My Awesome App
'404':
description: 'No Application with ID `appId` in Organization.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
patch:
tags:
- Application
summary: Update metadata of an existing Application
operationId: patchApplication
description: Update metadata of an existing Application in the specified Organization.
parameters:
- $ref: '#/components/parameters/orgIdPathParam'
- $ref: '#/components/parameters/appIdPathParam'
requestBody:
description: The Application patch request. Only the field `name` can be updated.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationPatchPayload'
responses:
'200':
description: Application updated.
content:
application/json:
schema:
$ref: '#/components/schemas/ApplicationResponse'
example:
created_at: '2020-06-15T09:32:03Z'
created_by: a-user@example.com
envs:
id: development
name: Development
type: development
id: my-app
name: My Awesome App
'404':
description: No Application with ID `appId` in Organization.
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
delete:
tags:
- Application
summary: Delete an Application
operationId: deleteApplication
description: '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._'
parameters:
- name: orgId
in: path
description: 'The Organization ID.
'
required: true
schema:
type: string
- name: appId
in: path
description: 'The Application ID.
'
required: true
schema:
type: string
responses:
'204':
description: 'Application Successfully deleted.
'
'202':
description: 'Application deletion is in progress.
'
'401':
description: 'The Authorization header was not present or invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
'404':
description: 'No Application with `id` in Organization.
'
content:
application/json:
schema:
$ref: '#/components/schemas/HumanitecErrorResponse'
components:
schemas:
EnvironmentBaseResponse:
properties:
id:
description: The ID the Environment is referenced as.
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
type: string
name:
description: The Human-friendly name for the Environment.
type: string
type:
description: The Environment Type. This is used for organizing and managing Environments.
type: string
required:
- id
- name
- type
type: object
EnvironmentBaseRequest:
properties:
id:
description: The ID the Environment is referenced as.
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
maxLength: 50
type: string
name:
description: The Human-friendly name for the Environment.
type: string
type:
description: The Environment Type. This is used for organizing and managing Environments.
type: string
required:
- id
- name
- type
type: object
HumanitecErrorResponse:
description: HumanitecError represents a standard Humanitec Error
properties:
details:
additionalProperties: true
type: object
description: (Optional) Additional information is enclosed here.
error:
type: string
example: API-000
description: A short code to help with error identification.
message:
type: string
example: Could not validate token
description: A Human readable message about the error.
required:
- error
- message
type: object
example:
error: API-000
message: Could not validate token.
ApplicationCreationRequest:
properties:
env:
$ref: '#/components/schemas/EnvironmentBaseRequest'
description: The Environment that will be automatically created with application. If not provided, default environment will be created instead.
id:
description: The ID which refers to a specific application.
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
maxLength: 50
type: string
name:
description: The Human-friendly name for the Application.
type: string
skip_environment_creation:
description: If true, no environment will be created with the application.
type: boolean
required:
- id
- name
type: object
ApplicationPatchPayload:
description: Patch request body to update Application metadata.
example:
description: Example Environment Type description
properties:
name:
description: The Human-friendly name for the Application.
type: string
required:
- name
additionalProperties: false
type: object
ApplicationResponse:
description: '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.'
example:
created_at: '2020-05-22T14:53:27Z'
created_by: a.user@example.com
status: active
status_changed_at: '2020-05-22T14:53:27Z'
envs:
- id: my-env
name: My Environment
id: my-app
name: My Application
properties:
created_at:
description: The timestamp in UTC indicates when the Application was created.
example: '2020-06-22T09:37:23.523Z'
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{3})?Z$
title: Simplified extended ISO format date/time string.
type: string
created_by:
description: The user who created the Application.
type: string
envs:
description: The Environments associated with the Application.
items:
$ref: '#/components/schemas/EnvironmentBaseResponse'
type: array
id:
description: The ID which refers to a specific application.
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
type: string
name:
description: The Human-friendly name for the Application.
type: string
org_id:
description: The Organization id of this Application
type: string
status:
description: The status of the application
type: string
enum:
- active
- deleting
status_changed_at:
description: The timestamp in UTC of when the Environment status was last changed.
example: '2020-06-22T09:37:23.523Z'
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{3})?Z$
title: Simplified extended ISO format date/time string.
format: date-time
type: string
status_message:
description: The message associated with the status of the environment
type: string
required:
- id
- name
- org_id
- created_at
- created_by
- envs
- status
- status_changed_at
type: object
parameters:
orgIdPathParam:
name: orgId
in: path
description: The Organization ID
example: sample-org
required: true
schema:
type: string
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
maxLength: 50
appIdPathParam:
name: appId
in: path
description: The Application ID
required: true
example: sample-app
schema:
pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
type: string
maxLength: 50
externalDocs:
description: Find out more about how to use Humanitec in your every-day development work.
url: https://developer.humanitec.com/
x-tagGroups:
- name: Core
tags:
- Agents
- Application
- Artefact
- ArtefactVersion
- AuditLogs
- Logs
- Deployment
- EnvironmentType
- Environment
- Image
- PublicKeys
- Organization
- Registry
- RuntimeInfo
- SecretStore
- Value
- ValueSetVersion
- name: App Configuration
tags:
- Delta
- Set
- WorkloadProfile
- name: Resources
tags:
- ActiveResource
- DriverDefinition
- MatchingCriteria
- ResourceDefinition
- ResourceDefinitionVersion
- ResourceProvision
- AccountType
- ResourceAccount
- ResourceType
- ResourceClass
- name: Automation
tags:
- AutomationRule
- Event
- Pipelines
- PipelineRuns
- PipelineApprovals
- name: Users
tags:
- UserProfile
- UserRole
- Group
- TokenInfo