openapi: 3.0.0
info:
  title: Humanitec AccountType Deployment 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: Deployment
  x-displayName: Deployments
  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.

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

    '
paths:
  /orgs/{orgId}/apps/{appId}/envs/{envId}/deploys:
    get:
      tags:
      - Deployment
      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:
      - Deployment
      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:
      - Deployment
      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:
      - Deployment
      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
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
    DeploymentErrorResponse:
      description: Error happening during deployment.
      example:
        code: CLD-001
        message: Incorrect cloud provider credentials.
        object_id: my-workload
        scope: workload
        summary: Provider error
      properties:
        code:
          type: string
        error_type:
          type: string
        message:
          type: string
        object_id:
          type: string
        scope:
          type: string
        summary:
          type: string
      required:
      - scope
      - object_id
      - code
      - summary
      - message
      - error_type
      type: object
    DeploymentPipelineReferenceRequest:
      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
      type: object
    DeploymentRequest:
      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
        delta_id:
          description: ID of the Deployment Delta describing the changes to the current Environment for this Deployment.
          type: string
        pipeline:
          $ref: '#/components/schemas/DeploymentPipelineReferenceRequest'
          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
        value_set_version_id:
          description: ID of the Value Set Version describe the values to be used for this Deployment.
          nullable: true
          type: string
      type: object
    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
    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.
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