openapi: 3.0.0
info:
  title: Humanitec AccountType ValueSetVersion 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: ValueSetVersion
  x-displayName: Shared Value Set Version
  description: 'A Value Set Version can be used as a track record of Shared Values changes, to restore a previous version of a Shared Value or Value Set, or to purge a Shared Value if it shouldn''t be accessible anymore.

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

    '
paths:
  /orgs/{orgId}/apps/{appId}/envs/{envId}/value-set-versions:
    get:
      tags:
      - ValueSetVersion
      summary: List Value Set Versions in an Environment of an App
      description: A new Value Set Version is created on every modification of a Value inside the an Environment of an App. In case this environment has no overrides the response is the same as the App level endpoint.
      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: key_changed
        in: query
        description: '(Optional) Return only value set version where the specified key changed


          '
        schema:
          type: string
      responses:
        '200':
          description: 'A possibly empty list of ValueSetVersion.


            '
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ValueSetVersionResponse'
                type: array
  /orgs/{orgId}/apps/{appId}/envs/{envId}/value-set-versions/{valueSetVersionId}:
    get:
      tags:
      - ValueSetVersion
      summary: Get a single Value Set Version in an Environment of an App. The zero version id (00000000-0000-0000-0000-000000000000) will return the latest Value Set Version.
      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: valueSetVersionId
        in: path
        description: 'The ValueSetVersion ID.


          '
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: 'The requested ValueSetVersion


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueSetVersionResponse'
        '404':
          description: 'ValueSetVersion with `valueSetVersionId` in Environment.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/apps/{appId}/envs/{envId}/value-set-versions/{valueSetVersionId}/purge/{key}:
    post:
      tags:
      - ValueSetVersion
      summary: Purge the value of a specific Shared Value from the App Environment Version history.
      description: 'Purging permanently removes the value of a specific Shared Value in an application. A purged value is no longer accessible, can''t be restored and can''t be used

        by deployments referencing a Value Set Version where the value was present.


        Learn more about purging in our [docs](https://docs.humanitec.com/reference/concepts/app-config/shared-app-values#purge).

        '
      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: valueSetVersionId
        in: path
        description: 'The ValueSetVersion ID.


          '
        required: true
        schema:
          type: string
          format: uuid
      - name: key
        in: path
        description: 'Key of the value to be purged.


          '
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValueSetActionPayloadRequest'
      responses:
        '204':
          description: 'key successfully purged


            '
        '400':
          description: 'The specified key can''t be purged in this version.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'No ValueSetVersion with `valueSetVersionId` in App Environment.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/apps/{appId}/envs/{envId}/value-set-versions/{valueSetVersionId}/restore:
    post:
      tags:
      - ValueSetVersion
      summary: Restore a Value Set Version in an Environment of an App
      description: 'Restore the values of all Shared Values in an environment from a specific version. Keys not existing in the selected version are deleted.


        Learn more about reverting in our [docs](https://docs.humanitec.com/reference/concepts/app-config/shared-app-values#revert).

        '
      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: valueSetVersionId
        in: path
        description: 'The ValueSetVersion ID.


          '
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValueSetActionPayloadRequest'
      responses:
        '200':
          description: 'The resulting ValueSetVersion


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueSetVersionResponse'
        '404':
          description: 'No ValueSetVersion with `valueSetVersionId` in App Environment.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/apps/{appId}/envs/{envId}/value-set-versions/{valueSetVersionId}/restore/{key}:
    post:
      tags:
      - ValueSetVersion
      summary: Restore a specific key from the Value Set Version in an Environment of an App
      description: 'Restore the values of a single Shared Value in an Environment from a specific version.


        Learn more about reverting in our [docs](https://docs.humanitec.com/reference/concepts/app-config/shared-app-values#revert).

        '
      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: valueSetVersionId
        in: path
        description: 'The ValueSetVersion ID.


          '
        required: true
        schema:
          type: string
          format: uuid
      - name: key
        in: path
        description: 'Key of the value to be restored.


          '
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValueSetActionPayloadRequest'
      responses:
        '200':
          description: 'The resulting ValueSetVersion


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueSetVersionResponse'
        '400':
          description: 'Invalid request


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'No ValueSetVersion with `valueSetVersionId` in App Environment.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/apps/{appId}/value-set-versions:
    get:
      tags:
      - ValueSetVersion
      summary: List Value Set Versions in the App
      description: A new Value Set Version is created on every modification of a Value inside the app.
      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: key_changed
        in: query
        description: '(Optional) Return only value set version where the specified key changed


          '
        schema:
          type: string
      responses:
        '200':
          description: 'A possibly empty list of ValueSetVersion.


            '
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ValueSetVersionResponse'
                type: array
  /orgs/{orgId}/apps/{appId}/value-set-versions/{valueSetVersionId}:
    get:
      tags:
      - ValueSetVersion
      summary: Get a single Value Set Version from the App
      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: valueSetVersionId
        in: path
        description: 'The ValueSetVersion ID.


          '
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: 'The requested ValueSetVersion


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueSetVersionResponse'
        '404':
          description: 'ValueSetVersion with `valueSetVersionId` in App.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/apps/{appId}/value-set-versions/{valueSetVersionId}/purge/{key}:
    post:
      tags:
      - ValueSetVersion
      summary: Purge the value of a specific Shared Value from the App Version history.
      description: 'Purging permanently removes the value of a specific Shared Value in an Application. A purged value is no longer accessible, can''t be restored and can''t be used

        by deployments referencing a Value Set Version where the value was present.


        Learn more about purging in our [docs](https://docs.humanitec.com/reference/concepts/app-config/shared-app-values#purge).

        '
      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: valueSetVersionId
        in: path
        description: 'The ValueSetVersion ID.


          '
        required: true
        schema:
          type: string
          format: uuid
      - name: key
        in: path
        description: 'Key of the value to be purged.


          '
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValueSetActionPayloadRequest'
      responses:
        '204':
          description: 'key successfully purged


            '
        '400':
          description: 'The specified key can''t be purged in this version.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'No ValueSetVersion with `valueSetVersionId` in App.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/apps/{appId}/value-set-versions/{valueSetVersionId}/restore:
    post:
      tags:
      - ValueSetVersion
      summary: Restore a Value Set Version in an App
      description: 'Restore the values of all Shared Values in an application from a specific version. Keys not existing in the selected version are deleted.


        Learn more about reverting in our [docs](https://docs.humanitec.com/reference/concepts/app-config/shared-app-values#revert).

        '
      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: valueSetVersionId
        in: path
        description: 'The ValueSetVersion ID.


          '
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValueSetActionPayloadRequest'
      responses:
        '200':
          description: 'The resulting ValueSetVersion


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueSetVersionResponse'
        '404':
          description: 'No ValueSetVersion with `valueSetVersionId` in App.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
  /orgs/{orgId}/apps/{appId}/value-set-versions/{valueSetVersionId}/restore/{key}:
    post:
      tags:
      - ValueSetVersion
      summary: Restore a specific key from the Value Set Version in an App
      description: 'Restore the values of a single Shared Value in an application from a specific version.


        Learn more about reverting in our [docs](https://docs.humanitec.com/reference/concepts/app-config/shared-app-values#revert).

        '
      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: valueSetVersionId
        in: path
        description: 'The ValueSetVersion ID.


          '
        required: true
        schema:
          type: string
          format: uuid
      - name: key
        in: path
        description: 'Key of the value to be restored.


          '
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValueSetActionPayloadRequest'
      responses:
        '200':
          description: 'The resulting ValueSetVersion


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueSetVersionResponse'
        '400':
          description: 'Invalid request


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
        '404':
          description: 'No ValueSetVersion with `valueSetVersionId` in App.


            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanitecErrorResponse'
components:
  schemas:
    ValueSetResponse:
      additionalProperties:
        $ref: '#/components/schemas/ValueResponse'
      type: object
    JSONPatchesResponse:
      items:
        $ref: '#/components/schemas/JSONPatchResponse'
      type: array
    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.
    ValueSetActionPayloadRequest:
      properties:
        comment:
          type: string
      type: object
    ValueSource:
      description: Source of the value, "app" for app level, "env" for app env level.
      type: string
      enum:
      - app
      - env
    ValueSetVersionResultOf:
      type: string
      nullable: true
      enum:
      - app_value_create
      - app_value_update
      - app_value_delete
      - app_values_delete
      - app_value_set_version_restore
      - app_value_set_version_purge
      - env_value_create
      - env_value_update
      - env_value_delete
      - env_values_delete
      - env_value_set_version_restore
      - env_value_set_version_purge
    ValueSetVersionResponse:
      description: A Value Set Version can be used as a track record of Shared Values changes, to restore a previous version of a Shared Value or Value Set, or to purge a Shared Value if it shouldn't be accessible anymore.
      properties:
        change:
          $ref: '#/components/schemas/JSONPatchesResponse'
        comment:
          type: string
        created_at:
          example: '2020-06-22T09:37:23.523Z'
          format: date-time
          title: Simplified extended ISO format date/time string.
          type: string
        created_by:
          type: string
        id:
          type: string
        result_of:
          $ref: '#/components/schemas/ValueSetVersionResultOf'
        source_value_set_version_id:
          nullable: true
          type: string
        updated_at:
          example: '2020-06-22T09:37:23.523Z'
          format: date-time
          title: Simplified extended ISO format date/time string.
          type: string
        values:
          $ref: '#/components/schemas/ValueSetResponse'
      required:
      - id
      - values
      - change
      - created_at
      - created_by
      - updated_at
      - result_of
      - comment
      - source_value_set_version_id
      type: object
    ValueResponse:
      description: 'Shared Values can be used to manage variables and configuration that might vary between environments. They are also the way that secrets can be stored securely.


        Shared Values are by default shared across all environments in an application. However, they can be overridden on an Environment by Environment basis.


        For example: There might be 2 API keys that are used in an application. One development key used in the development and staging environments and another used for production. The development API key would be set at the Application level. The value would then be overridden at the Environment level for the production Environment.'
      example:
        description: The message to show me.
        is_secret: false
        key: MY_MSG
        value: Hello World
      properties:
        created_at:
          example: '2020-06-22T09:37:23.523Z'
          format: date-time
          title: Simplified extended ISO format date/time string.
          type: string
        description:
          description: A Human friendly description of what the Shared Value is.
          type: string
        is_secret:
          description: Specified that the Shared Value contains a secret.
          type: boolean
        key:
          description: 'The unique key by which the Shared Value can be referenced. pattern: ^[a-zA-Z0-9._-]+$.'
          type: string
        secret_key:
          description: Location of the secret value in the secret store.
          nullable: true
          type: string
        secret_store_id:
          nullable: true
          type: string
        secret_version:
          description: Version of the current secret value as returned by the secret store.
          nullable: true
          type: string
        source:
          $ref: '#/components/schemas/ValueSource'
        updated_at:
          example: '2020-06-22T09:37:23.523Z'
          format: date-time
          title: Simplified extended ISO format date/time string.
          type: string
        value:
          description: The value that will be stored. (Will be always empty for secrets.)
          type: string
      required:
      - key
      - value
      - is_secret
      - description
      - created_at
      - updated_at
      - source
      - secret_key
      - secret_version
      - secret_store_id
      type: object
    JSONPatchResponse:
      properties:
        op:
          type: string
        path:
          type: string
        value: {}
      required:
      - op
      - path
      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