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