openapi: 3.0.0 info: title: Humanitec AccountType ActiveResource 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: ActiveResource x-displayName: Active Resources 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. ' paths: /orgs/{orgId}/apps/{appId}/envs/{envId}/resources: get: tags: - ActiveResource summary: List Active Resources provisioned in an environment. operationId: listActiveResources 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: scheduled_deletion in: query description: 'If set to `true` or `false`, filters resources scheduled or not scheduled for deletion correspondingly. ' schema: type: boolean 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' /orgs/{orgId}/apps/{appId}/envs/{envId}/resources/{type}/{resId}: delete: tags: - ActiveResource summary: Delete Active Resource. operationId: deleteActiveResource 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: type in: path description: 'The Resource Type, may include a resource class: {type}.{class}. ' required: true schema: type: string - name: resId in: path description: 'The Resource ID. ' required: true schema: type: string - name: detach in: query description: "If set to `true`, will detach an active resource. The resource continues to exist and is not deleted, but it is no longer connected to the Platform Orchestrator. \nDetaching can be done for any active resource. In case that the resource is an active one (i.e. not marked to be deleted), it would stay in use until the next deployment.\nDetaching active resources can cause inconsistent status (e.g. detaching a k8s-cluster might make it impossible to retrieve runtime information by or un-pause an environment)\nIf the resource has been provisioned via the Humanitec Operator, this does not delete the resource CR in the cluster. This must be done manually.\n" schema: type: boolean responses: '202': description: 'The resource has successfully been marked for deletion. ' '204': description: 'The resource deleted. ' '400': description: 'The driver associated to the request resource could not be found. ' content: application/json: schema: $ref: '#/components/schemas/HumanitecErrorResponse' '404': description: 'The requested resource could not be found. ' content: application/json: schema: $ref: '#/components/schemas/HumanitecErrorResponse' '409': description: 'Conflict when deleting resource. ' content: application/json: schema: $ref: '#/components/schemas/HumanitecErrorResponse' /orgs/{orgId}/apps/{appId}/envs/{envId}/resources/{type}/{resId}/actions/pin: post: tags: - ActiveResource summary: Pin Active Resource to a target Resource Definition Version. operationId: pinActiveResource parameters: - $ref: '#/components/parameters/orgIdPathParam' - $ref: '#/components/parameters/appIdPathParam' - $ref: '#/components/parameters/envIdPathParam' - $ref: '#/components/parameters/resourceTypePathParam' - $ref: '#/components/parameters/resourceIdPathParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ActiveResourceTargetDefinitionRequest' responses: '200': description: "The updated Active Resource. \n\n" content: application/json: schema: $ref: '#/components/schemas/ActiveResourceResponse' '400': description: 'One or more request parameters is missing or invalid. ' content: application/json: schema: $ref: '#/components/schemas/HumanitecErrorResponse' '404': description: 'The requested resource could not be found. ' content: application/json: schema: $ref: '#/components/schemas/HumanitecErrorResponse' /orgs/{orgId}/resources/defs/{defId}/resources: get: tags: - ActiveResource 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: parameters: resourceIdPathParam: name: resId in: path description: The Resource ID. required: true schema: type: string orgIdPathParam: name: orgId in: path description: The Organization ID example: sample-org required: true schema: type: string pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$ maxLength: 50 envIdPathParam: name: envId in: path description: The Environment ID example: development required: true schema: type: string appIdPathParam: name: appId in: path description: The Application ID required: true example: sample-app schema: pattern: ^[a-z0-9](?:-?[a-z0-9]+)+$ type: string maxLength: 50 resourceTypePathParam: name: type in: path description: 'The Resource Type, may include a resource class: {type}.{class}. ' required: true schema: type: string schemas: 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 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. ActiveResourceTargetDefinitionRequest: description: An active resource can be pinned to a certain version of the resource definition, then the resource is provisioned with this version. example: target_def_version_id: 01234567-89ab-cdef-0123-4567890abcdef properties: target_def_version_id: description: The Resource Definition Version pinned to this resource to be provisioned from. type: string nullable: true type: object required: - target_def_version_id 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