Humanitec public API

openapi: 3.2.0
info:
  title: Humanitec Public 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: public
paths:
  /orgs/{orgId}/apps:
    get:
      tags:
      - public
      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:
      - public
      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:
      - public
      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:
      - public
      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:
      - public
      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'
  /orgs/{orgId}/apps/{appId}/envs:
    get:
      tags:
      - public
      summary: List all Environments.
      operationId: listEnvironments
      description: Lists all of the Environments in the Application.
      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: 'A list of Environments associated with an Application.


            '
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/EnvironmentResponse'
                type: array
              example:
              - {}
    post:
      tags:
      - public
      summary: Add a new Environment to an Application.
      operationId: createEnvironment
      description: '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.'
      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
      requestBody:
        description: 'The ID, Name, Type, and Deployment the Environment will be derived from.


          '
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentDefinitionRequest'
            example:
              from_deploy_id: e80db1a327208c1a
              id: awesome-feature
              name: Awesome Feature Dev
              namespace: awesome-namespace
              type: development
      responses:
        '201':
          description: 'The new Environment.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentResponse'
              example: {}
        '400':
          description: 'The supplied `id` is an invalid ID or a required field is missing.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'No Application with `id` in Organization.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '409':
          description: 'The supplied `id` clashes with an existing Environment.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/apps/{appId}/envs/{envId}:
    get:
      tags:
      - public
      summary: Get a specific Environment.
      operationId: getEnvironment
      description: Gets a specific Environment in an Application.
      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
      - name: envId
        in: path
        description: 'The Environment ID.


          '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'The Environment requested.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentResponse'
              example: {}
        '404':
          description: 'No Environment with `id` in Application.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
    patch:
      tags:
      - public
      summary: Update a specific Environment.
      operationId: updateEnvironment
      description: Update a specific Environment in an Application.
      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
      - name: envId
        in: path
        description: 'The Environment ID.


          '
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentBaseUpdateRequest'
      responses:
        '200':
          description: 'The updated Environment.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentResponse'
              example: {}
        '404':
          description: 'No Environment with `id` in Application.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
    delete:
      tags:
      - public
      summary: Delete a specific Environment.
      operationId: deleteEnvironment
      description: 'Deletes a specific Environment in an Application.


        Deleting an Environment will also delete the Deployment history of the Environment.


        _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
      - name: envId
        in: path
        description: 'The Environment ID.


          '
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'Environment successfully deleted.


            '
        '202':
          description: 'Environment deletion is in progress.


            '
        '400':
          description: 'Attempt to delete the last Environment in an Application.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'No Environment with `envId` in Application.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/apps/{appId}/envs/{envId}/deploys:
    get:
      tags:
      - public
      summary: List Deployments in an Environment.
      description: List all of the Deployments that have been carried out in the current Environment. Deployments are returned with the newest first.
      operationId: listDeployments
      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
      - name: envId
        in: path
        description: 'The Environment ID.


          '
        required: true
        schema:
          type: string
      - name: pipelineRunId
        in: query
        description: 'An optional filter by the Pipeline and Pipeline Run ID separated by a comma.

          '
        example: default,01234567-89ab-cdef-0123-456789abcdef
        schema:
          type: string
      responses:
        '200':
          description: 'A possibly empty list of Deployments.


            '
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DeploymentResponse'
                type: array
              example:
              - {}
        '404':
          description: 'No Environment with `id` in Application.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
    post:
      tags:
      - public
      summary: Start a new Deployment.
      operationId: createDeployment
      description: '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.'
      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
      - name: envId
        in: path
        description: 'The Environment ID.


          '
        required: true
        schema:
          type: string
      requestBody:
        description: 'The Delta describing the change to the Environment and a comment.


          '
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentRequest'
            example:
              comment: Updated version of module-one to v0.3.1
              delta_id: df1ad41807b0390a9b0eaf8688e1f5baece9d764
      responses:
        '201':
          description: 'A description of the Deployment.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentResponse'
        '400':
          description: 'Error because the Delta is non-existent or incompatible with the state of the Environment.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'No Environment with `id` in Application.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '409':
          description: 'There is already an active deployment in the Environment.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/apps/{appId}/envs/{envId}/deploys/{deployId}:
    get:
      tags:
      - public
      summary: Get a specific Deployment.
      description: Gets a specific Deployment in an Application and an Environment.
      operationId: getDeployment
      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
      - name: envId
        in: path
        description: 'The Environment ID.


          '
        required: true
        schema:
          type: string
      - name: deployId
        in: path
        description: 'The Deployment ID.


          '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'The Deployment requested.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentResponse'
              example: {}
        '404':
          description: 'No Deployment with `deployId` in Application and Environment.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/apps/{appId}/envs/{envId}/deploys/{deployId}/errors:
    get:
      tags:
      - public
      summary: List errors that occurred in a Deployment.
      operationId: listDeploymentErrors
      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
      - name: envId
        in: path
        description: 'The Environment ID.


          '
        required: true
        schema:
          type: string
      - name: deployId
        in: path
        description: 'The Deployment ID.


          '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'A List of deployment errors, could be empty.


            '
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DeploymentErrorResponse'
                type: array
              example:
              - code: CLD-001
                message: Incorrect credentials
                object_id: my-service
                scope: workload
  /orgs/{orgId}/apps/{appId}/envs/{envId}/from_deploy_id:
    put:
      tags:
      - public
      summary: Rebase to a different Deployment.
      operationId: rebaseEnvironment
      description: '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.'
      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
      - name: envId
        in: path
        description: 'The Environment ID.


          '
        required: true
        schema:
          type: string
      requestBody:
        description: 'The Deployment ID to rebase to.


          '
        required: true
        content:
          application/json:
            schema:
              type: string
      responses:
        '204':
          description: 'Rebase successful.


            '
        '400':
          description: 'No Deployment with ID found in Application.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'No Environment with ID found in Application and Organization.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/env-types:
    get:
      tags:
      - public
      summary: List all Environment Types
      operationId: listEnvironmentTypes
      description: Lists all Environment Types in an Organization.
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'A list of Environment Types.


            '
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/EnvironmentTypeResponse'
                type: array
    post:
      tags:
      - public
      summary: Add a new Environment Type
      operationId: createEnvironmentType
      description: Adds a new Environment Type to an Organization.
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      requestBody:
        description: 'New Environment Type.


          '
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentTypeRequest'
      responses:
        '201':
          description: 'The Environment Type requested.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentTypeResponse'
        '400':
          description: 'The supplied `id` is not a valid ID or a required field is missing.


            '
          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 Environment Type.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/env-types/{envTypeId}:
    get:
      tags:
      - public
      summary: Get an Environment Type
      operationId: getEnvironmentType
      description: Gets a specific Environment Type within an Organization.
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: envTypeId
        in: path
        description: 'ID of the Environment Type.


          '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'The Environment Type requested.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentTypeResponse'
        '404':
          description: 'No Environment Type with `id` in Organization.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
    delete:
      tags:
      - public
      summary: Deletes an Environment Type
      operationId: deleteEnvironmentType
      description: Deletes a specific Environment Type from an Organization. If there are Environments with this Type in the Organization, the operation will fail.
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: envTypeId
        in: path
        description: 'ID of the Environment Type.


          '
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'The Environment Type requested.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentTypeResponse'
        '401':
          description: 'The Authorization header was not present or invalid.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'No Environment Type with ID `envTypeId` in Organization.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '409':
          description: 'There are 1 or more Environments with this Type.


            To delete an Environment Type, there can be no Environments with that type in the Organization.'
          content:
            application/json:
              schema:
                items:
                  additionalProperties:
                    type: str

# --- truncated at 32 KB (488 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/humanitec/refs/heads/main/openapi/humanitec-public-api-openapi.yml