openapi: 3.0.0
info:
  title: Humanitec AccountType ResourceDefinition 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: ResourceDefinition
  x-displayName: Definitions
  description: 'A Resource Definitions describes how and when a resource should be provisioned. It links a driver (the how) along with a Matching Criteria (the when) to a Resource Type. This allows Humanitec to invoke a particular driver for the required Resource Type in the context of a particular Application and Environment.


    The schema for the `driver_inputs` is defined by the `input_schema` property on the DriverDefinition identified by the `driver_type` property.

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

    '
paths:
  /orgs/{orgId}/resources/defs:
    get:
      tags:
      - ResourceDefinition
      summary: List Resource Definitions.
      operationId: listResourceDefinitions
      description: Filter criteria can be applied to obtain all the resource definitions that could match the filters, grouped by type and sorted by matching rank. Resources marked as deleted are not listed in the response, unless specified via `deleted` query parameter.
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: app
        in: query
        description: '(Optional) Filter Resource Definitions that may match a specific Application.


          '
        schema:
          type: string
      - name: env
        in: query
        description: '(Optional) Filter Resource Definitions that may match a specific Environment.


          '
        schema:
          type: string
      - name: env_type
        in: query
        description: '(Optional) Filter Resource Definitions that may match a specific Environment Type.


          '
        schema:
          type: string
      - name: res
        in: query
        description: '(Optional) Filter Resource Definitions that may match a specific Resource.


          '
        schema:
          type: string
      - name: res_type
        in: query
        description: '(Optional) Filter Resource Definitions that may match a specific Resource Type.


          '
        schema:
          type: string
      - name: class
        in: query
        description: '(Optional) Filter Resource Definitions that may match a specific Class.


          '
        schema:
          type: string
      - name: deleted
        in: query
        description: If returns also resource definitions which has been deleted.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: 'A possibly empty list of Resources Definitions.


            '
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ResourceDefinitionResponse'
                type: array
        '500':
          description: 'Internal application error.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
    post:
      tags:
      - ResourceDefinition
      summary: Create a new Resource Definition.
      operationId: createResourceDefinition
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      requestBody:
        description: 'The Resource Definition details.


          '
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResourceDefinitionRequestRequest'
      responses:
        '200':
          description: 'The newly created Resources Definition details.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceDefinitionResponse'
        '400':
          description: 'One or more request parameters is missing or invalid.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '409':
          description: 'A Resources Definition already exists.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '500':
          description: 'Internal application error.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/resources/defs/{defId}:
    get:
      tags:
      - ResourceDefinition
      summary: Get a Resource Definition.
      description: If the resource is marked as deleted it is not shown in the response, unless specified via `deleted` query parameter.
      operationId: getResourceDefinition
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: defId
        in: path
        description: 'The Resource Definition ID.


          '
        required: true
        schema:
          type: string
      - name: deleted
        in: query
        description: If returns the resource definition even if it has been deleted.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: 'The requested Resources Definition details.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceDefinitionResponse'
        '404':
          description: 'A Resource Definition with the ''defId'' ID is not found.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '500':
          description: 'Internal application error.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
    put:
      tags:
      - ResourceDefinition
      summary: Update a Resource Definition.
      operationId: updateResourceDefinition
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: defId
        in: path
        description: 'The Resource Definition ID.


          '
        required: true
        schema:
          type: string
      requestBody:
        description: 'The Resource Definition record details.


          The PUT operation updates a resource definition using the provided payload. An empty driver_account or driver_inputs property will unset the existing values.


          If driver_type changes and an Active Resource which uses this Resource Definition exists, the resource provisioned with the previous used driver_type will be deleted.

          As driver_type can''t be empty, an empty driver_type means existing value will be used.


          Currently the resource can''t be changed.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateResourceDefinitionRequestRequest'
      responses:
        '200':
          description: 'The updated Resource Definition.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceDefinitionResponse'
        '400':
          description: 'One or more request parameters is missing or invalid.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'A Resource Definition with the ''defId'' ID is not found.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '500':
          description: 'Internal application error.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
    delete:
      tags:
      - ResourceDefinition
      summary: Delete a Resource Definition.
      operationId: deleteResourceDefinition
      description: "If there **are no** Active Resources provisioned via the current definition, the Resource Definition is deleted immediately.\n\nIf there **are** Active Resources provisioned via the current definition, the request fails. The response will describe the changes to the affected Active Resources if operation is forced.\n\nThe request can take an optional `force` query parameter. If set to `true`, the current Resource Definition is deleted immediately even if there are Active Resources linked to it.  \nThe Resource Definition that has been marked for deletion cannot be used to provision new resources.\n\nWith the next deployment, matching criteria for Resources will be re-evaluated, and current Active Resources for the target environment would be either linked to another matching Resource Definition or decommissioned and created using the new or default Resource Definition (when available)."
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: defId
        in: path
        description: 'The Resource Definition ID.


          '
        required: true
        schema:
          type: string
      - name: force
        in: query
        description: 'If set to `true`, will mark the Resource Definition for deletion, even if it affects existing Active Resources.


          '
        schema:
          type: boolean
      responses:
        '204':
          description: 'Resource Definition has been marked as deleted.


            '
        '404':
          description: 'A Resource Driver with the ''driverId'' ID is not found or is not accessible by the organization.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '409':
          description: 'List of Active Resources that still reference this Resource Definition.


            '
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ResourceDefinitionChangeResponse'
                type: array
        '500':
          description: 'Internal application error.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
    patch:
      tags:
      - ResourceDefinition
      summary: Update a Resource Definition.
      operationId: patchResourceDefinition
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: defId
        in: path
        description: 'The Resource Definition ID.


          '
        required: true
        schema:
          type: string
      requestBody:
        description: 'The Resource Definition record details.


          The PATCH operation would change the value of the property if it is included in the request payload JSON, and not `null`. Missing and `null` properties are ignored.


          For the map properties, such as PatchResourceDefinitionRequest.DriverInputs, the merge operation is applied.


          Merge rules are as follows:


          - If a map property has a value, it is replaced (or added).


          - If a map property is set to `null`, it is removed.


          - If a map property is not included (missing in JSON), it remains unchanged.'
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchResourceDefinitionRequestRequest'
      responses:
        '200':
          description: 'The updated Resource Definition.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceDefinitionResponse'
        '400':
          description: 'One or more request parameters is missing or invalid.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'A Resource Definition with the ''defId'' ID is not found.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '500':
          description: 'Internal application error.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/resources/defs/{defId}/criteria:
    put:
      tags:
      - ResourceDefinition
      summary: Update all Matching Criteria of a Resource Definition.
      operationId: updateResourceDefinitionCriteria
      description: "Matching Criteria are combined with Resource Type to select a specific definition. Matching Criteria can be set for any combination of Application ID, Environment ID, Environment Type, and Resource ID. In the event of multiple matches, the most specific match is chosen.\n\nFor example, given 3 sets of matching criteria for the same type:\n\n```\n 1. {\"env_type\":\"test\"}\n 2. {\"env_type\":\"development\"}\n 3. {\"env_type\":\"test\", \"app_id\":\"my-app\"}\n```\n\nIf, a resource of that type was needed in an Application `my-app`, Environment `qa-team` with Type `test` and Resource ID `modules.my-module-externals.my-resource`, there would be two resource definitions matching the criteria: #1 & #3. Definition #3 will be chosen because its matching criteria is the most specific."
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: defId
        in: path
        description: 'The Resource Definition ID.


          '
        required: true
        schema:
          type: string
      requestBody:
        description: 'Matching Criteria rules.


          '
        required: true
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/MatchingCriteriaRuleRequest'
              type: array
            example:
            - env_id: production
      responses:
        '200':
          description: 'The newly added Matching Criteria details.


            '
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/MatchingCriteriaResponse'
                type: array
        '400':
          description: 'One or more request parameters is missing or invalid.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'The Resource Definition is not found.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '409':
          description: 'A Matching Criteria already exists.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '500':
          description: 'Internal application error.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
    post:
      tags:
      - ResourceDefinition
      summary: Add a new Matching Criteria to a Resource Definition.
      operationId: createResourceDefinitionCriteria
      description: "Matching Criteria are combined with Resource Type to select a specific definition. Matching Criteria can be set for any combination of Application ID, Environment ID, Environment Type, and Resource ID. In the event of multiple matches, the most specific match is chosen.\n\nFor example, given 3 sets of matching criteria for the same type:\n\n```\n 1. {\"env_type\":\"test\"}\n 2. {\"env_type\":\"development\"}\n 3. {\"env_type\":\"test\", \"app_id\":\"my-app\"}\n```\n\nIf, a resource of that type was needed in an Application `my-app`, Environment `qa-team` with Type `test` and Resource ID `modules.my-module-externals.my-resource`, there would be two resource definitions matching the criteria: #1 & #3. Definition #3 will be chosen because its matching criteria is the most specific."
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: defId
        in: path
        description: 'The Resource Definition ID.


          '
        required: true
        schema:
          type: string
      requestBody:
        description: 'Matching Criteria rules.


          '
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MatchingCriteriaRuleRequest'
            example:
              env_id: production
      responses:
        '200':
          description: 'The newly added Matching Criteria details.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchingCriteriaResponse'
        '400':
          description: 'One or more request parameters is missing or invalid.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'The Resource Definition is not found.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '409':
          description: 'A Matching Criteria already exists.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '500':
          description: 'Internal application error.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/resources/defs/{defId}/criteria/{criteriaId}:
    delete:
      tags:
      - ResourceDefinition
      summary: Delete a Matching Criteria from a Resource Definition.
      operationId: deleteResourceDefinitionCriteria
      description: 'If there **are no** Active Resources that would match to a different Resource Definition when the current Matching Criteria is deleted, the Matching Criteria is deleted immediately.


        If there **are** Active Resources that would match to a different Resource Definition, the request fails with HTTP status code 409 (Conflict). The response content will list all of affected Active Resources and their new matches.


        The request can take an optional `force` query parameter. If set to `true`, the Matching Criteria is deleted immediately. Referenced Active Resources would match to a different Resource Definition during the next deployment in the target environment.'
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: defId
        in: path
        description: 'The Resource Definition ID.


          '
        required: true
        schema:
          type: string
      - name: criteriaId
        in: path
        description: 'The Matching Criteria ID.


          '
        required: true
        schema:
          type: string
      - name: force
        in: query
        description: 'If set to `true`, the Matching Criteria is deleted immediately, even if this action affects existing Active Resources.


          '
        schema:
          type: boolean
      responses:
        '204':
          description: 'Record deleted.


            '
        '404':
          description: 'The Resource Definition is not found.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '409':
          description: 'One or more Active Resources reference the Resource Definition through this Matching Criteria.


            '
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ResourceDefinitionChangeResponse'
                type: array
        '500':
          description: 'Internal application error.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/resources/defs/{defId}/resources:
    get:
      tags:
      - ResourceDefinition
      summary: List Active Resources provisioned via a specific Resource Definition.
      operationId: listActiveResourceByDefinition
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: defId
        in: path
        description: 'The Resource Definition ID.


          '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'A possibly empty list of Active Resources.


            '
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ActiveResourceResponse'
                type: array
        '500':
          description: 'Internal application error.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
components:
  schemas:
    CreateResourceDefinitionRequestRequest:
      description: CreateResourceDefinitionRequest describes a new ResourceDefinition request.
      example:
        criteria: []
        driver_account: gcp-dev-cloudsql
        driver_inputs:
          secrets:
            dbcredentials:
              password: '***'
              username: '***'
          values:
            instance: my-dev-project:my-region:dev-db
        driver_type: humanitec/cloudsql
        id: dev-postgres
        name: Dev Postgres Instance
        provision:
          aws-policy:
            is_dependent: false
          dns#my-dns: {}
        type: postgres
      properties:
        criteria:
          description: (Optional) The criteria to use when looking for a Resource Definition during the deployment.
          items:
            $ref: '#/components/schemas/MatchingCriteriaRuleRequest'
          type: array
        driver_account:
          description: (Optional) Security account required by the driver.
          pattern: ^[a-z0-9][a-z0-9-]+[a-z0-9]$
          type: string
        driver_inputs:
          $ref: '#/components/schemas/ValuesSecretsRefsRequest'
          description: (Optional) Additional input data to be passed to the driver.
        driver_type:
          description: The driver to be used to create the resource.
          type: string
        id:
          description: The Resource Definition ID.
          pattern: ^[a-z0-9][a-z0-9-]+[a-z0-9]$
          type: string
        name:
          description: The display name.
          type: string
        provision:
          additionalProperties:
            $ref: '#/components/schemas/ProvisionDependenciesRequest'
          description: (Optional) A map where the keys are resType#resId (if resId is omitted, the same id of the current resource definition is used) of the resources that should be provisioned when the current resource is provisioned. This also specifies if the resources have a dependency on the current resource.
          type: object
        type:
          description: The Resource Type.
          type: string
      required:
      - id
      - name
      - type
      - driver_type
      type: object
    ActiveResourceResponse:
      description: 'Active Resources represent the concrete resources provisioned for an Environment. They are provisioned on the first deployment after a dependency on a particular resource type is introduced into an Environment. In general, Active Resources are only deleted when their introductory Environment is deleted.


        Active Resources are provisioned based on a Resource Definition. The Resource Definition describes how to provision a concrete resource based on a Resource Type and metadata about the Environment (for example the Environment Type or the Application ID). The criteria for how to choose a Resource Definition is known as a Matching Criteria. If the Matching Criteria changes or the Resource Definition is deleted, the concrete resource represented by an Active Resource might be deleted and reprovisioned when a deployment occurs in the Environment.'
      example:
        app_id: test-app
        class: default
        def_id: gcp-dev-postgres
        def_version_id: 01234567-89ab-cdef-0123-4567890abcdef
        deploy_id: 172a1013b
        env_id: gcp-dev
        env_type: development
        gu_res_id: 7bd3966c9ff8eaa66c5cce855c03d715857c3440
        org_id: test-org
        res_id: modules.my-module.externals.my-db
        resource:
          host: 127.0.0.1
          name: db_33c7ef9b_8d90-4c62_a1cf_0cdd30fd29a9
          port: 5432
        secret_refs:
          credentials: orgs/test-org/resources/7bd3966c9ff8eaa66c5cce855c03d715857c3440/secrets/.credentials
        type: postgres
        updated_at: '2020-06-23T16:53:12Z'
      properties:
        app_id:
          description: The ID of the App the resource is associated with.
          type: string
        class:
          description: The Resource Class of the resource
          type: string
        criteria_id:
          description: The Matching Criteria ID.
          type: string
        def_id:
          description: The Resource Definition that this resource was provisioned from.
          type: string
        def_version_id:
          description: The Resource Definition Version that this resource was provisioned from.
          type: string
        target_def_version_id:
          description: The Resource Definition Version pinned to this resource to be provisioned from.
          type: string
        deploy_id:
          description: The deployment that the resource was last provisioned in.
          type: string
        driver_account:
          description: (Optional) Security account required by the driver.
          type: string
        driver_type:
          description: The driver to be used to create the resource.
          type: string
        env_id:
          description: The ID of the Environment the resource is associated with.
          type: string
        env_type:
          description: The Environment Type of the Environment specified by env_id.
          type: string
        gu_res_id:
          description: Globally unique resource id
          type: string
        org_id:
          description: the ID of the Organization the Active Resource is associated with.
          type: string
        res_id:
          description: The ID of the resource
          type: string
        resource:
          additionalProperties: true
          description: The resource provisioning outputs ('values' only).
          type: object
        scheduled_deletion:
          description: Deletion is scheduled for this resource.
          type: boolean
        secret_refs:
          additionalProperties: true
          description: Secret references from the resource provisioning output.
          type: object
        status:
          description: 'Current resource status: ''pending'', ''active'', or ''deleting''.'
          type: string
        type:
          description: The Resource Type of the resource
          type: string
        updated_at:
          description: The time the resource was last provisioned as part of a deployment.
          example: '2020-06-22T09:37:23.523Z'
          type: string
          format: date-time
      required:
      - org_id
      - app_id
      - env_id
      - env_type
      - res_id
      - def_id
      - def_version_id
      - type
      - driver_type
      - class
      - status
      - resource
      - secret_refs
      - updated_at
      - deploy_id
      - gu_res_id
      - scheduled_deletion
      type: object
    ValuesSecretsRefsRequest:
      description: ValuesSecretsRefs stores data that should be passed around split by sensitivity.
      example:
        secret_refs:
          credentials:
            password:
              value: <secret>
            user:
              ref: vault/path/to/data/secrets/user
              store: my-external-vault
              version: '1'
        secrets:
          password: vault/path/to/data/.secrets/password
          user: vault/path/to/data/.secrets/user
        values:
          host: 127.0.0.1
          name: my-database
      properties:
        secret_refs:
          additionalProperties: true
          description: 'Secrets section of the data set. They can hold sensitive information that will be stored in the primary organization secret store and replaced with the secret store paths when sent outside, or secret references stored in a defined secret store. Can''t be used together with `secrets`.


            They can hold a nested structure but leaf objects need to be of type SecretReference, where:


            - `store` is a Secret Store id. It can''t be `humanitec`. It''s mandatory if `ref` is defined and can''t be used in request payloads if `value` is defined.


            - `ref` is the secret key in the format of the target store. It can''t be used in request payloads if `value` is defined.


            - `version` is the version of the secret as defined in the target store. It can be defined only if `ref` is defined.


            - `value` is the value to store in the organizations primary secret store. It can''t be used in request payloads if `ref` is defined.'
          type: object
        secrets:
          additionalProperties: true
          description: Secrets section of the data set. Sensitive information is stored in the primary organization secret store and replaced with the secret store paths when sent outside. Can't be used together with `secret_refs`.
          type: object
        values:
          additionalProperties: true
          description: Values section of the data set. Passed around as-is.
          type: object
      type: object
    ProvisionDependenciesRequest:
      description: ProvisionDependencies defines resources which are needed to be co-provisioned with the current resource.
      properties:
        is_dependent:
          description: If the co-provisioned resource is dependendent on the current one.
          type: boolean
        match_dependents:
          description: If the resources dependant on the main resource, are also dependant on the co-provisioned one.
          type: boolean
        params:
          additionalProperties: true
          description: (Optional) Additional parameters to be passed to the driver which will provision the resource.
          type: object
      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.
    ProvisionDependenciesResponse:
      description: ProvisionDependencies defines resources which are needed to be co-provisioned with the current resource.
      properties:
        is_dependent:
          description: If the co-provisioned resource is dependendent on the current one.
          type: boolean
        match_dependents:
          description: If the resources dependant on the main resource, are also dependant on the co-provisioned one.
          type: boolean
        params:
          additionalProperties: true
          description: (Optional) Additional parameters to be passed to the driver which will provision the resource.
          type: object
      required:
      - is_dependent
      type: object
    UpdateResourceDefinitionRequestRequest:
      description: UpdateResourceDefinitionRequest describes a ResourceDefinition change request.
      example:
        driver_type: humanitec/terraform
        driver_account: gcp-dev-cloudsql
        driver_inputs:
          secret_refs:
            dbcredentials:
              password:
                ref: path--to--password
                store: my-store
                version: '1'
              username:
                value: '***'
          values:
            instance: my-dev-project:my-region:dev-db
        name: Dev Postgres Instance
        provision:
          aws-policy:
            is_dependent: false
          dns#my-dns: {}
      properties:
        driver_type:
          description: (Optional) The driver to be used to create the resource.
          type: string
        driver_account:
          description: (Optional) Security account required by the driver.
          pattern: ^[a-z0-9][a-z0-9-]+[a-z0-9]$
          type: string
        driver_inputs:
          $ref: '#/components/schemas/ValuesSecretsRefsRequest'
          description: (Optional) Additional input data to be passed to the driver.
        name:
          description: The display name.
          type: string
        provision:
          additionalProperties:
            $ref: '#/components/schemas/ProvisionDependenciesRequest'
          description: (Optional) A map where the keys are resType#resId (if resId is omitted, the same id of the current resource definition is used) of the resources that should be provisioned when the current resource is provisioned. This also specifies if the resources have a dependency on the current resource or if they have the same dependent resources.
          type: object
        proposed:
          description: (Optional) If true, the new definition version should be created as "proposed" version (not active).
          type: boolean
      required:
      - name
      type: object
    PatchResourceDefinitionRequestRequest:
      description: PatchResourceDefinitionRequest describes a ResourceDefinition change request.
      example:
        driver_account: gcp-dev-cloudsql
        driver_inputs:
          secret_refs:
            dbcredentials:
              password:
                ref: path--to--password
                store: my-store
                version: '1'
              username:
                value: '***'
          values:
            instance: my-dev-project:my-region:dev-db
        provision:
          aws-policy:
            is_dependent: false
          dns#my-dns: {}
      properties:
        driver_account:
          description: (Optional) Security account required by the driver.
          pattern: ^[a-z0-9][a-z0-9-]+[a-z0-9]$
          type: string
        driver_inputs:
          $ref: '#/components/schemas/ValuesSecretsRefsRequest'
          description: (Optional) Additional input data to be passed to the driver.
        name:
          description: (Optional) Resource display name
          type: string
        provision:
          additionalProperties:
            $ref: '#/components/schemas/ProvisionDependenciesRequest'
          description: (Optional) A map where the keys are resType#resId (if resId is omitted, the same id of the current resource definition is used) of the resources that should be provisioned when the current resource is provisioned. This also specifies if the resources have a dependency on the current resource or if they have the same dependent resources.
          type: object
        proposed:
          description: (Optional) If true, the new definition version should be created as "proposed" version (not active).
          type: boolean
      type: object
    MatchingCriteriaRuleRequest:
      description: MatchingCriteriaRule describes Matching Criteria rules.
      properties:
        app_id:
          description: (Optional) The ID of the Application that the Resources should belong to.
          type: string
        class:
          description: (Optional) The class of the Resource in the Deployment Set. Can not be empty, if is not defined, set to `default`.
          type: string
        env_id:
          description: (Optional) The ID of the Environment that the Resources should belong to. If `env_type` is also set, it must match the Type of the Environment for the Criteria to match.
          type: string
        env_type:
          description: (Optional) The Type of the Environment that the Resources should belong to. If `env_id` is also set, it must have an Environment Type that matches this parameter for the Criteria to match.
          type: string
        res_id:
          description: (Optional) The ID of the Resource in the Deployment Set. The ID is normally a `.` separated path to the definition in the set, e.g. `modules.my-module.externals.my-database`.
          type: string
      type: object
    ResourceDefinitionChangeResponse:
      description: ResourceDefinitionChange describes the effects of a Resource Definition or Matching Criteria update/deletion.
      properties:
        app_id:
          description: The ID of the App the resource is associated with.
          type: string
        env_id:
          description: The ID of the Environment the resource is associated with.
          type: string
        from_def:
          description: The Resource Definition that this resource was provisioned from.
          type: string
        res_id:
          description: The ID of the resource
          type: string
        to_def:
          description: The Resource Definition that resource *will be* provisioned from if the change is applied.
          type: string
      required:
      - app_id
      - env_id
      - res_id
      - from_def
      - to_def
      type: object
    MatchingCriteriaResponse:
      description: 'Matching Criteria are a set of rules used to choose which Resource Definition to use to provision a particular Resource Type.


        Matching criteria are made up in order of specificity with least specific first:


        - Environment Type (`env_type`)


        - Application (`app_id`)


        - Environment (`env_id`)


        - Resource (`res_id`)


        When selecting matching criteria, the most specific one is selected. In general, this means of all the Matching Criteria fully matching the context, the Matching Criteria Rule with the most specific element filled is chosen. If there is a tie, the next most specific elements are compared and so on until one is chosen.


        **NOTE:**


        Humanitec will reject the registration of matching criteria rules that duplicate rules already present for a Resource Type.'
      properties:
        app_id:
          description: (Optional) The ID of the Application that the Resources should belong to.
          type: string
        class:
          description: (Optional) The class of the Resource in the Deployment Set. Can not be empty, if is not defined, set to `default`.
          type: string
        env_id:
          description: (Optional) The ID of the Environment that the Resources should belong to. If `env_type` is also set, it must match the Type of the Environment for the Criteria to match.
          type: string
        env_type:
          description: (Optional) The Type of the Environment that the Resources should belong to. If `env_id` is also set, it must have an Environment Type that matches this parameter for the Criteria to match.
          type: string
        id:
          description: Matching Criteria ID
          type: string
        res_id:
          description: (Optional) The ID of the Resource in the Deployment Set. The ID is normally a `.` separated path to the definition in the set, e.g. `modules.my-module.externals.my-database`.
          type: string
      required:
      - class
      - id
      type: object
    ResourceDefinitionResponse:
      description: 'A Resource Definitions describes how and when a resource should be provisioned. It links a driver (the how) along with a Matching Criteria (the when) to a Resource Type. This allows Humanitec to invoke a particular driver for the required Resource Type in the context of a particular Application and Environment.


        The schema for the `driver_inputs` is defined by the `input_schema` property on the DriverDefinition identified by the `driver_type` property.'
      example:
        created_at: '2020-05-23T12:32:16Z'
        created_by: a.user@example.com
        criteria:
        - env_type: development
          id: '123456'
        driver_account: gcp-dev-cloudsql
        driver_inputs:
          secret_refs:
            credentials:
              password:
                value: <secret>
              user:
                ref: vault/path/to/data/secrets/user
                store: my-external-vault
                version: '1'
          values:
            instance: my-dev-project:my-region:dev-db
        driver_type: humanitec/postgres-cloudsql
        id: dev-postgres
        is_default: false
        is_deleted: false
        name: Dev Postgres Instance
        org_id: test-org
        provision:
          aws-policy:
            is_dependent: false
            match_dependents: false
          dns#my-dns: {}
        type: postgres
      properties:
        created_at:
          description: The timestamp of when this record has been created.
          example: '2020-06-22T09:37:23.523Z'
          title: Simplified extended ISO format date/time string.
          type: string
          format: date-time
        created_by:
          description: The user who created this record.
          type: string
        updated_at:
          description: The timestamp of when this record has been updated.
          example: '2020-06-22T09:37:23.523Z'
          title: Simplified extended ISO format date/time string.
          type: string
          format: date-time
        updated_by:
          description: The user who updated this record.
          type: string
        criteria:
          description: (Optional) The criteria to use when looking for a Resource Definition during the deployment.
          items:
            $ref: '#/components/schemas/MatchingCriteriaResponse'
          type: array
        driver_account:
          description: (Optional) Security account required by the driver.
          type: string
        driver_inputs:
          $ref: '#/components/schemas/ValuesSecretsRefsResponse'
          description: (Optional) Additional input data to be passed to the driver.
        driver_type:
          description: The driver to be used to create the resource.
          type: string
        id:
          description: The Resource Definition ID.
          type: string
        active_version_id:
          description: The active Resource Definition Version ID.
          type: string
        is_default:
          description: Indicates this definition is a built-in one (provided by Humanitec).
          type: boolean
        is_deleted:
          description: Indicates if this record has been marked for deletion. The Resource Definition that has been marked for deletion cannot be used to provision new resources.
          type: boolean
        name:
          description: The display name.
          type: string
        org_id:
          description: The Organization ID.
          type: string
        provision:
          additionalProperties:
            $ref: '#/components/schemas/ProvisionDependenciesResponse'
          description: (Optional) A map where the keys are resType#resId (if resId is omitted, the same id of the current resource definition is used) of the resources that should be provisioned when the current resource is provisioned. This also specifies if the resources have a dependency on the current resource.
          type: object
        type:
          description: The Resource Type.
          type: string
      required:
      - org_id
      - id
      - name
      - type
      - created_at
      - created_by
      - is_default
      - is_deleted
      - driver_type
      - active_version_id
      type: object
    ValuesSecretsRefsResponse:
      description: ValuesSecretsRefs stores data that should be passed around split by sensitivity.
      example:
        secret_refs:
          credentials:
            password:
              value: <secret>
            user:
              ref: vault/path/to/data/secrets/user
              store: my-external-vault
              version: '1'
        secrets:
          password: vault/path/to/data/.secrets/password
          user: vault/path/to/data/.secrets/user
        values:
          host: 127.0.0.1
          name: my-database
      properties:
        secret_refs:
          additionalProperties: true
          description: 'Secrets section of the data set. They can hold sensitive information that will be stored in the primary organization secret store and replaced with the secret store paths when sent outside, or secret references stored in a defined secret store. Can''t be used together with `secrets`.


            They can hold a nested structure but leaf objects need to be of type SecretReference, where:


            - `store` is a Secret Store id. It can''t be `humanitec`. It''s mandatory if `ref` is defined and can''t be used in request payloads if `value` is defined.


            - `ref` is the secret key in the format of the target store. It can''t be used in request payloads if `value` is defined.


            - `version` is the version of the secret as defined in the target store. It can be defined only if `ref` is defined.


            - `value` is the value to store in the organizations primary secret store. It can''t be used in request payloads if `ref` is defined.'
          type: object
        secrets:
          additionalProperties: true
          description: Secrets section of the data set. Sensitive information is stored in the primary organization secret store and replaced with the secret store paths when sent outside. Can't be used together with `secret_refs`.
          type: object
        values:
          additionalProperties: true
          description: Values section of the data set. Passed around as-is.
          type: object
      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