openapi: 3.0.0
info:
  title: Humanitec AccountType DriverDefinition 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: DriverDefinition
  x-displayName: Resource Drivers
  description: 'DriverDefinition describes the resource driver.


    Resource Drivers are code that fulfils the Humanitec Resource Driver Interface. This interface allows for certain actions to be performed on resources such as creation and destruction. Humanitec provides numerous Resource Drivers “out of the box”. It is also possible to use 3rd party Resource Drivers or write your own.

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

    '
paths:
  /orgs/{orgId}/resources/drivers:
    get:
      tags:
      - DriverDefinition
      summary: List Resource Drivers.
      operationId: listResourceDrivers
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


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


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


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
    post:
      tags:
      - DriverDefinition
      summary: Register a new Resource Driver.
      operationId: createResourceDriver
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      requestBody:
        description: 'Resources Driver details.


          '
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDriverRequestRequest'
      responses:
        '200':
          description: 'The newly registered Resources Driver details.


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


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '409':
          description: 'A Resources Driver 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/drivers/{driverId}:
    get:
      tags:
      - DriverDefinition
      summary: Get a Resource Driver.
      operationId: getResourceDriver
      description: '# Only drivers that belongs to the given organization or registered as `public` are accessible through this endpoint'
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


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


          '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'The requested Resources Driver details.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriverDefinitionResponse'
        '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'
        '500':
          description: 'Internal application error.


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


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


          '
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDriverRequestRequest'
      responses:
        '200':
          description: 'The updated Resources Driver details.


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


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'A Resources Driver with the ''driverId'' 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:
      - DriverDefinition
      summary: Delete a Resources Driver.
      operationId: deleteResourceDriver
      parameters:
      - name: orgId
        in: path
        description: 'The Organization ID.


          '
        required: true
        schema:
          type: string
      - name: driverId
        in: path
        description: 'The Resources Driver ID to delete.


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

            '
        '409':
          description: 'Resource driver is used by some active resources.

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

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
components:
  schemas:
    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.
    CreateDriverRequestRequest:
      description: CreateDriverRequest describes the new resource driver registration request.
      example:
        account_types:
        - gcp
        - aws
        id: route53
        inputs_schema: {}
        is_public: false
        target: https://drivers.example.com/route53/
        template: ''
        type: dns
      properties:
        account_types:
          description: List of resources accounts types supported by the driver
          items:
            type: string
          type: array
        id:
          description: The ID for this driver. Is used as `driver_type`.
          pattern: ^[a-z0-9][a-z0-9-]+[a-z0-9]$
          type: string
        inputs_schema:
          additionalProperties: true
          description: A JSON Schema specifying the driver-specific input parameters.
          type: object
        target:
          description: The prefix where the driver resides or, if the driver is a virtual driver, the reference to an existing driver using the `driver://` schema of the format `driver://{orgId}/{driverId}`. Only members of the organization the driver belongs to can see 'target'.
          type: string
        template:
          description: If the driver is a virtual driver, template defines a Go template that converts the driver inputs supplied in the resource definition into the driver inputs for the target driver.
        type:
          description: The type of resource produced by this driver
          type: string
        is_public:
          type: boolean
          deprecated: true
      required:
      - id
      - type
      - target
      - inputs_schema
      - account_types
      type: object
    DriverDefinitionResponse:
      description: 'DriverDefinition describes the resource driver.


        Resource Drivers are code that fulfils the Humanitec Resource Driver Interface. This interface allows for certain actions to be performed on resources such as creation and destruction. Humanitec provides numerous Resource Drivers “out of the box”. It is also possible to use 3rd party Resource Drivers or write your own.'
      example:
        account_types:
        - gcp
        - aws
        id: route53
        inputs_schema: {}
        is_public: false
        org_id: test-org
        target: https://drivers.example.com/route53/
        template: ''
        type: dns
      properties:
        account_types:
          description: List of resources accounts types supported by the driver
          items:
            type: string
          type: array
        id:
          description: The ID for this driver. Is used as `driver_type`.
          type: string
        inputs_schema:
          additionalProperties: true
          description: A JSON Schema specifying the driver-specific input parameters.
          type: object
        org_id:
          description: The Organization this driver exists under. Useful as public drivers are accessible to other orgs.
          type: string
        target:
          description: The prefix where the driver resides or, if the driver is a virtual driver, the reference to an existing driver using the `driver://` schema of the format `driver://{orgId}/{driverId}`. Only members of the organization the driver belongs to can see `target`.
          type: string
        template:
          description: If the driver is a virtual driver, template defines a Go template that converts the driver inputs supplied in the resource definition into the driver inputs for the target driver.
        type:
          description: The type of resource produced by this driver
          type: string
      required:
      - org_id
      - id
      - type
      - inputs_schema
      - account_types
      type: object
    UpdateDriverRequestRequest:
      description: UpdateDriverRequest describes the update driver details request.
      example:
        account_types:
        - gcp
        - aws
        inputs_schema: {}
        is_public: false
        target: https://drivers.example.com/route53/
        template: '{{ mustToRawJson .driver }}'
        type: dns
      properties:
        account_types:
          description: List of resources accounts types supported by the driver
          items:
            type: string
          type: array
        inputs_schema:
          additionalProperties: true
          description: A JSON Schema specifying the driver-specific input parameters.
          type: object
        target:
          description: The prefix where the driver resides or, if the driver is a virtual driver, the reference to an existing driver using the `driver://` schema of the format `driver://{orgId}/{driverId}`. Only members of the organization the driver belongs to can see 'target'.
          type: string
        template:
          description: If the driver is a virtual driver, template defines a Go template that converts the driver inputs supplied in the resource definition into the driver inputs for the target driver.
        type:
          description: The type of resource produced by this driver
          type: string
        is_public:
          type: boolean
          deprecated: true
      required:
      - type
      - target
      - inputs_schema
      - account_types
      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