openapi: 3.0.0
info:
  title: Humanitec AccountType Environment 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: Environment
  x-displayName: Environments
  description: 'Environments are independent spaces where Applications can run. An Application is always deployed into an Environment.

    <SchemaDefinition schemaRef="#/components/schemas/EnvironmentResponse" />

    '
paths:
  /orgs/{orgId}/apps/{appId}/envs:
    get:
      tags:
      - Environment
      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:
      - Environment
      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:
      - Environment
      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:
      - Environment
      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:
      - Environment
      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}/from_deploy_id:
    put:
      tags:
      - Environment
      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'
components:
  schemas:
    DeploymentResponse:
      description: 'Deployments represent updates to the running state of an Environment.


        Deployments are made by applying _Deltas_ to a state defined by an existing Deployment. The Environment’s from_deploy property defines the Deployment. This Deployment is usually but not always in the current Environment. If the Deployment is from another Environment, the state of that Environment will be "cloned" into the current Environment with the option to apply a Delta.'
      example:
        comment: Updated version of module-one to v0.3.1
        created_at: '2020-05-22T14:58:07Z'
        created_by: a.user@example.com
        delta_id: df1ad41807b0390a9b0eaf8688e1f5baece9d764
        env_id: my-env
        from_id: 42d4b302fd3c
        id: 67f1619a57d
        status: in progress
        status_changed_at: '2020-05-22T14:59:01Z'
      properties:
        comment:
          description: An optional comment to help communicate the purpose of the Deployment.
          type: string
        created_at:
          description: The Timestamp of when the Deployment was initiated.
          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
        created_by:
          description: The user who initiated the Deployment.
          type: string
        delta_id:
          description: ID of the Deployment Delta describing the changes to the current Environment for this Deployment.
          type: string
        env_id:
          description: The Environment where the Deployment occurred.
          type: string
        export_file:
          type: string
        dependency_graph_id:
          type: string
          description: 'The ID of the Dependency Graph which holds the sorted list of the resources provisioned with this deployment.

            The referenced Graph does not include resources of type k8s-cluster and k8s-namespace (and logging in case of deployments executed in Operator mode).'
        legacy_mode:
          type: boolean
          description: Defines if it's a Legacy Mode deployment, nil means either the mode is unknown or the deployment not yet finished.
        export_status:
          type: string
        from_id:
          description: The ID of the Deployment that this Deployment was based on.
          type: string
        id:
          description: The ID of the Deployment.
          type: string
        pipeline:
          $ref: '#/components/schemas/DeploymentPipelineReferenceResponse'
          description: The Pipeline that created this deployment. This may be blank if no Pipeline is associated.
        set_id:
          description: ID of the Deployment Set describing the state of the Environment after Deployment.
          type: string
        status:
          description: The current status of the Deployment. Can be `pending`, `in progress`, `succeeded`, or `failed`.
          type: string
        status_changed_at:
          description: The timestamp of the last `status` change. If `status` is `succeeded` or `failed` it it will indicate when the Deployment finished.
          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
        value_set_version_id:
          description: ID of the Value Set Version describe the values to be used for this Deployment.
          nullable: true
          type: string
      required:
      - set_id
      - comment
      - id
      - env_id
      - created_at
      - created_by
      - status
      - status_changed_at
      - from_id
      - export_status
      - export_file
      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.
    DeploymentPipelineReferenceResponse:
      properties:
        id:
          description: The ID of the Pipeline
          type: string
        job_id:
          description: The ID of the Pipeline Job within the Run.
          type: string
        run_id:
          description: The ID of the Pipeline Run
          type: string
        step_index:
          description: The index of the step with in the Job.
          type: integer
      required:
      - id
      - run_id
      - job_id
      - step_index
      type: object
    EnvironmentDefinitionRequest:
      properties:
        from_deploy_id:
          description: Defines the existing Deployment the new Environment will be based on.
          type: string
        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: object
    EnvironmentResponse:
      description: Environments are independent spaces where Applications can run. An Application is always deployed into an Environment.
      example:
        created_at: '2020-05-22T14:58:07Z'
        created_by: a.user@example.com
        status: active
        status_changed_at: '2020-05-22T14:59:01Z'
        from_deploy:
          comment: Updated version of module-one to v0.3.1
          created_at: '2020-05-22T14:58:07Z'
          created_by: a.user@example.com
          delta_id: df1ad41807b0390a9b0eaf8688e1f5baece9d764
          env_id: my-env
          from_id: 42d4b302fd3c
          id: 67f1619a57d
          status: in progress
          status_changed_at: '2020-05-22T14:59:01Z'
        id: feature-test
        last_deploy:
          comment: Updated version of module-one to v0.3.1
          created_at: '2020-05-22T14:58:07Z'
          created_by: a.user@example.com
          delta_id: df1ad41807b0390a9b0eaf8688e1f5baece9d764
          env_id: my-env
          from_id: 42d4b302fd3c
          id: 67f1619a57d
          status: in progress
          status_changed_at: '2020-05-22T14:59:01Z'
        name: Feature Test
        type: development
      properties:
        created_at:
          description: The timestamp in UTC of when the Environment 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.
          format: date-time
          type: string
        created_by:
          description: The user who created the Environment
          type: string
        from_deploy:
          $ref: '#/components/schemas/DeploymentResponse'
          description: 'The Deployment which acts as the base for the next Deployment. Typically this will be identical to last_deploy but can differ if an Environment Rebase occurred.


            This property is not present before the first Deployment in the first Environment in a new Application.'
        id:
          description: The ID the Environment is referenced as.
          pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$
          type: string
        last_deploy:
          $ref: '#/components/schemas/DeploymentResponse'
          description: The last Deployment to have occured in the environment. This is not present if a deployment is yet to occur in the Environment.
        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
        status:
          description: The status of the environment
          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
      - type
      - created_at
      - created_by
      - status
      - status_changed_at
      type: object
    EnvironmentBaseUpdateRequest:
      properties:
        name:
          description: The Human-friendly name for the Environment.
          type: string
      type: object
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