openapi: 3.0.3
info:
  description: >
    ---

    sidebar_position: 1

    sidebar_label: Overview

    description: The Piiano Vault REST API enables you to access and manage collections, objects, tokens, users, policies, and other resources within Piiano Vault.

    slug: /

    ---


    # Introduction


    The Piiano Vault REST API enables you to access and manage collections, objects, tokens, users, policies, and other resources within Piiano Vault in a simple, programmatic way using conventional HTTP requests and standard HTTP response codes.


    The API follows RESTful conventions when possible, with most operations performed by `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` requests. Request and response bodies are [JSON-encoded](https://www.json.org/json-en.html). However, for collection operations, an SQL-like [PVSchema](/guides/reference/pvschema) encoding is available.


    This API reference provides details for each operation available in the API.


    When you install a local copy of Vault, you can try each operation using **Send API request**.


    An OpenAPI specification is available in [YAML](@site/static/assets/openapi.yaml) and [JSON](@site/static/assets/openapi.json) formats and can be used to generate client code for the API.
  contact:
    name: Us
    url: https://piiano.com/contact-us/
  license:
    name: MPL-2.0
    url: https://www.mozilla.org/en-US/MPL/2.0/
  title: Piiano Vault REST API
  version: "1.0"
servers:
  - url: http://localhost:8123
tags:
  - description: Create, retrieve, update, and delete the <a
      href="/guides/manage-collections-and-schemas/about-collections">collections</a>
      you use to hold sensitive data.
    name: Collections
  - description: Create, retrieve, list, update, and delete the <a
      href="/guides/manage-collections-and-schemas/about-collections">collection
      properties</a> that define the data items stored in collections.
    name: Collection properties
  - description: Create, retrieve, update, and delete <a
      href="/guides/reference/bundles">bundles</a> containing JavaScript code
      used by <a href="/guides/reference/custom-data-types">custom data
      types</a> to validate, normalize, and transform data.
    name: Bundles
  - description: Create, retrieve, update, and delete <a
      href="/guides/reference/custom-data-types">custom data types</a> you use
      to validate, normalize, store, and transform your unique data.
    name: Custom data types
  - description: Create, retrieve, search, update, and delete the <a
      href="/guides/write-and-read-personal-data/about-objects">objects</a> that
      store your sensitive data in collections.
    name: Objects
  - description: Tokenize, detokenize, update, rotate, search, and delete
      non-sensitive <a
      href="/guides/tokenize-personal-data/about-tokens">tokens</a> referencing
      sensitive data.
    name: Tokens
  - description: Encrypt, decrypt, and update encrypted ciphertext for Vault
      objects, data stored outside Vault, and ciphertext objects.
    name: Crypto
  - description: Check for and locate PII data in text strings. <br/><br/>&#x26A0;
      These requests are rate-limited\:<ul><li>For sandbox users, the rate limit
      is 10 requests per minute and 1,000 requests per day, and subject to fair
      use policy for evaluation purposes.</li><li>For production users,
      `Contains` can be called more frequently than `Locate`; your purchased
      plan determines the rate. [Contact us](https://www.piiano.com/contact-us)
      for details.</li></ul>
    name: Analysis
  - description: Retrieve and invoke actions that process data without giving the
      action caller access to the source data.
    name: Actions
  - description: Set and retrieve the <a href="/guides/reference/iam-toml">IAM
      configuration</a> and <a
      href="/guides/manage-users-and-policies/regenerate-user-api-key">regenerate
      user API keys</a>.
    name: IAM
  - description: Set and retrieve the dynamic configuration variables that control
      the behavior of your Vault.
    name: Config Vars
  - description: Retrieve details about the status of system components and the
      Vault version. These operations are unavailable in the hosted version of
      Vault.
    name: System
paths:
  /api/pvlt/1.0/ctl/collections:
    get:
      operationId: list-collections
      summary: List collections
      description: >
        Lists all collections.


        The collections can be returned in JSON or PVSchema format using the `format` query parameter or by setting the `Accept` header to `application/json` or `application/pvschema`, respectively. The default is to return JSON.


        See [PVSchema](/guides/reference/pvschema) for more details on the structure and content of PVSchema.


        The PVSchema format for multiple collections is the PVSchema for each collection string concatenated with a newline.


        See the [List collections](/guides/manage-collections-and-schemas/list-all-collections) guide for more information on using this operation.


        The role that performs this operation must have the `CapCollectionsReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/jsonOrPvSchemaFormat"
        - $ref: "#/components/parameters/custom_audit"
        - description: |
            Options for the operation. Options include:
            - `show_builtins` – show built-in properties in the response.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - show_builtins
      responses:
        "200":
          description: The request is successful.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Collection"
              example:
                - type: PERSONS
                  name: customers
                  properties:
                    - description: Date of birth
                      name: date_of_birth
                      data_type_name: DATE_OF_BIRTH
                      is_unique: false
                      is_index: false
                      is_substring_index: false
                      is_encrypted: true
                      is_nullable: true
                      is_builtin: false
                      is_readonly: false
                      creation_time: 2022-12-01T10:04:42.777225Z
                      modification_time: 2022-12-01T10:04:42.777225Z
                    - description: Email
                      name: email
                      data_type_name: EMAIL
                      is_unique: true
                      is_index: true
                      is_substring_index: false
                      is_encrypted: true
                      is_nullable: true
                      is_builtin: false
                      is_readonly: false
                      creation_time: 2022-12-01T10:04:42.777225Z
                      modification_time: 2022-12-01T10:04:42.777225Z
                    - description: First name
                      name: first_name
                      data_type_name: NAME
                      is_unique: false
                      is_index: false
                      is_substring_index: false
                      is_encrypted: true
                      is_nullable: false
                      is_builtin: false
                      is_readonly: false
                      creation_time: 2022-12-01T10:04:42.777225Z
                      modification_time: 2022-12-01T10:04:42.777225Z
                    - description: Last name
                      name: last_name
                      data_type_name: NAME
                      is_unique: false
                      is_index: false
                      is_substring_index: false
                      is_encrypted: true
                      is_nullable: false
                      is_builtin: false
                      is_readonly: false
                      creation_time: 2022-12-01T10:04:42.777225Z
                      modification_time: 2022-12-01T10:04:42.777225Z
                    - description: Phone number
                      name: phone_number
                      data_type_name: PHONE_NUMBER
                      is_unique: true
                      is_index: true
                      is_substring_index: false
                      is_encrypted: true
                      is_nullable: true
                      is_builtin: false
                      is_readonly: false
                      creation_time: 2022-12-01T10:04:42.777225Z
                      modification_time: 2022-12-01T10:04:42.777225Z
                  creation_time: 2022-12-01T10:04:42.777225Z
                  modification_time: 2022-12-01T10:04:42.777225Z
            application/pvschema:
              schema:
                $ref: "#/components/schemas/Collection.pvschema"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          description: Reserved for future use.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                error_code: PV1004
                message: The collection is not found.
                context: {}
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Collections
    post:
      operationId: add-collection
      summary: Add collection
      description: >-
        Adds a collection.


        The collection request can be provided in JSON or PVSchema format by setting the `Content-Type` header to `application/json` or `application/pvschema`, respectively. The collection can be returned in JSON or PVSchema format using the `format` query parameter or by setting the `Accept` header to `application/json` or `application/pvschema`, respectively. The default is to return JSON.


        See [PVSchema](/guides/reference/pvschema) for more details on the structure and content of PVSchema.


        Invalid optional `properties` attributes in a JSON request are ignored.


        :::note

        The combined length of the collection name and the longest property name can not exceed 40 characters.

        :::


        See the [Create a collection](/guides/manage-collections-and-schemas/create-a-collection) guide for more information on using this operation.


        The role performing this operation must have the `CapCollectionsWriter` capability. See [Access control](/data-security/identity-and-access-management#access-control) for more information about how capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/jsonOrPvSchemaFormat"
        - $ref: "#/components/parameters/custom_audit"
        - description: |
            Options for the operation. Options include:
            - `show_builtins` – show built-in properties in the response.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - show_builtins
      requestBody:
        x-has-pii: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Collection"
          application/pvschema:
            schema:
              $ref: "#/components/schemas/Collection.pvschema"
        description: Details of the collection including its properties.
        required: true
        x-originalParamName: collection
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Collection"
              example:
                type: PERSONS
                name: customers
                properties:
                  - description: Date of birth
                    name: date_of_birth
                    data_type_name: DATE_OF_BIRTH
                    is_unique: false
                    is_index: false
                    is_substring_index: false
                    is_encrypted: true
                    is_nullable: true
                    is_builtin: false
                    is_readonly: false
                    creation_time: 2022-12-01T10:04:42.777225Z
                    modification_time: 2022-12-01T10:04:42.777225Z
                  - description: Email
                    name: email
                    data_type_name: EMAIL
                    is_unique: true
                    is_index: true
                    is_substring_index: false
                    is_encrypted: true
                    is_nullable: true
                    is_builtin: false
                    is_readonly: false
                    creation_time: 2022-12-01T10:04:42.777225Z
                    modification_time: 2022-12-01T10:04:42.777225Z
                  - description: First name
                    name: first_name
                    data_type_name: NAME
                    is_unique: false
                    is_index: false
                    is_substring_index: false
                    is_encrypted: true
                    is_nullable: false
                    is_builtin: false
                    is_readonly: false
                    creation_time: 2022-12-01T10:04:42.777225Z
                    modification_time: 2022-12-01T10:04:42.777225Z
                  - description: Last name
                    name: last_name
                    data_type_name: NAME
                    is_unique: false
                    is_index: false
                    is_substring_index: false
                    is_encrypted: true
                    is_nullable: false
                    is_builtin: false
                    is_readonly: false
                    creation_time: 2022-12-01T10:04:42.777225Z
                    modification_time: 2022-12-01T10:04:42.777225Z
                  - description: Phone number
                    name: phone_number
                    data_type_name: PHONE_NUMBER
                    is_unique: true
                    is_index: true
                    is_substring_index: false
                    is_encrypted: true
                    is_nullable: true
                    is_builtin: false
                    is_readonly: false
                    creation_time: 2022-12-01T10:04:42.777225Z
                    modification_time: 2022-12-01T10:04:42.777225Z
                creation_time: 2022-12-01T10:04:42.777225Z
                modification_time: 2022-12-01T10:04:42.777225Z
            application/pvschema:
              schema:
                $ref: "#/components/schemas/Collection.pvschema"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          description: Reserved for future use.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                error_code: PV1004
                message: The collection is not found.
                context: {}
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Collections
  /api/pvlt/1.0/ctl/bundles:
    get:
      operationId: list-bundles
      summary: List bundles
      description: >-
        Lists the Vault bundles.


        The role that performs this operation must have the `CapCodeReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/Bundle"
                type: array
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Bundles
    post:
      operationId: add-bundle
      summary: Add bundle
      description: >-
        Adds a bundle.


        See [Create the bundles](/guides/create-custom-data-types/create-a-custom-data-type#create-the-bundles) in the Create a custom data type guide for more information on using this operation.


        The role performing this operation must have the `CapCodeWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      requestBody:
        x-has-pii: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Bundle"
            example:
              name: example_bundle
              description: An example bundle that exports a validator, normalizer,
                transformer, and action
              code: U2FtcGxlIGNvZGU=
        description: Details of the bundle including the code that defines the functions
          as properties of the exports object.
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Bundle"
              example:
                name: example_bundle
                description: An example bundle that exports a validator, normalizer,
                  transformer, and action
                exports:
                  validators:
                    - name: is_positive
                      type: validator
                      description: A validator that returns true if its argument is positive.
                      dependencies:
                        properties: []
                  normalizers:
                    - name: to_lower
                      type: normalizer
                      description: A normalizer that formats a string to lowercase without any
                        dependencies.
                  transformers:
                    - name: to_name_with_title
                      type: transformer
                      description: A transformer that accepts a full name and returns it prepended
                        with a title.
                      dependencies:
                        properties:
                          - gender
                          - marital_status
                  actions:
                    - name: decrypt_and_send
                      type: action
                      description: An action that decrypts an object and sends it to a compliant
                        third-party service.
                code: U2FtcGxlIGNvZGU=
                creation_time: 2022-12-02T02:02:14.398599Z
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          description: Reserved for future use.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                error_code: PV1004
                message: The bundle is not found.
                context: {}
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Bundles
  /api/pvlt/1.0/ctl/types:
    get:
      operationId: list-data-types
      summary: List data types
      description: >-
        Lists the Vault data types.


        See Data types for more information.


        The role that performs this operation must have the `CapTypesReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
        - description: If provided, return only types that depend on the bundle with the
            specified name.
          in: query
          name: bundle
          schema:
            type: string
        - description: |
            Options for the operation. Options include:
             - `show_builtins` – show built-in properties.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - show_builtins
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/DataType"
                type: array
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Custom data types
    post:
      operationId: add-data-type
      summary: Add data type
      description: >-
        Adds a data type.


        The role performing this operation must have the `CapTypesWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      requestBody:
        x-has-pii: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DataType"
            example:
              name: student_id
              base_type_name: STRING
              description: A custom data type representing a student ID based on the built-in
                STRING type.
              validator: example_bundle.validate_student_id
              normalizer: example_bundle.normalize_student_id
              transformers:
                - example_bundle.format_student_id
                - example_bundle.mask_first_4_digits
              default_transformer: example_bundle.format_student_id
        description: Details of the data type, including the names and locations of the
          JavaScript functions it uses.
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataType"
              example:
                name: student_id
                base_type_name: STRING
                description: A custom data type representing a student ID based on the built-in
                  STRING type.
                validator: example_bundle.validate_student_id
                normalizer: example_bundle.normalize_student_id
                transformers:
                  - example_bundle.format_student_id
                  - example_bundle.mask_first_4_digits
                default_transformer: example_bundle.format_student_id
                creation_time: 2022-12-01T10:04:42.777225Z
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          description: Reserved for future use.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                error_code: PV1004
                message: The data type is not found.
                context: {}
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Custom data types
  "/api/pvlt/1.0/data/collections/{collection}/count/objects":
    get:
      operationId: get-objects-count
      summary: Get object count
      description: >-
        Gets the number of objects in a collection.


        The role performing this operation must have at least one allowing policy and no denying policies for the `stats` operation.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how Vault uses policies to control access to data.
      parameters:
        - description: The name of the collection containing the objects.
          in: path
          name: collection
          required: true
          schema:
            type: string
            pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
          example: customers
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Count"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Objects
  "/api/pvlt/1.0/data/collections/{collection}/count/tokens":
    get:
      operationId: get-tokens-count
      summary: Get token count
      description: >-
        Gets the number of tokens in a collection.


        The role performing this operation must have at least one allowing policy and no denying policies for the `stats` operation.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how Vault uses policies to control access to data.
      parameters:
        - description: The name of the collection containing the tokens.
          in: path
          name: collection
          required: true
          schema:
            type: string
            pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
          example: customers
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Count"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Tokens
  "/api/pvlt/1.0/data/collections/{collection}/objects":
    get:
      operationId: list-objects
      summary: List objects
      description: >-
        Returns a [paginated list](/api/api-pagination) of objects from a
        collection with all or a subset of object property values. To encrypt
        object property values, set export to true. Values are encrypted using
        the key specified in the [PVAULT_KMS_EXPORT_URI or
        PVAULT_KMS_EXPORT_SEED environment
        variables](/guides/configure/environment-variables#key-management-service).


        The role performing this operation must have both of the following:

        - The `CapDataReader` capability.

        - At least one allowing policy and no denying policies for the `read` operation for each of the properties and the
          collection requested in the call.

        See [identity and access management](/data-security/identity-and-access-management) for more information about how

        capabilities are used to control access to operations and policies are used to control access to data.


        **Warning**: Use of the `unsafe` option, to include all object property values, may expose more private information than is required, use with caution.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - $ref: "#/components/parameters/page_size"
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/export"
        - $ref: "#/components/parameters/trans_param"
        - $ref: "#/components/parameters/tenant_id"
        - description: A comma-separated list of object IDs
          in: query
          name: ids
          schema:
            type: array
            items:
              type: string
              format: uuid
        - description: >
            Options for the operation. Options include:

            - `archived` – whether to list only archived objects. If not specified, list only active objects.

            - `show_builtins` – show built-in properties, can only be specified with `unsafe`.

            - `unsafe` – fetch all the properties, cannot be specified with `props`.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - unsafe
                - show_builtins
                - archived
        - $ref: "#/components/parameters/props"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObjectFieldsPage"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection, properties, or object is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Objects
    post:
      operationId: add-object
      summary: Add object
      description: >-
        Adds an object to a collection. The request must include all the
        non-nullable properties, as defined by the [collection
        schema](/api/operations/list-collection-properties).


        By default, accepts the object fields in JSON format. To pass a raw, unformatted value for a single property, set the `Content-Type` header to `application/octet-stream` and the property name in the `prop` query parameter.


        When adding an object from an external system that uses UUID IDs, you can include the object ID in the request to set the ID in Vault. For example, `"id","463a83d0-a816-4902-abba-2486e0c0a0bb"`. Vault normalizes the ID to lowercase.


        If the object to add is exported from an external system or Vault:

        - set `import` to `true` to import values for the built-in properties `_creation_time`, `_modification_time`, and `_expiration_time`. 

        - if the data is encrypted, to decrypt the data provide the encryption key in `export_key`.


        The role performing this operation must have both of the following:

        - The `CapDataWriter` or the `CapDataCreator` capability.

        - At least one allowing policy and no denying policies for the `write` operation for each of the collection properties
          provided in the call.

        See [identity and access management](/data-security/identity-and-access-management) for more information about how

        capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - $ref: "#/components/parameters/tenant_id"
        - description: Object expiration time in seconds, cannot be set to 0. If not set,
            the default value is used. See the
            `PVAULT_EXPIRATION_ASSOCIATED_OBJECTS` and
            `PVAULT_EXPIRATION_UNASSOCIATED_OBJECTS` environment variables. If
            set to an empty value, the token will be marked to not expire.
          in: query
          name: expiration_secs
          allowEmptyValue: true
          schema:
            type: string
            pattern: ^[0-9]*$
        - $ref: "#/components/parameters/import"
        - $ref: "#/components/parameters/export_key"
        - name: prop
          in: query
          schema:
            $ref: "#/components/schemas/PropertyName"
      requestBody:
        x-has-pii: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ObjectFields"
          application/octet-stream:
            schema:
              type: string
              format: binary
        description: The object details.
        required: true
        x-originalParamName: object
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObjectID"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection or properties is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Objects
  "/api/pvlt/1.0/data/collections/{collection}/tokens":
    post:
      operationId: tokenize
      summary: Tokenize
      description: >
        Creates a token that reference the values of an object's properties. The
        token ID is partially or wholly randomly-generated and, therefore, is
        not sensitive. Supports bulk operations.


        The returned token IDs are in the same order as the object IDs in the request. No tokens are created if any object IDs are invalid or not found.


        If this operation is called for an object ID and properties that have a token:

        - Any token tags are appended to the existing token.

        - If an expiration is specified, then the token expiry is updated. If an expiration is not specified, the token expiry is updated if the default settings result in an expiry date after the token's current expiry date.


        The operation can optionally include a transaction ID. This is an arbitrary string included in the request using the `transaction_id` query parameter. If a transaction ID is included, the token is associated with the transaction ID. The transaction ID can be used to retrieve the token ID by calling the [get by transaction ID](/api/operations/get-by-transaction-id) operation. A transaction ID is unique to the operation and collection. It cannot be used again on future calls to the `tokenize` operation on the same collection. If multiple tokens are created in the `tokenize` operation (bulk), all the tokens are associated with the transaction ID.


        The role performing this operation must have both of these:

        - The `CapTokensWriter` capability.

        - At least one allowing policy and no denying policies for the `tokenize` operation for each of the collection properties specified in the call.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - description: Token expiration time in seconds. If not set, the default
            expiration time is used. See the `PVAULT_EXPIRATION_TOKENS`
            variable. If set to an empty value, the token will be marked to not
            expire.
          in: query
          name: expiration_secs
          allowEmptyValue: true
          schema:
            type: string
            pattern: ^[0-9]*$
        - $ref: "#/components/parameters/tenant_id"
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/transaction_id"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      requestBody:
        x-has-pii: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                $ref: "#/components/schemas/TokenizeRequest"
            example:
              - type: pointer
                object:
                  id: cc9a39c5-4734-4786-b317-e16705d5128f
                props:
                  - phone_number
        description: Details of the tokenization request.
        required: true
        x-originalParamName: object_prop
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/TokenValue"
                type: array
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                objectid: credit_cadr
                error_code: PV3003
                message: One or more values are invalid.
          description: The collection, objects, or properties aren't found or are missing.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Tokens
    get:
      operationId: detokenize
      summary: Detokenize tokens
      description: >
        Returns the object property values for tokens.


        The tokens returned by this operation are defined using three query parameters: `token_ids`, `object_ids`, and `tags`. The operation returns an empty response if it finds no matches. See the [Retrieve a token](/guides/tokenize-personal-data/retrieve-a-token) guide for more information about how to match tokens for this operation.


        The role performing this operation must have all of these:

        - The `CapTokensDetokenizer` capability.

        - Policies:
          + At least one allowing policy and no denying policies for the `detokenize` operation for each of the collection properties that are tokenized by tokens specified in the query.
          + At least one allowing policy and no denying policies for the `read` operation for each of the collection properties that are tokenized by tokens specified in the query.

        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - description: Comma-separated list of object IDs.
          in: query
          name: object_ids
          schema:
            items:
              type: string
              format: uuid
            type: array
        - description: Comma-separated list of tags.
          in: query
          name: tags
          schema:
            type: array
            items:
              $ref: "#/components/schemas/Tag"
        - description: Comma-separated list of token IDs.
          in: query
          name: token_ids
          schema:
            items:
              type: string
            type: array
        - $ref: "#/components/parameters/props"
        - description: >
            Options for the operation. Options include:

            - `include_metadata` - show token metadata in the response.

            - 'include_aggregated_data' - whether to include aggregated data in the response. If not specified, aggregated data is not included. Only applicable if `include_metadata` is set.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - include_metadata
                - include_aggregated_data
        - $ref: "#/components/parameters/tenant_id"
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/DetokenizedToken"
                type: array
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Tokens
    delete:
      operationId: delete-tokens
      summary: Delete tokens
      description: >
        Deletes tokens.


        The tokens deleted are those that match all the criteria in the `token_ids`, `object_ids`,  `tags`, and `tenant_id` parameters. `tenant_id` is matched against the tenant ID of the object owning the token. If the token query finds no matches, the operation returns a 404 error. See [delete tokens](/guides/tokenize-personal-data/delete-a-token) for more details.


        The role performing this operation must have both of these:

        - The `CapTokensWriter` capability.

        - At least one allowing policy and no denying policies for the `delete` operation for the `tokens` resource of the specified collection.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - description: Comma-separated list of object IDs.
          in: query
          name: object_ids
          schema:
            type: array
            items:
              type: string
              format: uuid
        - description: Comma-separated list of tags.
          in: query
          name: tags
          schema:
            type: array
            items:
              type: string
        - description: Comma-separated list of token IDs.
          in: query
          name: token_ids
          schema:
            type: array
            items:
              type: string
        - description: "A Tenant ID. Can only be provided as an additional filter to
            `tokens_ids`, `object_ids`, or `tags`. DEPREDATED: Use X-Tenant-Id
            header instead."
          in: query
          name: tenant_id
          schema:
            type: string
          deprecated: true
        - description: >
            Options for the operation. Options include:

            - `archived` – whether to delete only archived tokens. If not specified, delete only active tokens.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - archived
        - $ref: "#/components/parameters/tenant_id"
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                error_code: PV3009
                message: The token is not found.
          description: The collection or reason aren't found or are missing, the `reason`
            is set to `other` but no `adhoc_reason` is provided, no token query
            parameters are provided, or the query finds no matching tokens.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Tokens
    patch:
      operationId: update-tokens
      summary: Update tokens
      description: >
        Updates token data or token metadata `tags` and `expiration` properties.


        ### Update token metadata


        See the [Update a token](/guides/tokenize-personal-data/update-a-token) guide for more information about updating a token's metadata.


        ### Update token data


        To update token data, all the tokens must:

        * have the same token ID.

        * be token types `pci`, `pci_oneway`, or `randomized` (metadata can be updated in all token types).


        To update a token's data, set the `object` parameter to contain one of these:

        1. Objects stored in Vault by providing their ID. 

        2. Fields not stored in Vault by providing a map of their properties and property values. These fields must conform to the schema of the collection specified in the request. 

        3. Ciphertext. This enables you to update a token's data with a subset of another ciphertext's properties or with a different encryption type or scope.


        Updates to the token's data do not change the token's metadata, token ID, ownership, or lifecycle of the token . However, the data update may affect subsequent tokenizations. For example, if a token of type `pci` with ID "X" is updated, subsequent tokenizations of the new data have the same token ID "X," while tokenizations of the previous data results in a new token ID. See [Tokenization](/data-security/tokenization) for more information on token types.


        :::note

        Update to the token's data overrides the entire existing data.

        :::


        ### Permissions


        The role performing this operation must have both of these:

        - The `CapTokensWriter` capability.

        - At least one allowing policy and no denying policies for the `write` operation for the `tokens` resource of the collection specified in the call.
          - Updating a token's metadata requires the `write` operation for the `tokens` resource of the collection specified in the call.
          - Updating a token's data requires the `tokenize` operation for each of the collection properties specified in the call.
          - For updating both the metadata and the data of a token, only the `tokenize` operation permission is required.

        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.


        ### Query


        The tokens returned by this operation are defined using three query parameters: `token_ids`, `object_ids`, and `tags`. If no tokens are matched, status code 404 is returned. See the [Retrieve a token](/guides/tokenize-personal-data/retrieve-a-token) guide for more information about how to match tokens for this operation.
      parameters:
        - description: Expiration time in seconds for the tokens. If not set, the expiry
            dates of the tokens are not changed.  If set to an empty value, the
            token will be marked to not expire.'
          in: query
          name: expiration_secs
          allowEmptyValue: true
          schema:
            type: string
            pattern: ^[0-9]*$
        - description: Comma-separated list of object IDs.
          in: query
          name: object_ids
          schema:
            type: array
            items:
              type: string
              format: uuid
        - description: Comma-separated list of tags.
          in: query
          name: tags
          schema:
            type: array
            items:
              type: string
        - description: Comma-separated list of token IDs.
          in: query
          name: token_ids
          schema:
            type: array
            items:
              type: string
        - description: >
            Options for the operation. Options include:

            - `archived` – whether to update only archived tokens. If not specified, update only active tokens.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - archived
        - $ref: "#/components/parameters/tenant_id"
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      requestBody:
        x-has-pii: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateTokenRequest"
        description: Update token request details.
        required: true
        x-originalParamName: body
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                error_code: PV3009
                message: The token is not found.
          description: The collection or reason aren't found or are missing, the `reason`
            is set to `other` but no `adhoc_reason` is provided, no token query
            parameters are provided, or the query finds no matching tokens.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Tokens
  "/api/pvlt/1.0/data/collections/{collection}/encrypt/objects":
    post:
      operationId: encrypt
      summary: Encrypt
      description: >
        Creates ciphertext that includes the values of an object's properties.
        Supports bulk operations.


        You can encrypt:


        1. Objects stored in Vault by providing their ID. 

        2. Fields not stored in Vault by providing a map of their properties and property values. However, fields must conform to the collection schema specified in the request. 

        3. Ciphertext. This enables you to create a ciphertext including a subset of another ciphertext's properties or with a different encryption type or scope. To update the property values, use the [update encrypted](/api/operations/update-encrypted) operation.


        :bulb: For brevity, this guide uses the term `object` to refer to the content being encrypted.


        If any request details are invalid, none of the objects are encrypted.


        You can generate ciphertext for the encrypted object with a random initialization vector (randomized) or based on the collection name, input object, and scope (deterministic).


        Using `props`, you can request that the ciphertext include a subset of the collection schema's properties.  However, if a property isn't present in the object or the property value is null, it is not included in the encrypted ciphertext. Also, if you want to include built-in properties, you must include them in `props`.


        The role performing this operation must have both of these:


        - The `CapCryptoEncrypter` capability.

        - At least one allowing policy and no denying policies for the `encrypt` operation for each of the collection properties specified in the call.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how Vault uses capabilities to control access to operations and policies to control access to data.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - description: Encrypted object expiration time in seconds. If not set, the
            default expiration time is used. See the `PVAULT_EXPIRATION_TOKENS`
            variable. If set to an empty value, the encrypted will be marked to
            not expire.
          in: query
          name: expiration_secs
          allowEmptyValue: true
          schema:
            type: string
            pattern: ^[0-9]*$
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - $ref: "#/components/parameters/tenant_id"
      requestBody:
        x-has-pii: true
        description: Details of the encryption request.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/EncryptionRequest"
            example:
              - object:
                  fields:
                    email: john@work.com
                    phone_number: 555-555-5555
                props:
                  - phone_number
                  - email
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EncryptedValue"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                objectid: credit_cadr
                error_code: PV3003
                message: One or more values are invalid.
          description: The collection or properties aren't found, or property values are
            invalid.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Crypto
    patch:
      operationId: update-encrypted
      summary: Update ciphertext and metadata
      description: >
        Returns ciphertext that includes property values from another
        ciphertext. Supports bulk operations.


        This enables the creation of encrypted ciphertext without exposing encrypted property values to the user. 


        The returned ciphertext can have different encryption type, scope, properties, or property values to the source ciphertext. Any property values in the source ciphertext not updated in the request are preserved in the new ciphertext as long as they are included in `props`.


        For example, if the source ciphertext contains `first_name`, `last_name`, and `telephone_number` and `props` specifies `[first_name, last_name]`, then `telephone_number` isn't included in the new encrypted ciphertext.


        The request must include the scope used to encrypt the source ciphertext.


        If any request details are invalid, no ciphertexts are created.


        The role performing this operation must have both of these:


        - The `CapCryptoDecrypter` and `CapCryptoEncrypter` capabilities.

        - At least one allowing policy and no denying policies for the `decrypt` and `encrypt` operations for each of the collection properties specified in the call.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how Vault uses capabilities to control access to operations and policies to control access to data.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - description: >
            Options for the request.

            - `archived` - whether to update only archived encrypted objects. If not specified, update only active encrypted objects.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - archived
        - description: Encrypted object expiration time in seconds. If not set, the
            default expiration time is used. See the `PVAULT_EXPIRATION_TOKENS`
            variable.
          in: query
          name: expiration_secs
          allowEmptyValue: true
          schema:
            type: string
            pattern: ^[0-9]*$
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - $ref: "#/components/parameters/tenant_id"
      requestBody:
        x-has-pii: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/UpdateEncryptionRequest"
        description: >
          Details of the update encrypted object request.

          The request includes the encrypted object to update and the property values to update the encrypted object with.
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EncryptedValue"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                objectid: credit_card
                error_code: PV3003
                message: One or more values are invalid.
          description: The collection or properties aren't found, or property values are
            invalid.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Crypto
  /api/pvlt/1.0/ctl/actions:
    get:
      operationId: list-actions
      summary: List all actions
      description: >
        Lists built-in and custom actions.


        The role performing this operation must have:


        - The `CapActionReader` capability.

        - At least one allowing policy and no denying policies for the `read` operation for all actions.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Action"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Actions
    post:
      operationId: add-action
      summary: Add action
      description: >-
        Adds an action.


        The role performing this operation must have the `CapActionWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      requestBody:
        x-has-pii: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Action"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Actions
  /api/pvlt/1.0/data/analysis/contains:
    post:
      operationId: analysis-contains
      summary: Contains PII data
      description: >
        Checks if text strings contain PII and classifies the findings.


        If you need to obtain details about the location of PII in your strings, use the [locate operation](/api/operations/analysis-locate).


        See the [Find PII](/guides/analyze-for-pii-data) guide for more information on using this operation.


        The role performing this operation must have the `CapAnalysisDetect` capability.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.

        :::note

        This operation uses AI to detect PII. As such, it's possible for PII to be missed or for non-PII text to be classified as PII.

        :::

        :::info

        This feature is enabled on [Vault SaaS](/guides/install/hosted) only. If you're interested in running it with a self-hosted deployment, please [contact us](https://www.piiano.com/contact-us).

        :::
      parameters:
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      requestBody:
        description: List of the text strings to check for PII.
        x-has-pii: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnalysisRequest"
      responses:
        "200":
          description: The request is successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisContainsResponseBody"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Analysis
  "/api/pvlt/1.0/ctl/collections/{collection}":
    get:
      operationId: get-collection
      summary: Get collection
      description: >
        Gets a collection and its properties.


        The collection details can be returned in JSON or PVSchema format using the `format` query parameter or by setting the `Accept` header to `application/json` or `application/pvschema`, respectively. The default is to return JSON.


        See [PVSchema](/guides/reference/pvschema) for more details on the structure and content of PVSchema.


        See the [Retrieve a collection](/guides/manage-collections-and-schemas/retrieve-a-collection) guide for more information on using this operation.


        The role that performs this operation must have the `CapCollectionsReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/jsonOrPvSchemaFormat"
        - description: |
            Options for the operation. Options include:
            - `show_builtins` – show built-in properties in the response.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - show_builtins
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Collection"
              example:
                type: PERSONS
                name: customers
                properties:
                  - description: Date of birth
                    name: date_of_birth
                    data_type_name: DATE_OF_BIRTH
                    is_unique: false
                    is_index: false
                    is_substring_index: false
                    is_encrypted: true
                    is_nullable: true
                    is_builtin: false
                    is_readonly: false
                    creation_time: 2022-12-01T10:04:42.777225Z
                    modification_time: 2022-12-01T10:04:42.777225Z
                  - description: Email
                    name: email
                    data_type_name: EMAIL
                    is_unique: true
                    is_index: true
                    is_substring_index: false
                    is_encrypted: true
                    is_nullable: true
                    is_builtin: false
                    is_readonly: false
                    creation_time: 2022-12-01T10:04:42.777225Z
                    modification_time: 2022-12-01T10:04:42.777225Z
                  - description: First name
                    name: first_name
                    data_type_name: NAME
                    is_unique: false
                    is_index: false
                    is_substring_index: false
                    is_encrypted: true
                    is_nullable: false
                    is_builtin: false
                    is_readonly: false
                    creation_time: 2022-12-01T10:04:42.777225Z
                    modification_time: 2022-12-01T10:04:42.777225Z
                  - description: Last name
                    name: last_name
                    data_type_name: NAME
                    is_unique: false
                    is_index: false
                    is_substring_index: false
                    is_encrypted: true
                    is_nullable: false
                    is_builtin: false
                    is_readonly: false
                    creation_time: 2022-12-01T10:04:42.777225Z
                    modification_time: 2022-12-01T10:04:42.777225Z
                  - description: Phone number
                    name: phone_number
                    data_type_name: PHONE_NUMBER
                    is_unique: true
                    is_index: true
                    is_substring_index: false
                    is_encrypted: true
                    is_nullable: true
                    is_builtin: false
                    is_readonly: false
                    creation_time: 2022-12-01T10:04:42.777225Z
                    modification_time: 2022-12-01T10:04:42.777225Z
                creation_time: 2022-12-01T10:04:42.777225Z
                modification_time: 2022-12-01T10:04:42.777225Z
            application/pvschema:
              schema:
                $ref: "#/components/schemas/Collection.pvschema"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Collections
    patch:
      operationId: update-collection
      summary: Update collection
      description: >
        Updates properties of a collection.


        The update:

        - Adds any properties in the request that are not in the collection.

        - Amends the `description`, `is_unique`, `is_index`, `is_substring_index`, and `is_nullable` attributes, where they have changed, for any properties in the request that are in the collection. 
          - `is_nullable` can only be changed from `false` to `true`. 
          - `is_unique` can only be changed from `true` to `false`.
          - `is_substring_index` can only be changed from `true` to `false`.
          - All other property attributes are ignored.

        :::note

        The combined length of the collection name and the longest property name can not exceed 40 characters.

        :::


        The collection request can be provided in JSON or PVSchema format by setting the `Content-Type` header to `application/json` or `application/pvschema`, respectively. The collection can be returned in JSON or PVSchema format using the `format` query parameter or by setting the  `Accept` header to `application/json` or `application/pvschema`, respectively. The default is to return JSON.


        See [PVSchema](/guides/reference/pvschema) for more details on the structure and content of PVSchema.


        The collection name provided in the path parameter must match the collection name in the JSON or PVSchema.


        The response contains the collection with all the properties.


        :::info

        This command may take a while to complete (e.g., when adding an index) and is excluded from Vault's standard call timeout.

        :::


        See the [Update a collection](/guides/manage-collections-and-schemas/update-a-collection) guide for more information on using this operation.


        The role that performs this operation must have the `CapCollectionsWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/jsonOrPvSchemaFormat"
        - $ref: "#/components/parameters/custom_audit"
        - description: |
            Options for the operation. Options include:
            - `show_builtins` – show built-in properties in the response.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - show_builtins
      requestBody:
        x-has-pii: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Collection"
            example:
              type: PERSONS
              name: customers
              properties:
                - description: Social Security Number
                  name: ssn
                  data_type_name: SSN
                  is_unique: true
                  is_index: true
                  is_substring_index: false
                  is_encrypted: true
                  is_nullable: true
                  is_builtin: false
                  is_readonly: false
                  creation_time: 2023-01-25T17:31:40.291033Z
                  modification_time: 2023-01-25T17:31:40.291033Z
              creation_time: 2023-01-25T16:21:48.308234Z
              modification_time: 2023-01-25T16:21:48.308234Z
          application/pvschema:
            schema:
              type: string
            example: |-
              customers PERSONS (
                ssn SSN NULL UNIQUE INDEX COMMENT 'Social Security Number',
              );
        description: Details of the collection, including its properties.
        required: true
        x-originalParamName: collectionChanges
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Collection"
              example:
                type: PERSONS
                name: customers
                properties:
                  - description: Social Security Number
                    name: ssn
                    data_type_name: ssn
                    is_unique: true
                    is_index: true
                    is_substring_index: false
                    is_encrypted: true
                    is_nullable: true
                    is_builtin: false
                    is_readonly: false
                    creation_time: 2022-12-01T10:20:47.115228Z
                    modification_time: 2022-12-01T10:20:47.115228Z
                creation_time: 2022-12-01T09:45:03.015895Z
                modification_time: 2022-12-01T09:45:03.015895Z
            application/pvschema:
              schema:
                type: string
              example: |-
                customers PERSONS (
                  ssn SSN NULL UNIQUE INDEX COMMENT 'Social Security Number',
                );
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Collections
    delete:
      operationId: delete-collection
      summary: Delete collection
      description: >-
        Deletes a collection.


        See the [Delete a collection](/guides/manage-collections-and-schemas/delete-a-collection) guide for more information on using this operation.


        The role that performs this operation must have the `CapCollectionsWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/custom_audit"
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Collections
  "/api/pvlt/1.0/ctl/collections/{collection}/properties":
    get:
      operationId: list-collection-properties
      summary: List collection properties
      description: >-
        Lists the properties of a collection.


        The role that performs this operation must have the `CapCollectionsReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/custom_audit"
        - description: |
            Options for the operation. Options include: 
            - `show_builtins` – show built-in properties in the response.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - show_builtins
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/Property"
                type: array
              example:
                - description: Date of birth
                  name: date_of_birth
                  data_type_name: DATE_OF_BIRTH
                  is_unique: false
                  is_index: false
                  is_substring_index: false
                  is_encrypted: true
                  is_nullable: true
                  is_builtin: false
                  is_readonly: false
                  creation_time: 2023-01-25T16:21:48.308234Z
                  modification_time: 2023-01-25T16:21:48.308234Z
                - description: Email
                  name: email
                  data_type_name: EMAIL
                  is_unique: true
                  is_index: true
                  is_substring_index: false
                  is_encrypted: true
                  is_nullable: true
                  is_builtin: false
                  is_readonly: false
                  creation_time: 2023-01-25T16:21:48.308234Z
                  modification_time: 2023-01-25T16:21:48.308234Z
                - description: First name
                  name: first_name
                  data_type_name: NAME
                  is_unique: false
                  is_index: false
                  is_substring_index: false
                  is_encrypted: true
                  is_nullable: false
                  is_builtin: false
                  is_readonly: false
                  creation_time: 2023-01-25T16:21:48.308234Z
                  modification_time: 2023-01-25T16:21:48.308234Z
                - description: Last name
                  name: last_name
                  data_type_name: NAME
                  is_unique: false
                  is_index: false
                  is_substring_index: false
                  is_encrypted: true
                  is_nullable: false
                  is_builtin: false
                  is_readonly: false
                  creation_time: 2023-01-25T16:21:48.308234Z
                  modification_time: 2023-01-25T16:21:48.308234Z
                - description: Phone number
                  name: phone_number
                  data_type_name: PHONE_NUMBER
                  is_unique: true
                  is_index: true
                  is_substring_index: false
                  is_encrypted: true
                  is_nullable: true
                  is_builtin: false
                  is_readonly: false
                  creation_time: 2023-01-25T16:21:48.308234Z
                  modification_time: 2023-01-25T16:21:48.308234Z
                - description: Social Security Number
                  name: ssn
                  data_type_name: SSN
                  is_unique: true
                  is_index: true
                  is_substring_index: false
                  is_encrypted: true
                  is_nullable: true
                  is_builtin: false
                  is_readonly: false
                  creation_time: 2023-01-25T17:31:40.291033Z
                  modification_time: 2023-01-25T17:31:40.291033Z
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Collection properties
  "/api/pvlt/1.0/ctl/bundles/{bundle}":
    get:
      operationId: get-bundle
      summary: Get bundle
      description: >-
        Gets a bundle.


        The role that performs this operation must have the `CapCodeReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/bundle_name"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Bundle"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Bundles
    patch:
      operationId: update-bundle
      summary: Update bundle
      description: >-
        Updates a bundle.


        An update is allowed only if the prototypes of the JavaScript functions in the request are a superset of those in the

        bundle.

        The name of the bundle can't be updated.


        The role performing this operation must have the `CapCodeWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/bundle_name"
      requestBody:
        x-has-pii: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PartialBundle"
            example:
              name: example_bundle
              description: An example bundle that exports a validator, normalizer,
                transformer, and action
              code: U2FtcGxlIGNvZGU=
        description: Details of the bundle including the code that defines the functions
          as properties of the exports object. Name can't be updated.
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Bundle"
              example:
                name: example_bundle
                description: An example bundle that exports a validator, normalizer,
                  transformer, and action
                exports:
                  validators:
                    - name: is_positive
                      type: validator
                      description: A validator that returns true if its argument is positive.
                      dependencies:
                        properties: []
                  normalizers:
                    - name: to_lower
                      type: normalizer
                      description: A normalizer that formats a string to lowercase without any
                        dependencies.
                  transformers:
                    - name: to_name_with_title
                      type: transformer
                      description: A transformer that accepts a full name and returns it prepended
                        with a title.
                      dependencies:
                        properties:
                          - gender
                          - marital_status
                  actions:
                    - name: decrypt_and_send
                      type: action
                      description: An action that decrypts an object and sends it to a compliant
                        third-party service.
                code: U2FtcGxlIGNvZGU=
                creation_time: 2022-12-02T02:02:14.398599Z
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          description: The bundle is not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                error_code: PV1004
                message: The bundle is not found.
                context: {}
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Bundles
    delete:
      operationId: delete-bundle
      summary: Delete bundle
      description: >-
        Deletes a bundle.


        The role that performs this operation must have the `CapCodeWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/bundle_name"
        - description: >
            Options for the operation. Options include:

            - `force` – delete the bundle if there is an unused data type referencing it. An unused data type is one that is not used in any object schema. When the bundle is deleted, the data type referencing it is also deleted.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - force
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The bundle is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Bundles
  "/api/pvlt/1.0/ctl/types/{type}":
    get:
      operationId: get-data-type
      summary: Get data type
      description: >
        Gets a data type.


        The role performing this operation must have the `CapTypesReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/type_name"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataType"
              example:
                name: student_id
                base_type_name: STRING
                description: A custom data type representing a student ID based on the built-in
                  STRING type.
                validator: example_bundle.validate_student_id
                normalizer: example_bundle.normalize_student_id
                transformers:
                  - example_bundle.format_student_id
                  - example_bundle.mask_first_4_digits
                default_transformer: example_bundle.format_student_id
                creation_time: 2022-12-01T10:04:42.777225Z
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The data type is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Custom data types
    patch:
      operationId: update-data-type
      summary: Update data type
      description: >
        Updates a data type.


        The update includes:

        - For built-in and custom data types, adding or removing custom transformers.

        - For custom data types, updating the `description`, `default_transformer`, and `validator` attributes.


        :::note

        - The update of `validator` is allowed only if the custom data type does not have a `normalizer`.

        - Built-in transformers can not be added or removed.

        - Custom transformers may be added or removed but must be exported by a loaded bundle.

        :::
      parameters:
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/type_name"
      requestBody:
        x-has-pii: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DataType"
            example:
              description: A custom data type representing a student ID based on the built-in
                STRING type.
              validator: example_bundle.validate_student_id
              transformers:
                - example_bundle.format_student_id
                - example_bundle.mask_first_4_digits
              default_transformer: example_bundle.format_student_id
        description: Details of the properties to update for the data type, including
          the names and locations of the JavaScript functions it uses.
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataType"
              example:
                name: student_id
                base_type_name: STRING
                description: A custom data type representing a student ID based on the built-in
                  STRING type.
                validator: example_bundle.validate_student_id
                normalizer: example_bundle.normalize_student_id
                transformers:
                  - token
                  - example_bundle.format_student_id
                  - example_bundle.mask_first_4_digits
                default_transformer: example_bundle.format_student_id
                creation_time: 2022-12-01T10:04:42.777225Z
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Custom data types
    delete:
      operationId: delete-data-type
      summary: Delete data type
      description: >-
        Deletes a data type.


        The role that performs this operation must have the `CapTypesWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/type_name"
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The data type is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Custom data types
  "/api/pvlt/1.0/data/collections/{collection}/decrypt/objects":
    post:
      operationId: decrypt
      summary: Decrypt
      description: >
        Decrypts ciphertext. Supports bulk operations.


        To decrypt ciphertext, the request must include the scope used when the ciphertext was encrypted. By default, only ciphertext considered active is decrypted. Ciphertext is considered active when its metadata `expiration` property is for the current or a future date. If `options` is set to `archived`, the ciphertext is only decrypted if its metadata `expiration` property is for a date in the past.


        By default, all property values from the ciphertext are returned. Use `props` to return a subset of the encrypted property values.


        If any request details are invalid, none of the ciphertexts are decrypted.


        The role performing this operation must have both of these:


        - The `CapCryptoDecrypter` capability.

        - At least one allowing policy and no denying policies for the `decrypt` operation for each of the collection properties specified in the call.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how Vault uses capabilities to control access to operations and policies to control access to data.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - description: >
            Options for the operation. Options include:

            - `archived` – whether to decrypt only archived objects. If not specified, decrypts only active objects.

            - `include_metadata` - show the encrypted object metadata.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              description: Option for the operation.
              type: string
              enum:
                - archived
                - include_metadata
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - $ref: "#/components/parameters/tenant_id"
      requestBody:
        x-has-pii: true
        description: Details of the decryption request.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/DecryptionRequest"
            example:
              - encrypted_object: ...
                props:
                  - phone_number
                  - email
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DecryptedObject"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                objectid: credit_cadr
                error_code: PV3003
                message: One or more values are invalid.
          description: The collection or properties aren't found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Crypto
  /api/pvlt/1.0/data/analysis/locate:
    post:
      operationId: analysis-locate
      summary: Locate PII data
      description: >
        Locates the positions of PII data in text strings and classifies the
        findings.


        If you only need an indication of whether your strings contain PII, use the [contains operation](/api/operations/analysis-contains).


        See the [Find PII](/guides/analyze-for-pii-data) guide for more information on using this operation.


        The role performing this operation must have the `CapAnalysisLocate` capability.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.


        :::info

        This feature is enabled on [Vault SaaS](/guides/install/hosted) only. If you're interested in running it with a self-hosted deployment, please [contact us](https://www.piiano.com/contact-us).

        :::
      parameters:
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      requestBody:
        description: The locate request.
        x-has-pii: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AnalysisRequest"
      responses:
        "200":
          description: The request is successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AnalysisLocateResponseBody"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Analysis
  "/api/pvlt/1.0/ctl/collections/{collection}/properties/{property}":
    post:
      operationId: add-collection-property
      summary: Add collection property
      description: >-
        Adds a property to a collection.


        The property name in the `property` parameter and request body must match. Only nullable properties can be added to the collection when the collection contains objects.


        :::note

        The combined length of the collection name and the longest property name can not exceed 40 characters.

        :::


        See the [Add a property](/guides/manage-collections-and-schemas/update-a-collection#add-a-property) in the Update a collection guide for more information on using this operation.


        The role performing this operation must have the `CapCollectionsWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/custom_audit"
        - name: property
          in: path
          description: The name of the property.
          required: true
          schema:
            $ref: "#/components/schemas/PropertyName"
      requestBody:
        x-has-pii: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Property"
            example:
              description: Social Security Number
              name: ssn
              data_type_name: ssn
              is_unique: true
              is_index: true
              is_substring_index: false
              is_encrypted: true
              is_nullable: true
        description: Details of the property.
        required: true
        x-originalParamName: property
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Property"
              example:
                description: Social Security Number
                name: ssn
                data_type_name: ssn
                is_unique: true
                is_index: true
                is_substring_index: false
                is_encrypted: true
                is_nullable: true
                is_builtin: false
                is_readonly: false
                creation_time: 2022-12-02T02:02:14.398599Z
                modification_time: 2022-12-02T02:02:14.398599Z
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Collection properties
    get:
      operationId: get-collection-property
      summary: Get collection property
      description: >-
        Gets a property of a collection.


        See the [Get a property](/guides/manage-collections-and-schemas/update-a-collection#get-a-property) in the Update a collection guide for more information on using this operation.


        The role that performs this operation must have the `CapCollectionsReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/custom_audit"
        - description: The name of the property.
          in: path
          name: property
          required: true
          example: first_name
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Property"
              example:
                description: Social Security Number
                name: ssn
                data_type_name: SSN
                is_unique: true
                is_index: true
                is_substring_index: false
                is_encrypted: true
                is_nullable: true
                is_builtin: false
                is_readonly: false
                creation_time: 2023-01-25T17:31:40.291033Z
                modification_time: 2023-01-25T17:31:40.291033Z
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection or property is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Collection properties
    patch:
      operationId: update-collection-property
      summary: Update collection property
      description: >-
        Updates the attributes of a collection property. Can update these
        property attributes:

        * `description`

        * `is_index`

        * `is_substring_index` (only from `true` to `false`)

        * `is_nullable` (only from `false` to `true`)

        * `is_unique` (only from `true` to `false`)


        :::info

        This command may take a while to complete (e.g., when adding an index) and is excluded from Vault's standard call timeout.

        :::


        See the [Update a property](/guides/manage-collections-and-schemas/update-a-collection#update-a-property) in the Update a collection guide for more information on using this operation.


        The role that performs this operation must have the `CapCollectionsWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/custom_audit"
        - description: The name of the property.
          in: path
          name: property
          required: true
          schema:
            type: string
          example: ssn
      requestBody:
        x-has-pii: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdatePropertyRequest"
            example:
              name: email
              description: Email address
              is_index: true
              is_substring_index: false
              is_nullable: true
              is_unique: false
        description: The property details to update.
        required: true
        x-originalParamName: property
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Property"
              example:
                description: Social Security Number
                name: ssn
                data_type_name: ssn
                is_unique: true
                is_index: true
                is_substring_index: false
                is_encrypted: true
                is_nullable: true
                is_builtin: false
                is_readonly: false
                creation_time: 2022-12-02T02:02:14.398599Z
                modification_time: 2022-12-02T02:02:14.398599Z
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection or property wasn't found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Collection properties
    delete:
      operationId: delete-collection-property
      summary: Delete collection property
      description: >-
        Deletes a property from a collection.


        Any values stored against the property in objects are also deleted. This operation is irreversible.


        See the [Delete a property](/guides/manage-collections-and-schemas/update-a-collection#delete-a-property) in the Update a collection guide for more information on using this operation.


        The role that performs this operation must have the `CapCollectionsWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities control access to operations.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/custom_audit"
        - description: The name of the property.
          in: path
          name: property
          required: true
          schema:
            type: string
          example: ssn
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection or property wasn't found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Collection properties
  "/api/pvlt/1.0/data/collections/{collection}/objects/{id}":
    get:
      operationId: get-object-by-id
      summary: Get object
      description: >-
        Returns an object from a collection with all or a subset of object
        property values.


        By default, returns the properties in JSON format. To get a single property's value without formatting, specify the property name in the `prop` query parameter, and set the `Accept` header to `application/octet-stream`.


        The role performing this operation must have both of the following:

        - The `CapDataReader` capability.

        - At least one allowing policy and no denying policies for the `read` operation for each of the properties and the
          collection requested in the call.

        See [identity and access management](/data-security/identity-and-access-management) for more information about how

        capabilities are used to control access to operations and policies are used to control access to data.


        **Warning**: Use of the `unsafe` option, to include all object property values, may expose more private information than is required, use with caution.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - description: The ID of the object.
          in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
            example: 463a83d0-a816-4902-abba-2486e0c0a0bb
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - $ref: "#/components/parameters/trans_param"
        - $ref: "#/components/parameters/tenant_id"
        - description: >
            Options for the operation. Options include:

            - `archived` – whether to list only archived objects. If not specified, list only active objects.

            - `show_builtins` – show built-in properties, can only be specified with `unsafe`.

            - `unsafe` – fetch all the properties, cannot be specified with `props`.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - unsafe
                - show_builtins
                - archived
        - $ref: "#/components/parameters/props"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObjectFields"
            application/octet-stream:
              schema:
                type: string
                format: binary
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection, properties, or object is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Objects
    patch:
      operationId: update-object-by-id
      summary: Update object
      description: >
        Updates properties of an object in a collection.


        By default, accepts the object fields in JSON format. To update a property using a raw, unformatted value, set the `Content-Type` header to `application/octet-stream`, and the a single property name in the `prop` query parameter.


        The role performing this operation must have both of the following:

        - The `CapDataWriter` or the `CapDataUpdater` capability.

        - At least one allowing policy and no denying policies for the `write` operation for each of the collection properties
          specified in the call.

        See [identity and access management](/data-security/identity-and-access-management) for more information about how

        capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - description: The ID of the object.
          in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - $ref: "#/components/parameters/tenant_id"
        - description: Object expiration time in seconds. If not set, the expiration will
            not be changed. See the `PVAULT_EXPIRATION_ASSOCIATED_OBJECTS` and
            `PVAULT_EXPIRATION_UNASSOCIATED_OBJECTS` environment variables. If
            set to an empty value, the object will be marked to not expire.
          in: query
          name: expiration_secs
          allowEmptyValue: true
          schema:
            type: string
            pattern: ^[0-9]*$
        - description: >
            Options for the operation. Options include:

            - `archived` – whether to update only archived objects. If not specified, update only active objects.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - archived
        - $ref: "#/components/parameters/import"
        - $ref: "#/components/parameters/export_key"
        - name: prop
          in: query
          schema:
            $ref: "#/components/schemas/PropertyName"
      requestBody:
        x-has-pii: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ObjectFields"
          application/octet-stream:
            schema:
              type: string
              format: binary
        description: The object properties to update.
        required: true
        x-originalParamName: object
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection, properties, or object is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Objects
    delete:
      operationId: delete-object-by-id
      summary: Delete object
      description: >-
        Deletes an object from a collection. This operation is irreversible.


        The role performing this operation must have both of the following:

        - The `CapDataWriter` or the `CapDataDeleter` capability.

        - At least one allowing policy and no denying policies for the `delete` operation for each of the properties defined for
          the collection specified in the call.

          
        See [identity and access management](/data-security/identity-and-access-management) for more information about how

        capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - description: The ID of the object.
          in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
        - description: >
            Options for the operation. Options include:

            - `archived` – whether to delete only archived objects. If not specified, delete only active objects.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - archived
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - $ref: "#/components/parameters/tenant_id"
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection or object is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Objects
  "/api/pvlt/1.0/ctl/actions/{action}":
    get:
      operationId: get-action-by-name
      summary: Get action
      description: >
        Gets an action.


        The role performing this operation must have:


        - The `CapActionReader` capability.

        - At least one allowing policy and no denying policies for the `read` operation for the action provided in the call.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/action_name"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Action"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Actions
    delete:
      operationId: delete-action
      summary: Delete action
      description: >-
        Deletes an action.


        You cannot delete a built-in action.


        The role performing this operation must have the `CapActionWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/action_name"
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The bundle is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Actions
  "/api/pvlt/1.0/data/collections/{collection}/encrypt/blob":
    post:
      operationId: encrypt-blob
      summary: Encrypt blob
      description: >-
        Creates ciphertext for the value of a BLOB type property.


        Receives a query parameter, `prop`, containing the name of a BLOB type property, and raw bytes (not a JSON object) in the request body. The ciphertext is returned in the response body as raw bytes (application/octet-stream`).


        See [Encrypt](/api/operations/encrypt) for more information about the encryption process and request parameters.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - description: Encrypted object expiration time in seconds. If not set, the
            default expiration time is used. See the `PVAULT_EXPIRATION_TOKENS`
            variable. If set to an empty value, the encrypted ciphertext blob
            does not expire.
          in: query
          name: expiration_secs
          allowEmptyValue: true
          schema:
            type: string
            pattern: ^[0-9]*$
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - name: prop
          in: query
          required: true
          schema:
            $ref: "#/components/schemas/PropertyName"
        - name: type
          in: query
          schema:
            $ref: "#/components/schemas/EncryptionType"
        - name: scope
          in: query
          description: >
            A classification for the encrypted object that is added to the
            ciphertext as associated data (AAD).

            An object encrypted with a scope can be decrypted only with the same scope.
          schema:
            type: string
            default: default
          example: default
        - name: tags
          in: query
          description: >
            Comma-separated list of tags to attach to the metadata of the
            encrypted object.

            The maximum number of allowed tags is defined by the [`PVAULT_DB_MAX_TOKEN_TAGS` environment variable](/guides/configure/environment-variables#database) (default 10).

            Tags are not supported for the `deterministic` encryption type.
          schema:
            type: string
            maxLength: 256
          example: tag1,tag2
      requestBody:
        x-has-pii: true
        description: Details of the encryption request.
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "200":
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                objectid: credit_cadr
                error_code: PV3003
                message: One or more values are invalid.
          description: The collection or properties aren't found, or property values are
            invalid.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Crypto
  "/api/pvlt/1.0/data/collections/{collection}/decrypt/blob":
    post:
      operationId: decrypt-blob
      summary: Decrypt blob
      description: >-
        Decrypts ciphertext and returns the plaintext as raw bytes
        (`application/octet-stream`) not a JSON object.


        See [Decrypt](/api/operations/decrypt) for more information about the decryption process and request parameters.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - description: >
            Options for the operation. Options include:

            - `archived` – whether to decrypt only archived objects. If not specified, decrypts only active objects.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              description: Option for the operation.
              type: string
              enum:
                - archived
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - name: prop
          in: query
          required: true
          schema:
            $ref: "#/components/schemas/PropertyName"
        - name: scope
          in: query
          description: >
            A classification for the encrypted object that is added to the
            ciphertext as associated data (AAD).

            An object encrypted with a scope can be decrypted only with the same scope.
          schema:
            type: string
            default: default
          example: default
      requestBody:
        x-has-pii: true
        description: Details of the decryption request.
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "200":
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                objectid: credit_cadr
                error_code: PV3003
                message: One or more values are invalid.
          description: The collection or properties aren't found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Crypto
  "/api/pvlt/1.0/data/collections/{collection}/hash/objects":
    post:
      operationId: hash-objects
      summary: Create hash
      description: >-
        Creates a deterministic hash based on an object's property values,
        collection, and scope. Supports bulk operations.


        This operation is similar to using the [tokenize](/api/operations/tokenize) operation for a token of type `deterministic`. The hash value is identical to the token ID generated for the same combination of collection, object, property values, and scope. However, unlike the token, this hash is not stored in Vault's storage and, as such, cannot be detokenized, searched, or invalidated.


        The role performing this operation must have both of these:


        - The `CapCryptoHasher` capability.

        - At least one allowing policy and no denying policies for the `hash` operation for each of the collection properties specified in the call.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how Vault uses capabilities to control access to operations and policies to control access to data.

        ``
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      requestBody:
        x-has-pii: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/HashObjectRequest"
        description: Details of the hashing request.
        required: true
        x-originalParamName: object_prop
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TokenValue"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                objectid: credit_cadr
                error_code: PV3003
                message: One or more values are invalid.
          description: The collection, objects, or properties aren't found or are missing.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Crypto
  "/api/pvlt/1.0/data/collections/{collection}/rotate/tokens":
    post:
      operationId: rotate-tokens
      summary: Rotate tokens
      description: >
        Generates new token IDs for a list of tokens.


        The role performing this operation must have both of these:

        - The `CapTokensWriter` capability.

        - At least one allowing policy and no denying policies for the `write` operation for the `tokens` resource of the specified collection.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - description: Comma-separated list of token IDs.
          in: query
          name: token_ids
          required: true
          schema:
            items:
              type: string
            type: array
        - $ref: "#/components/parameters/tenant_id"
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RotatedTokens"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                token_ids: d27923c6-5d16-41e3-89ee-118b05a25372
                error_code: PV3087
                message: One or more token IDs not found.
          description: The collection, reason, or tokens aren't found or are missing or
            the `reason` is set to `other` but no `adhoc_reason` is provided.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Tokens
  /api/pvlt/1.0/data/actions/http_call:
    post:
      operationId: invoke-http-call-action
      summary: Invoke HTTP call action
      description: >
        Invokes the built-in `http_call` action.


        The `http_call` action enables Vault to issue an HTTP call using a template that includes references to sensitive data.


        Read more about [using the `http_call` action](/guides/use-third-party-services/about-http-call-action).


        The role performing this operation must have:


        - The `CapActionInvoker` capability.

        - At least one allowing policy and no denying policies for the `invoke` operation for the action provided in the call.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      requestBody:
        description: The request specification. See [http_call request
          body](/guides/reference/http-call-request) for more details.
        x-has-pii: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HTTPCallActionInput"
      responses:
        "200":
          description: The request is successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HTTPCallActionResult"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Actions
  "/api/pvlt/1.0/data/actions/{action}":
    post:
      operationId: invoke-action
      summary: Invoke action
      description: >
        Invokes an action.


        The body of the request is passed to the action function parameters, and the result of the action function is returned in the response. 


        The role performing this operation must have:


        - The `CapActionInvoker` capability.

        - At least one allowing policy and no denying policies for the `invoke` operation for the action provided in the call.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - $ref: "#/components/parameters/action_name"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      requestBody:
        description: Details of the action to execute.
        x-has-pii: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActionInput"
      responses:
        "200":
          description: The request is successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActionResult"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Actions
  "/api/pvlt/1.0/data/collections/{collection}/query/tokens":
    post:
      operationId: search-tokens
      summary: Search tokens
      description: >
        Lists tokens with their metadata. 


        The tokens returned by this operation are defined using three query parameters: `token_ids`, `object_ids`, and `tags`. The operation returns an empty response if it finds no matches. See the [Retrieve a token](/guides/tokenize-personal-data/retrieve-a-token) guide for more information about how to match tokens for this operation. 


        The role performing this operation must have all of these:

        - The `CapTokensReader` capability.

        - At least one allowing policy and no denying policies for the `read` operation for the `tokens` resource of the specified collection.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - description: >
            Options for the operation. Options include:

            - `archived` – whether to search only archived tokens. If not specified, search only active tokens.

            - 'include_aggregated_data' - whether to include aggregated data in the response. If not specified, aggregated data is not included.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - archived
                - include_aggregated_data
        - $ref: "#/components/parameters/tenant_id"
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      requestBody:
        x-has-pii: false
        description: The token query.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueryToken"
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/TokenMetadata"
                type: array
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Tokens
  /api/pvlt/1.0/data/info/health:
    get:
      operationId: data-health
      summary: Get data service health/status
      description: >-
        Gets the status of the service.


        The status codes returned follow the IETF standard [Health Check Response Format for HTTP APIs](https://datatracker.ietf.org/doc/html/draft-inadarei-api-health-check-05). For example, `pass` is returned when the service is up.


        The role performing this operation must have the `CapDataReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      tags:
        - System
  /api/pvlt/1.0/ctl/info/health:
    get:
      operationId: control-health
      summary: Get control service health/status
      description: >-
        Gets the status of the service.


        The status codes returned follow the IETF standard [Health Check Response Format for HTTP APIs](https://datatracker.ietf.org/doc/html/draft-inadarei-api-health-check-05). For example, `pass` is returned when the service is up.
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      tags:
        - System
  /api/pvlt/1.0/ctl/info/cluster:
    get:
      operationId: get-cluster-info
      summary: Get cluster information
      description: >-
        Get Cluster Information.


        Returns the vault's generation and the generations of all the workers (Vault instances with a [Data component](/architecture/components)).


        Vault instances with only a Control component are not displayed in the response.


        The role that performs this operation must have the `CapClusterInfoReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AllGenerations"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - System
  "/api/pvlt/1.0/data/collections/{collection}/transaction_id/{id}":
    get:
      operationId: get-by-transaction-id
      summary: Get tokens by transaction ID
      description: >-
        Returns the list of token IDs associated with a transaction ID, an
        optional identifier passed to the [tokenize](/api/operations/tokenize)
        operation.


        The role performing this operation must have the `CapTransactionIdReader` capability, or another capability that matches the URL, such as the `CapDataReader` capability.
      parameters:
        - description: The transaction ID.
          in: path
          name: id
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionID"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Tokens
  /api/pvlt/1.0/system/admin/lifecycle/gc:
    post:
      operationId: garbage-collection
      summary: Delete objects and tokens
      description: >
        Deletes objects and tokens that have been archived for longer than the
        retention period and token transaction IDs with no associated tokens.


        :::note

        This operation deletes a maximum of 10,000 items. To delete all items, repeat calls until the count of deleted items reaches zero. Using the [prune job](/guides/prune-archived-data#configuring-the-prune-job), rather than calling the API, is recommended.


        For ad-hoc deletion of archived records, use the [Delete objects and tokens](/cli/reference#delete-objects-and-tokens) CLI command, which deletes all relevant items.

        :::


        See [Object life cycle](/data-privacy/object-lifecycle) for more information on how objects and tokens are archived and how deletion is affected by the retention period.
      parameters:
        - description: >
            Whether to delete objects, tokens, or token transaction IDs with no
            associated tokens. Options are:

            - `objects_only` – delete only objects.

            - `tokens_only` – delete only tokens.

            - `transaction_ids_only` – delete only token transaction IDs with no associated tokens.
          in: query
          name: filter
          schema:
            type: string
            enum:
              - objects_only
              - tokens_only
              - transaction_ids_only
        - description: Whether to respond with how many objects and tokens are available
            for deletion, without deleting them.
          in: query
          name: dry_run
          schema:
            default: false
            type: boolean
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: "#/components/schemas/DeletionCount"
                type: array
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - System
  /api/pvlt/1.0/system/debug/error/trigger:
    post:
      operationId: trigger-error
      summary: Trigger artificial error
      description: >-
        Manually trigger an artificial error for testing purposes.


        The role that performs this operation must have the `CapErrorWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      requestBody:
        content:
          application/json:
            schema: {}
        x-has-pii: true
      responses:
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/500"
        "403":
          $ref: "#/components/responses/500"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - System
  /api/pvlt/1.0/system/info/configuration:
    get:
      operationId: get-configuration
      summary: Get system configuration
      description: >-
        Get the current active system configuration.


        The role that performs this operation must have the `CapInfoReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      responses:
        "200":
          content:
            application/toml:
              schema:
                $ref: "#/components/schemas/Config"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - System
  /api/pvlt/1.0/system/info/license:
    get:
      operationId: get-license
      summary: Get license
      description: >-
        Gets information on the currently used license.


        The role that performs this operation must have the `CapInfoReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/License"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - System
    post:
      operationId: set-license
      summary: Set license
      description: >-
        Sets the license key for the Vault. 


        :::note

        In the hosted version of Vault, Piiano manages and sets the license key. 

        :::
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      requestBody:
        x-has-pii: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LicenseKey"
        description: The license key.
        required: true
        x-originalParamName: key
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - System
  /api/pvlt/1.0/system/info/version:
    get:
      operationId: get-vault-version
      summary: Get Vault version
      description: Gets the version of Vault.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProductVersion"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - System
  "/api/pvlt/1.0/data/collections/{collection}/bulk/objects":
    post:
      operationId: add-objects
      summary: Add objects (bulk)
      description: >
        Adds objects to a collection. The request must include all the
        non-nullable properties for each object, as defined by the collection
        schema. Use the [list collection
        properties](/api/operations/list-collection-properties) operation to
        check the collection schema.


        By default, accepts the object fields in JSON format. To pass a raw, unformatted value for a single property, set the `Content-Type` header to `application/octet-stream` and the property name in the `prop` query parameter.


        When adding objects from an external system that uses UUID IDs, you can include the object IDs in the request to set the IDs in Vault. For example, `"id","463a83d0-a816-4902-abba-2486e0c0a0bb"`. Vault normalizes the IDs to lowercase.


        If the objects to add are exported from an external system or Vault:

        - set `import` to `true` to import values for the built-in properties `_creation_time`, `_modification_time`, and `_expiration_time`. 

        - if the data is encrypted, to decrypt the data provide the encryption key in `export_key`.


        If any object add fails, the operation fails and no objects are added.


        The maximum number of objects that can be added in one operation is determined by the [`PVAULT_SERVICE_MAX_PAGE_SIZE` environment variable](/guides/configure/environment-variables#pvault_service_max_page_size).


        See the [add object](/api/operations/add-object) operation to add an object to a collection.


        The role performing this operation must have both of the following:

        - The `CapDataWriter` or the `CapDataCreator` capability.

        - For each object in the request, at least one allowing policy and no denying policies for the `write` operation for each object property.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - $ref: "#/components/parameters/tenant_id"
        - description: Object expiration time in seconds, cannot be set to 0. If not set,
            the default value is used. See the
            `PVAULT_EXPIRATION_ASSOCIATED_OBJECTS` and
            `PVAULT_EXPIRATION_UNASSOCIATED_OBJECTS` environment variables. If
            set to an empty value, the objects will be marked to not expire.
          in: query
          name: expiration_secs
          allowEmptyValue: true
          schema:
            type: string
            pattern: ^[0-9]*$
        - $ref: "#/components/parameters/import"
        - $ref: "#/components/parameters/export_key"
        - name: prop
          in: query
          schema:
            $ref: "#/components/schemas/PropertyName"
      requestBody:
        x-has-pii: true
        description: |
          List of objects to add.
          The order of the objects in this array is preserved in the response.
        content:
          application/json:
            schema:
              description: |
                List of objects to add.
              type: array
              items:
                $ref: "#/components/schemas/ObjectFields"
              example:
                - date_of_birth: 1993-02-22
                  email: patfar@example.com
                  first_name: Pat
                  last_name: Far
                  phone_number: "+11011010101"
                - date_of_birth: 1994-12-03
                  email: ronfar@example.com
                  first_name: Ron
                  last_name: Far
                  phone_number: "+19099090909"
        required: true
        x-originalParamName: object
      responses:
        "200":
          $ref: "#/components/responses/Bulk200Response"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection or properties is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Objects
    patch:
      operationId: update-objects
      summary: Update objects (bulk)
      description: >
        Updates properties of objects in a collection.


        If any object update fails, the operation fails and no objects are updated.


        The maximum number of objects that can be updated in one operation is determined by the [`PVAULT_SERVICE_MAX_PAGE_SIZE` environment variable](/guides/configure/environment-variables#pvault_service_max_page_size).


        The role performing this operation must have both of the following:

        - The `CapDataWriter` or the `CapDataUpdater` capability.

        - For each object in the request, at least one allowing policy and no denying policies for the `write` operation for each of the object's properties.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how 

        capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - description: Expiration time in seconds for the tokens. If not set, the expiry
            dates of the tokens are not changed.
          in: query
          name: expiration_secs
          allowEmptyValue: true
          schema:
            type: string
            pattern: ^[0-9]*$
        - description: >
            Options for the operation. Options include:

            - `archived` – whether to update only archived objects. If not specified, updates only active objects.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - archived
        - name: prop
          in: query
          schema:
            $ref: "#/components/schemas/PropertyName"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - $ref: "#/components/parameters/import"
        - $ref: "#/components/parameters/export_key"
        - $ref: "#/components/parameters/tenant_id"
      requestBody:
        x-has-pii: true
        description: |
          List of objects properties to update.
          The order of the objects in the array is preserved in the response.
        content:
          application/json:
            schema:
              description: |
                List of objects properties to update.
              type: array
              items:
                $ref: "#/components/schemas/ObjectFields"
            example:
              - id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
                phone_number: "+11011010102"
              - id: 69861845-8405-430c-b8ef-7e646d153149
                phone_number: "+19099090908"
      responses:
        "200":
          $ref: "#/components/responses/Bulk200Response"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Objects
    delete:
      operationId: delete-objects
      summary: Delete objects (bulk)
      description: >
        Deletes objects from a collection. This operation is irreversible.


        If any object delete fails, the operation fails and no objects are deleted.


        The maximum number of objects that can be deleted in one operation is determined by the [`PVAULT_SERVICE_MAX_PAGE_SIZE` environment variable](/guides/configure/environment-variables#pvault_service_max_page_size).



        The role performing this operation must have both of the following:

        - The `CapDataWriter` or the `CapDataDeleter` capability.

        - At least one allowing policy and no denying policies for the `delete` operation for each of the properties defined for
          the collection specified in the call.

        See [identity and access management](/data-security/identity-and-access-management) for more information about how

        capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - description: >
            Options for the operation. Options include:

            - `archived` – whether to delete only archived objects. If not specified, deletes only active objects.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - archived
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - $ref: "#/components/parameters/tenant_id"
      requestBody:
        x-has-pii: false
        description: |
          List of objects to delete.
          The order of the objects in the array is preserved in the response.
        content:
          application/json:
            schema:
              description: |
                List of objects to delete.
              type: array
              items:
                $ref: "#/components/schemas/ObjectID"
              example:
                - id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
                - id: 69861845-8405-430c-b8ef-7e646d153149
      responses:
        "200":
          $ref: "#/components/responses/Bulk200Response"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection or object is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Objects
  "/api/pvlt/1.0/data/collections/{collection}/query/objects":
    post:
      operationId: search-objects
      summary: Search objects
      description: >-
        Returns a [paginated list](/api/api-pagination) of objects, with
        property values, from a collection that satisfies a query.


        You can read more about full-match searches in the [Search objects](/guides/write-and-read-personal-data/search-objects/string-search-objects) guide and about substring searches in the [Substring search objects](/guides/write-and-read-personal-data/search-objects/substring-search-objects) guide.


        The role performing this operation must have all the following:

        - The `CapDataSearcher` capability.

        - Policies:
          + At least one allowing policy and no denying policies for the `read` operation for each of the collection properties
            specified in the `props` query parameter.
          + At least one allowing policy and no denying policies for the `search` operation for each of the collection
            properties
            specified in the `query` body parameter.

        See [identity and access management](/data-security/identity-and-access-management) for more information about how

        capabilities are used to control access to operations and policies are used to control access to data.


        **Warning**: Use of the `unsafe` option, to include all object property values, may expose more private information than is required, use with caution..
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - $ref: "#/components/parameters/page_size"
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/trans_param"
        - $ref: "#/components/parameters/tenant_id"
        - description: >
            Options for the operation. Options include:

            - `archived` – whether to search only archived objects. If not specified, search only active objects.

            - `show_builtins` – show built-in properties, can only be specified with `unsafe`.

            - `unsafe` – fetch all the properties, cannot be specified with `props`.
          in: query
          name: options
          allowEmptyValue: true
          schema:
            type: array
            uniqueItems: true
            items:
              type: string
              enum:
                - unsafe
                - show_builtins
                - archived
        - $ref: "#/components/parameters/props"
      requestBody:
        x-has-pii: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Query"
            example:
              in:
                first_name:
                  - Pat
              match:
                date_of_birth: 1993-02-22
        description: >
          This is a JSON object consisting of maps in which the keys are
          property names. 

          The `in` map maps a property name to an array of possible values for that property.

          The `match` map maps a property name to the required value for that property.

          The `like` map maps a property name to a search pattern that the property value should match.

          An object matches the query if the object meets the requirements of both maps.

          For example:

          ```json

          {
            "in": {
              "email": ["john@work.com", "john@home.com"],
            },
            "match": {
              "first_name": "John",
              "last_name": "Doe"
            }
          }

          ```

          is equivalent to:

          ```sql

          WHERE first_name = 'John' AND last_name='Doe' AND email IN ('john@work.com', 'john@home.com')

          ```


          Another example:

          ```json

          {
            "like": {
              "email": "*john*",
            },
            "match": {
              "region": "US"
            }
          }

          ```

          is equivalent to:

          ```sql

          WHERE email LIKE '%john%' AND region = 'US'

          ```
        required: true
        x-originalParamName: query
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ObjectFieldsPage"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The collection or properties is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Objects
  /api/pvlt/1.0/ctl/iam/conf:
    get:
      operationId: get-iam-conf
      summary: Get IAM configuration
      description: >-
        Gets the identity and access management (IAM) configuration in TOML
        format.


        The role that performs this operation must have the `CapIAMReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      responses:
        "200":
          content:
            application/toml:
              schema:
                $ref: "#/components/schemas/IAMConfig"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - IAM
    post:
      operationId: set-iam-conf
      summary: Set IAM configuration
      description: >-
        Sets the identity and access management (IAM) configuration.


        The role that performs this operation must have the `CapIAMWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      requestBody:
        x-has-pii: false
        content:
          application/toml:
            schema:
              $ref: "#/components/schemas/IAMConfig"
        description: IAM configuration in TOML format.
        required: true
        x-originalParamName: auth_config
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - IAM
  /api/pvlt/1.0/ctl/iam/admin/set-api-key:
    post:
      operationId: set-admin-api-key
      summary: Set Admin API key
      description: >
        Set the Admin user's API key.


        Vault always has an administrative user account with the user name `Admin`. You use this account to update the configuration of Vault.


        The API key should meet the specified criteria:

         - It must be at least 15 characters long.
         - It must contain a combination of digits, lowercase letters, and uppercase letters.

        This API is restricted to the Admin user. 


        The Admin user API key can also be set using the [`PVAULT_SERVICE_ADMIN_API_KEY` environment variable](/guides/configure/environment-variables#pvault_service_admin_api_key).
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      requestBody:
        x-has-pii: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AdminAPIKey"
        description: The API key of the Admin user to set.
        required: true
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          description: The caller doesn't have the required access rights or attempts to
            set a password for the Admin user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                error_code: PV2021
                message: setting a password for Admin is not allowed.
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - IAM
  /api/pvlt/1.0/ctl/iam/user/update-expiration:
    post:
      operationId: update-api-key-expiration
      summary: Update user API key expiration
      description: >-
        Update a user's API key expiration.


        The role that performs this operation must have the `CapIAMWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      requestBody:
        x-has-pii: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserNameExpiry"
        description: The name of the user and the expiration in seconds to update API key.
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKeyExpiry"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The user is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - IAM
  "/api/pvlt/1.0/ctl/iam/user/{user}":
    get:
      operationId: get-user
      summary: Get a user details
      description: >-
        Get a user's details.


        The role that performs this operation must have the `CapIAMReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
        - description: The name of the user.
          in: path
          name: user
          required: true
          schema:
            type: string
            example: some_name
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserDetails"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The user is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - IAM
  /api/pvlt/1.0/ctl/iam/user/regen:
    post:
      operationId: regenerate-user-api-key
      summary: Regenerate user API key
      description: >-
        Regenerates a user's API key. The existing API key is invalidated. This
        operation is irreversible.


        :::note

        You cannot regenerate the key for the Admin user. See [Set the admin's API key](/guides/manage-users-and-policies/set-admin-api-key) for information on how to set a value for this key.

        :::


        The role that performs this operation must have the `CapIAMWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      requestBody:
        x-has-pii: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserName"
        description: The name of the user to regenerate API key for.
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKey"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          description: The caller doesn't have the required access rights or attempts to
            generate a key for the Admin user.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
              example:
                error_code: PV2021
                message: Regenerating a key for Admin is not allowed.
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rest.HTTPError"
          description: The user is not found.
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - IAM
  "/api/pvlt/1.0/data/collections/{collection}/export/tokens":
    get:
      operationId: export-tokens
      summary: Export tokens
      description: >
        Internal operation that lists token details for export by the CLI.


        Limitations:

        - Export of tokens of type `pci_oneway` is not supported.


        The role performing this operation must have:

        - The `CapTokensExporter` capability.

        - At least one allowing policy and no denying policies for the `detokenize` operation for each of the collection properties that are tokenized in tokens specified in the query.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - $ref: "#/components/parameters/page_size"
        - $ref: "#/components/parameters/cursor"
        - description: Comma-separated list of token types.
          in: query
          name: token_types
          schema:
            type: array
            items:
              $ref: "#/components/schemas/TokenType"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenDataPage"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Tokens
  "/api/pvlt/1.0/data/collections/{collection}/import/tokens":
    post:
      operationId: import-tokens
      summary: Import tokens
      description: >
        Internal operation that imports token details that were previously
        exported by the CLI.


        Limitations:

        - Import of tokens of type `pci_oneway` and `deterministic` is not supported.

        - Import of tokens of type 'pci' is supported only if the token data is not present in the Vault.


        The role performing this operation must have:

        - The `CapTokensImporter` capability.

        - At least one allowing policy and no denying policies for the `write` operation for the `tokens` resource of the specified collection.


        See [identity and access management](/data-security/identity-and-access-management) for more information about how capabilities are used to control access to operations and policies are used to control access to data.
      parameters:
        - $ref: "#/components/parameters/collection_name"
        - $ref: "#/components/parameters/adhoc_reason"
        - $ref: "#/components/parameters/reason"
        - $ref: "#/components/parameters/custom_audit"
        - $ref: "#/components/parameters/reload_cache"
        - $ref: "#/components/parameters/export_key"
      requestBody:
        x-has-pii: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                $ref: "#/components/schemas/TokenData"
        description: Details of the tokens to import.
        required: true
      responses:
        "200":
          description: >
            The request is successful.

            However, this status doesn't indicate that the operation imported all the tokens.

            Check the response body for the status of each token.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImportTokensBulkResponse"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Tokens
  /api/pvlt/1.0/system/admin/keys/rotate:
    post:
      operationId: rotate-keys
      summary: Rotate data encryption keys
      description: >-
        Rotates all the KMS keys that Vault uses to encrypt properties, tokens,
        and more.


        :::note

        Key rotation not managed in the hosted version of Vault.

        :::


        When the keys are rotated, new data is encrypted with the new key. All old keys are retained, so that content encrypted with previous keys can be decipherable.


        The role that performs this operation must have the `CapKMSWriter` capability. See [Access control](/data-security/identity-and-access-management#access-control) for more information about how capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - System
  /api/pvlt/1.0/system/admin/export_key:
    get:
      operationId: get-export-key
      summary: Get export key
      description: >-
        Gets an encrypted copy of the key used to encrypt exported data.

        The key is encrypted using the export KMS key defined by the [`PVAULT_KMS_EXPORT_URI` or `PVAULT_KMS_EXPORT_SEED` environment variables](/guides/configure/environment-variables#key-management-service).

        When importing data, the key is provided to the Vault and decrypted by the KMS, then used to decrypt the data.


        The role that performs this operation must have the `CapExportKeyReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      responses:
        "200":
          description: The request is successful.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExportKeyResponse"
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - System
  /api/pvlt/1.0/system/confvar:
    delete:
      operationId: clear-all-conf-vars
      summary: Clear configuration variables
      description: >-
        Clears all dynamic configuration variables.


        :::note

        This API is unavailable in the hosted version of Vault. 

        :::


        The role performing this operation must have the `CapConfvarWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Config Vars
  "/api/pvlt/1.0/system/confvar/{name}":
    get:
      operationId: get-conf-var
      summary: Get configuration variable
      description: >-
        Gets a dynamic configuration variable by name. 


        :::note

        This API is unavailable in the hosted version of Vault. 

        :::


        The variables that can be obtained are:


        - `log_level`


        The role that performs this operation must have the `CapConfvarReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
        - description: The name of the configuration variable.
          in: path
          name: name
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfVar"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Config Vars
    post:
      operationId: set-conf-var
      summary: Set configuration variable
      description: >-
        Sets a dynamic configuration variable by name. 


        :::note

        This API is unavailable in the hosted version of Vault. 

        :::


        The variables that can be set are:


        - `log_level` which can take the values of `debug`, `info`, `warn`, and `error`.

        - `trace_sql` Indicates whether sql logs are enabled. values are `true` or `false`.


        The role that performs this operation must have the `CapConfvarWriter` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
        - description: The name of the configuration variable.
          in: path
          name: name
          required: true
          schema:
            type: string
      requestBody:
        x-has-pii: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfVarValue"
        description: Value of the configuration.
        required: true
        x-originalParamName: value
      responses:
        "200":
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - Config Vars
  /api/pvlt/1.0/system/info/kms:
    get:
      operationId: get-kms
      summary: Get KMS status
      description: >-
        Gets the status of the configured KMS.


        The role that performs this operation must have the `CapKMSReader` capability.

        See [Access control](/data-security/identity-and-access-management#access-control) for more information about how

        capabilities are used to control access to operations.
      parameters:
        - $ref: "#/components/parameters/custom_audit"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KMSStatusResponse"
          description: The request is successful.
        "400":
          $ref: "#/components/responses/400"
        "401":
          $ref: "#/components/responses/401"
        "403":
          $ref: "#/components/responses/403"
        "404":
          $ref: "#/components/responses/404"
        "405":
          $ref: "#/components/responses/405"
        "409":
          $ref: "#/components/responses/409"
        "410":
          $ref: "#/components/responses/410"
        "500":
          $ref: "#/components/responses/500"
        "503":
          $ref: "#/components/responses/503"
      security:
        - bearerAuth: []
      tags:
        - System
components:
  parameters:
    jsonOrPvSchemaFormat:
      description: The format of the response. Overrides any `Accept` header value provided.
      in: query
      name: format
      schema:
        type: string
        enum:
          - pvschema
          - json
        default: json
    bundle_name:
      in: path
      name: bundle
      required: true
      schema:
        description: The name of a bundle.
        type: string
        maxLength: 450
        pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
        example: bundle
    collection_name:
      in: path
      name: collection
      required: true
      schema:
        description: The name of a collection.
        type: string
        maxLength: 40
        pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
        example: customers
    action_name:
      in: path
      name: action
      required: true
      schema:
        description: The name of an action.
        type: string
        maxLength: 450
        pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
        example: send_email
    type_name:
      in: path
      name: type
      required: true
      schema:
        description: The name of a data type.
        type: string
        maxLength: 450
        pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
        example: STRING
    page_size:
      description: The maximum number of items to return in this request. If not
        specified, the default value is used. The default value is specified in
        the [`PVAULT_SERVICE_DEFAULT_PAGE_SIZE` environment
        variable](/guides/configure/environment-variables#service-and-features).
        Must not exceed the value specified in the
        [`PVAULT_SERVICE_MAX_PAGE_SIZE` environment
        variable](/guides/configure/environment-variables#service-and-features).
      in: query
      name: page_size
      schema:
        type: integer
        minimum: 0
        exclusiveMinimum: true
    cursor:
      description: "The cursor represents the state of consecutive queries for the
        same request parameters. In the first call, the cursor may be omitted or
        specified as an empty string. In consecutive calls, it should be set to
        the value of the cursor field of the objectFieldsPage returned by the
        previous call. Note: when the `id` is specified, paging is not
        supported. In this case, if the number of `id` values specified exceeds
        the maximum page size, the method returns 400 (BAD REQUEST)."
      in: query
      name: cursor
      allowEmptyValue: true
      schema:
        type: string
    adhoc_reason:
      name: adhoc_reason
      description: An ad-hoc reason for accessing the Vault data. Required when
        `reason` is set to `Other`.
      in: query
      schema:
        type: string
    reason:
      name: reason
      description: Details of the reason for requesting the property. The default is
        set when no access reason is provided and
        PVAULT_SERVICE_FORCE_ACCESS_REASON is false.
      in: query
      required: false
      schema:
        enum:
          - AppFunctionality
          - Analytics
          - Notifications
          - Marketing
          - ThirdPartyMarketing
          - FraudPreventionSecurityAndCompliance
          - AccountManagement
          - Maintenance
          - DataSubjectRequest
          - Other
        type: string
      example: Maintenance
    custom_audit:
      name: custom_audit
      description: Custom audit information to be included in the audit log.
      in: query
      schema:
        type: string
    reload_cache:
      name: reload_cache
      description: Reloads the cache before the action.
      in: query
      schema:
        type: boolean
    trans_param:
      name: X-Trans-Param
      description: Extra parameter to pass on to the transformers.
      in: header
      schema:
        type: string
    tenant_id:
      name: X-Tenant-Id
      description: List of tenant IDs to enforce on the request.
      in: header
      schema:
        type: array
        items:
          type: string
    transaction_id:
      name: transaction_id
      description: The transaction ID to attach to the token.
      in: query
      schema:
        type: string
    export:
      name: export
      description: Whether to encrypt the property values for export.
      in: query
      schema:
        type: boolean
    import:
      name: import
      description: Whether to write built-in property values.
      in: query
      schema:
        type: boolean
        default: false
    export_key:
      name: export_key
      description: The encrypted copy of the key used to encrypt exported data. The
        key is encrypted using the export KMS key defined by the
        [`PVAULT_KMS_EXPORT_URI` or `PVAULT_KMS_EXPORT_SEED` environment
        variables](/guides/configure/environment-variables#key-management-service).
        When importing data, the key is decrypted by the KMS, then used to
        decrypt the data. This parameter is not intended to be used manually,
        but through the CLI command `pvault import`.
      in: query
      schema:
        type: string
    props:
      description: The list of property names and transformations. To include multiple
        names and transformations, provide a comma-separated list. For example,
        `props=first_name,last_name,email.mask`.
      in: query
      name: props
      schema:
        type: array
        items:
          description: The name of a property or a transformation in the format
            `<property-name>.<transformer-name>`.
          type: string
          example: ssn.mask
  responses:
    "400":
      description: The request is invalid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/rest.HTTPError"
          example:
            error_code: PV1001
            message: The access reason is missing.
            context:
              ? reason
    "401":
      description: Authentication credentials are incorrect or missing.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/rest.HTTPError"
          example:
            error_code: PV1005
            message: The request is unauthorized.
            context: {}
    "403":
      description: The caller doesn't have the required access rights.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/rest.HTTPError"
          example:
            error_code: PV1007
            message: The operation is forbidden due to missing capabilities.
            context:
              username: WebServer
    "404":
      description: The requested resource is not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/rest.HTTPError"
          example:
            error_code: PV1004
            message: The collection is not found.
            context: {}
    "405":
      description: The operation is not allowed.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/rest.HTTPError"
          example:
            error_code: PV1026
            message: The operation is not allowed in in-memory mode.
            context: {}
    "409":
      description: A conflict occurs.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/rest.HTTPError"
          example:
            error_code: PV3218
            message: Concurrent conflicting updates to the same object.
            context: {}
    "410":
      description: Access to a resource that is no longer available occurs.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/rest.HTTPError"
          example:
            error_code: PV1033
            message: The resource is gone.
            context: {}
    "500":
      description: An error occurs on the server.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/rest.HTTPError"
          example:
            error_code: PV1000
            message: Something went wrong
            context: {}
    "503":
      description: The service is unavailable.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/rest.HTTPError"
          example:
            error_code: PV1009
            message: The operation timed out on the server.
            context: {}
    Bulk200Response:
      description: >
        The bulk operation is successful.

        This status doesn't indicate that the operation is successful for all objects.

        Check the response body for details of the status of each object.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BulkObjectResponse"
  schemas:
    ObjectID:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
      required:
        - id
    UserName:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
      required:
        - name
    AdminAPIKey:
      type: object
      additionalProperties: false
      properties:
        key:
          description: The new API key for the Admin user.
          type: string
      required:
        - key
    UserNameExpiry:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: The name of the user.
        expiration_secs:
          type: integer
          format: int64
          description: The number of seconds from now until the user's token expires.
      required:
        - name
        - expiration_secs
    IAMConfig:
      type: object
      additionalProperties: false
      properties:
        policies:
          type: object
          default: {}
          additionalProperties:
            $ref: "#/components/schemas/Policy"
        roles:
          type: object
          default: {}
          additionalProperties:
            $ref: "#/components/schemas/Role"
        users:
          type: object
          default: {}
          additionalProperties:
            $ref: "#/components/schemas/User"
        idps:
          type: object
          default: {}
          additionalProperties:
            $ref: "#/components/schemas/Idp"
    Policy:
      type: object
      additionalProperties: false
      properties:
        operations:
          type: array
          default: []
          items:
            type: string
        policy_type:
          type: string
        reasons:
          type: array
          default: []
          items:
            type: string
        resources:
          type: array
          default: []
          items:
            type: string
      required:
        - policy_type
    Role:
      type: object
      additionalProperties: false
      properties:
        capabilities:
          type: array
          default: []
          items:
            type: string
        policies:
          type: array
          default: []
          items:
            type: string
        trusted_roles:
          type: array
          items:
            type: string
    User:
      type: object
      additionalProperties: false
      properties:
        disabled:
          type: boolean
          default: false
        role:
          type: string
      required:
        - role
    Idp:
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
        disabled:
          type: boolean
        allowed_roles:
          type: array
          items:
            type: string
        roles_map:
          type: object
          additionalProperties:
            type: string
        conf:
          type: object
          additionalProperties: true
      required:
        - type
        - conf
    Config:
      type: object
      additionalProperties: false
      properties:
        db:
          $ref: "#/components/schemas/DBConfig"
        devmode:
          type: boolean
        backing_store:
          type: string
        generate_secrets:
          type: boolean
        features:
          $ref: "#/components/schemas/FeaturesConfig"
        kms:
          $ref: "#/components/schemas/KMSConfig"
        log:
          $ref: "#/components/schemas/LogConfig"
        sentry:
          $ref: "#/components/schemas/SentryConfig"
        service:
          $ref: "#/components/schemas/ServiceConfig"
        tls:
          $ref: "#/components/schemas/TLSConfig"
        expiration:
          $ref: "#/components/schemas/ExpirationConfig"
      required:
        - db
        - devmode
        - features
        - kms
        - log
        - sentry
        - service
        - tls
        - expiration
    DBConfig:
      type: object
      additionalProperties: false
      properties:
        conn_max_lifetime_minutes:
          type: integer
        gc:
          $ref: "#/components/schemas/PrunerConfig"
        hostname:
          type: string
        mask_config:
          type: boolean
        max_idle_conns:
          type: integer
        max_open_conns:
          type: integer
        max_string_length:
          type: integer
        max_blob_length:
          type: integer
        max_token_tags:
          type: integer
          maximum: 200
          minimum: 1
        migration:
          $ref: "#/components/schemas/MigrationConfig"
        name:
          type: string
        password:
          type: string
        port:
          type: integer
        require_tls:
          type: boolean
        trace_sql:
          type: boolean
        user:
          type: string
      required:
        - conn_max_lifetime_minutes
        - gc
        - hostname
        - max_idle_conns
        - max_open_conns
        - migration
        - name
        - password
        - port
        - require_tls
        - trace_sql
        - user
    FeaturesConfig:
      type: object
      additionalProperties: false
      properties:
        encryption:
          type: boolean
        mask_license:
          type: boolean
        disable_docs:
          type: boolean
        disable_javascript:
          type: boolean
        disable_idp_jwks:
          type: boolean
        disable_cc_luhn_validation:
          type: boolean
        anti_tampering:
          type: string
          enum:
            - off
            - log
            - enforce
      required:
        - encryption
        - mask_license
        - disable_javascript
    PrunerConfig:
      type: object
      additionalProperties: false
      properties:
        batch_size:
          type: integer
        retention_period:
          type: integer
      required:
        - batch_size
        - retention_period
    KMSConfig:
      type: object
      additionalProperties: false
      properties:
        seed:
          type: string
        uri:
          type: string
        export_seed:
          type: string
        export_uri:
          type: string
        allow_local:
          type: boolean
      required:
        - seed
        - uri
        - export_seed
        - export_uri
        - allow_local
    LogConfig:
      type: object
      additionalProperties: false
      properties:
        customer_env:
          type: string
        customer_identifier:
          type: string
        customer_region:
          type: string
        datadog_enable:
          type: string
        level:
          type: string
        audit_enable:
          type: boolean
        audit_remote_addr_xff:
          type: boolean
        audit_remote_addr_enable:
          type: boolean
        audit_disable_delete_tokens:
          type: boolean
        destination:
          type: string
          enum:
            - stdout
            - stderr
      required:
        - customer_env
        - customer_identifier
        - customer_region
        - datadog_enable
        - level
        - audit_enable
    MigrationConfig:
      type: object
      additionalProperties: false
      properties:
        auto_run:
          type: boolean
        enable_clean_database_validation:
          type: boolean
      required:
        - auto_run
        - enable_clean_database_validation
    SentryConfig:
      type: object
      additionalProperties: false
      properties:
        enable:
          type: boolean
      required:
        - enable
    ServiceConfig:
      type: object
      additionalProperties: false
      properties:
        admin_api_key:
          type: string
        override_admin_api_key_on_restart:
          type: boolean
        allow_origins:
          type: string
        admin_may_read_data:
          type: boolean
        components:
          type: string
        worker_priority:
          type: number
        pci_restrictions:
          type: boolean
        default_page_size:
          type: integer
        set_iam_on_start_only:
          type: boolean
        update_schema_on_start:
          type: boolean
        force_access_reason:
          type: boolean
        listen_addr:
          type: string
        max_page_size:
          type: integer
        max_pagination_remaining_count:
          type: integer
        timeout_seconds:
          type: number
        cache_refresh_interval:
          type: integer
        cache_refresh_timeout:
          type: integer
        archive_prune_interval:
          type: integer
        archive_prune_timeout:
          type: integer
        substring_index_refresh_interval:
          type: integer
        license:
          type: string
        allowed_http_destinations:
          type: string
        allowed_pci_http_destinations:
          type: string
        actions_http_call_role:
          type: string
      required:
        - admin_api_key
        - admin_may_read_data
        - default_page_size
        - force_access_reason
        - listen_addr
        - max_page_size
        - timeout_seconds
        - cache_refresh_interval
        - archive_prune_interval
        - license
    TLSConfig:
      type: object
      additionalProperties: false
      properties:
        cert_file:
          type: string
        enable:
          type: boolean
        key_file:
          type: string
        selfsigned:
          type: boolean
      required:
        - cert_file
        - enable
        - key_file
        - selfsigned
    ExpirationConfig:
      type: object
      additionalProperties: false
      properties:
        associated_objects:
          type: integer
        tokens:
          type: integer
        unassociated_objects:
          type: integer
      required:
        - associated_objects
        - tokens
        - unassociated_objects
    DeletionCount:
      type: object
      additionalProperties: false
      properties:
        collection_name:
          type: string
          description: The name of the collection containing the objects or tokens to
            delete.
          example: Tokens
        collection_type:
          type: string
          description: The type of the collection.
          example: TOKENS
          enum:
            - DATA
            - PERSONS
            - TOKENS
            - TRANSACTION_IDS
        count:
          type: integer
          description: The number of items deleted.
          example: 634
      required:
        - collection_name
        - collection_type
        - count
    Collection:
      type: object
      additionalProperties: false
      properties:
        creation_time:
          type: string
          format: date-time
          description: |
            The time when the collection was created, in RFC3339Nano format.
            Vault sets this value automatically.
            Sending a value for this field is ignored.
          example: 2022-07-05T08:47:12.041234Z
        modification_time:
          type: string
          format: date-time
          description: >
            The time when the collection was last modified, in RFC3339Nano
            format.

            Vault sets this value automatically.

            Sending a value for this field is ignored.
          example: 2022-07-05T08:47:12.041234Z
        name:
          $ref: "#/components/schemas/CollectionName"
        properties:
          type: array
          items:
            $ref: "#/components/schemas/Property"
        type:
          type: string
          description: The schema prototype the collection is based on.
          enum:
            - PERSONS
            - DATA
      example:
        type: PERSONS
        name: customers
        properties:
          - description: Date of birth
            name: date_of_birth
            data_type_name: DATE_OF_BIRTH
            is_nullable: true
          - description: Email
            name: email
            data_type_name: EMAIL
            is_unique: true
            is_index: true
            is_substring_index: false
            is_nullable: true
          - description: First name
            name: first_name
            data_type_name: NAME
          - description: Last name
            name: last_name
            data_type_name: NAME
          - description: Phone number
            name: phone_number
            data_type_name: PHONE_NUMBER
            is_unique: true
            is_index: true
            is_substring_index: false
            is_nullable: true
      required:
        - name
        - properties
        - type
    Collection.pvschema:
      type: string
      example: |-
        customers PERSONS (
        date_of_birth DATE_OF_BIRTH NULL COMMENT 'Date of birth',
        email EMAIL NULL UNIQUE INDEX COMMENT 'Email',
        first_name NAME COMMENT 'First name',
        last_name NAME COMMENT 'Last name',
        phone_number PHONE_NUMBER NULL UNIQUE INDEX COMMENT 'Phone number',
        );
    ConfVar:
      type: object
      additionalProperties: false
      properties:
        name:
          description: The name of the configuration variable.
          example: log_level
          type: string
        value:
          description: The value of the configuration variable.
        default_value:
          description: The default value of the configuration variable.
      required:
        - name
        - value
        - default_value
    License:
      type: object
      additionalProperties: false
      properties:
        key:
          description: The full license activation key.
          type: string
        expiration:
          description: The expiration date of the token in an RFC3339Nano format.
          example: 2022-07-05T08:47:12.041234Z
          type: string
          format: date-time
      required:
        - key
        - expiration
    ConfVarValue:
      type: object
      additionalProperties: false
      properties:
        value:
          type: string
          description: The value of the configuration variable.
      required:
        - value
    LicenseKey:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
          description: The license key.
      required:
        - key
    DetokenizedToken:
      type: object
      additionalProperties: false
      properties:
        fields:
          $ref: "#/components/schemas/ObjectFields"
        token_id:
          description: The token ID.
          type: string
          example: 49303e72-35e3-11ed-a261-0242ac120002
        metadata:
          $ref: "#/components/schemas/TokenMetadata"
      required:
        - fields
        - token_id
    Health:
      type: object
      additionalProperties: false
      properties:
        status:
          description: The status of the service.
          example: pass
          type: string
      required:
        - status
    KMSStatusResponse:
      description: The status and type of the default KMS and the KMS for export.
      type: object
      additionalProperties: false
      properties:
        kms:
          $ref: "#/components/schemas/KMSStatus"
        kms_export:
          $ref: "#/components/schemas/KMSStatus"
      required:
        - kms
    KMSStatus:
      type: object
      additionalProperties: false
      properties:
        status:
          description: The status of the KMS.
          type: string
          enum:
            - pass
            - fail
          example: pass
        type:
          description: The type of the KMS.
          type: string
          enum:
            - GCP
            - AWS
            - LOCAL
          example: AWS
      required:
        - status
        - type
    Count:
      type: object
      additionalProperties: false
      properties:
        active:
          description: Number of active items.
          example: 10
          type: integer
        archived:
          description: Number of archived items.
          example: 15
          type: integer
        total:
          description: Number of total items.
          example: 25
          type: integer
      required:
        - active
        - archived
        - total
      example:
        active: 10
        archived: 15
        total: 25
    ObjectFields:
      description: A list of maps of object properties and their values.
      type: object
      example:
        date_of_birth: 1993-02-22
        email: patfar@example.com
        first_name: Pat
        last_name: Far
        phone_number: "+11011010101"
      additionalProperties: true
    ObjectFieldsPage:
      type: object
      additionalProperties: false
      properties:
        results:
          description: A page of objects.
          type: array
          items:
            $ref: "#/components/schemas/ObjectFields"
        paging:
          $ref: "#/components/schemas/Paging"
      required:
        - results
        - paging
    Paging:
      description: Pagination information.
      type: object
      additionalProperties: false
      properties:
        size:
          type: integer
          description: Number of results in the current page.
        remaining_count:
          type: integer
          description: The remaining number of objects that can be read in ensuing calls
            to this method.
        cursor:
          type: string
          description: An opaque string you should provide to get the next page.
      required:
        - size
        - remaining_count
        - cursor
    ProductVersion:
      type: object
      additionalProperties: false
      properties:
        db_schema_version:
          type: integer
          format: int64
        vault_id:
          example: 1525298622245192000
          type: string
        vault_version:
          description: The version of a Vault specified as a string consisting of version
            number, build number, and edition.
          example: 0.9.5.1-g2be0eb7e
          type: string
      required:
        - db_schema_version
        - vault_id
        - vault_version
    Property:
      type: object
      additionalProperties: false
      properties:
        creation_time:
          description: |
            The time when the property was created, in RFC3339Nano format.
            Vault sets this value automatically.
            Sending a value for this field is ignored.
          example: 2022-07-05T08:47:12.041234Z
          type: string
          format: date-time
        modification_time:
          description: |
            The time when the property was last modified, in RFC3339 format.
            Vault sets this value automatically.
            Sending a value for this field is ignored.
          example: 2022-07-05T08:47:12.047Z
          type: string
          format: date-time
        description:
          $ref: "#/components/schemas/Description"
        is_builtin:
          default: false
          description: |
            Whether the property is created by Vault (or by the user).
            Built-in properties cannot be deleted or modified.
            Sending a value for this field is ignored.
          example: false
          type: boolean
        is_encrypted:
          default: true
          description: Whether the value is stored encrypted.
          example: true
          type: boolean
        is_index:
          default: false
          description: Whether the backend storage is optimized for searches on this
            property. Cannot be set to `true` for properties with data types
            `LONG_TEXT`, `JSON`, or `BLOB`, or custom data types based on those
            types.
          example: false
          type: boolean
        is_substring_index:
          default: false
          description: Whether the backend storage is optimized for substring searches on
            this property. See <a
            href="/guides/reference/data-types#indexing">indexing</a> in the
            data type reference for a list of supported data types.
          example: false
          type: boolean
        is_nullable:
          default: false
          description: Whether the value of the property can be removed (set to null).
          example: false
          type: boolean
        is_readonly:
          default: false
          description: |
            Whether the user can modify values of this property.
            Ignored for user define properties.
            Sending a value for this field is ignored.
          example: false
          type: boolean
        is_unique:
          default: false
          description: Whether the backend storage enforces unique values for active
            objects. Cannot be set to `true` for properties with data types
            `LONG_TEXT`, `JSON`, or `BLOB`, or custom data types based on those
            types.
          example: false
          type: boolean
        name:
          $ref: "#/components/schemas/PropertyName"
        data_type_name:
          $ref: "#/components/schemas/DataTypeName"
      required:
        - name
        - data_type_name
    UpdatePropertyRequest:
      type: object
      additionalProperties: false
      properties:
        description:
          description: The description of the property. If not provided, is set to an
            empty `string`.
          type: string
          example: The name of the customer.
        is_index:
          description: Whether the backend storage is optimized for searches on this
            property. Cannot be set to `true` for properties with data types
            `LONG_TEXT`, `JSON`, or `BLOB`, or custom data types based on those
            types.
          type: boolean
          example: false
        is_substring_index:
          description: Whether the backend storage is optimized for substring searches on
            this property. Can only be set to change the value to 'false'.
          type: boolean
          example: false
        is_nullable:
          description: Whether this property can have no value.
          type: boolean
          example: false
        is_unique:
          description: Whether the backend storage enforces unique values for active
            objects.
          type: boolean
          example: false
    Query:
      type: object
      description: >
        A query is a map of operators to match against the properties of an
        object.


        Multiple operators can be combined in a single query.
      additionalProperties: false
      properties:
        in:
          $ref: "#/components/schemas/InMap"
        match:
          $ref: "#/components/schemas/MatchMap"
        like:
          $ref: "#/components/schemas/LikeMap"
      minProperties: 1
    InMap:
      type: object
      description: >
        The `in` query operator allows you to match a property value against a
        list of values.


        Each key in the map is a property name, and the value is a list of values to match.


        The SQL equivalent of this query is:


        ```sql

        SELECT * FROM objects WHERE property1 IN (value1, value2) AND property2 IN (value1, value2);

        ```
      additionalProperties:
        type: array
        items:
          description: A value to match. Must be of the same type as the property.
          nullable: true
    MatchMap:
      type: object
      description: >
        The `match` query operator allows you to match a property value against
        a specific value.


        Each key in the map is a property name, and the value is the value to match.


        The SQL equivalent of this query is:


        ```sql

        SELECT * FROM objects WHERE property1 = value1 AND property2 = value2;

        ```
      additionalProperties:
        description: A value to match. Must be of the same type as the property.
        nullable: true
    LikeMap:
      type: object
      description: >
        The `like` query operator allows you to match a property value against a
        search pattern.


        Each key in the map is a property name, and the value is the pattern to match.


        The SQL equivalent of this query is:


        ```sql

        SELECT * FROM objects WHERE property1 LIKE pattern1 AND property2 LIKE pattern2;

        ```
      additionalProperties:
        description: A pattern to match. Must be of the same type as the property.
        nullable: true
    QueryToken:
      type: object
      additionalProperties: false
      properties:
        object_ids:
          description: Comma-separated list of object IDs.
          items:
            type: string
            format: uuid
            example: 463a83d0-a816-4902-abba-2486e0c0a0bb
          type: array
        token_ids:
          description: Comma-separated list of token IDs.
          items:
            type: string
            example: 49303e72-35e3-11ed-a261-0242ac120002
          type: array
        tags:
          description: Comma-separated list of tags.
          type: array
          items:
            $ref: "#/components/schemas/Tag"
    RotatedTokens:
      type: object
      description: Mapping between old token IDs and new token IDs.
      example:
        49303e72-35e3-11ed-a261-0242ac120002: 463a83d0-a816-4902-abba-2486e0c0a0bb
      additionalProperties:
        type: string
    TokenAggregatedMetadata:
      type: object
      additionalProperties: false
      properties:
        max_effective_expiration_time:
          description: Latest expiry of all tokens with the token ID (UTC).
          type: string
          nullable: true
          format: date-time
    TokenMetadata:
      type: object
      additionalProperties: false
      properties:
        agg:
          $ref: "#/components/schemas/TokenAggregatedMetadata"
        type:
          $ref: "#/components/schemas/TokenType"
        scope:
          description: The scope of the tokens.
          type: string
          example: default
        token_id:
          description: The shared ID of the tokens.
          type: string
          example: 49303e72-35e3-11ed-a261-0242ac120002
        tokens:
          description: The metadata for each token.
          type: array
          items:
            $ref: "#/components/schemas/TokenRefMetadata"
      required:
        - type
        - scope
        - token_id
        - tokens
    TokenRefMetadata:
      type: object
      additionalProperties: false
      properties:
        creation_time:
          description: Creation time of the token (UTC).
          type: string
          format: date-time
        effective_expiration_time:
          description: Effective expiry time of the token (UTC), being the earliest of the
            expiry time of the token or the object owning the token, if any.
          type: string
          nullable: true
          format: date-time
        expiration_time:
          description: Expiry time of the token (UTC).
          type: string
          nullable: true
          format: date-time
        object_id:
          description: The object this token is for.
          type: string
          format: uuid
        effective_tenant_id:
          description: The tenant ID of the tokens.
          type: string
        tags:
          description: >
            Tags associated with the token.

            When token ID is reused, this is all the tags from the tokens that share the ID.
          type: array
          items:
            $ref: "#/components/schemas/Tag"
      required:
        - creation_time
        - effective_expiration_time
        - expiration_time
        - tags
    TokenType:
      description: >
        The type of the token:

        - `randomized` – token that represent the property values as they were when the token was created. For non-format preserving tokens, the token ID is taken from the token_id parameter of the request (if applicable) or randomly assigned a unique ID.

        - `pointer` – token that represent the property values as they are when the request to detokenize is made. For non-format preserving tokens, the token ID is taken from the token_id parameter of the request (if applicable) or randomly assigned a unique ID.

        - `pci` – token that represent property values as they were when the token was created. The token ID reuses the ID of an existing token where both tokens are created on the same collection with the same values and scope. Otherwise, the token ID is either randomly assigned, or taken from the token_id parameter of the request (if applicable).

        - `pci_oneway` – PCI token that cannot be detokenized.

        - `deterministic` - token that is assigned a deterministic ID based on the collection, tokenized object, property values, and scope.
      type: string
      enum:
        - pci
        - pci_oneway
        - pointer
        - randomized
        - deterministic
    TokenValue:
      type: object
      additionalProperties: false
      properties:
        token_id:
          description: The ID of the token.
          type: string
          example: de15a638-354a-11ed-a261-0242ac120002
        object_id:
          description: The ID of the newly added object, applicable for tokenizing with
            store_object is true.
          type: string
          format: uuid
          example: cc9a39c5-4734-4786-b317-e16705d5128f
      required:
        - token_id
    TokenizeRequest:
      type: object
      additionalProperties: false
      properties:
        type:
          $ref: "#/components/schemas/TokenType"
        object:
          $ref: "#/components/schemas/InputObject"
        props:
          description: A list of the properties to tokenize.
          type: array
          items:
            $ref: "#/components/schemas/PropertyName"
        token_id:
          description: User provided token ID, up to 128 chars, using letters (a-z, A-Z),
            numbers (0-9), hyphens (-), and underscores (_). The user provided
            ID can not be used with 'fptemplate' and 'fpprops' parameters. For
            `randomized` and `pointer` types, it must be unique. For `pci` and
            `pci_oneway` types, it must reuse the ID of any existing token which
            was created on the same collection with the same values and scope.
            Otherwise, it should be unique. For `deterministic` type, it must
            align exactly with the deterministic ID based on the collection,
            tokenized object, property values, and scope.
          type: string
        scope:
          default: default
          description: >
            A classification for the token.

            By default for these token types: `deterministic`, `pci` and `pci_oneway`, the scope is bound per collection. This implies that two identical tokens with the same scope on different collection will result with different token_ids. You can force the scope to apply globally by setting the suffix of the scope value to start with `global:`.
          type: string
        tags:
          description: |
            Tags to attach to the token. Maximum 10.
          type: array
          items:
            $ref: "#/components/schemas/Tag"
          maximum: 10
        ensure_unique_tenant_tags:
          description: >
            Tags to validate as unique in tenant scope. Must be subset of
            'tags'. Note: this operation has a performance impact to be able to
            ensure the uniqueness of the tags prior to the insertion operation.
          type: array
          items:
            $ref: "#/components/schemas/Tag"
          maximum: 10
        store_object:
          description: >
            When `fields` is included in the request body, whether to store the
            property values as an object in the collection. The token is owned
            by the new object. Default is false.
          type: boolean
        fpprops:
          description: >
            Properties used by the format preserving template for the ID
            generation. The templates require these properties:

            - the `primary_account_number` template requires a property of type `CC_NUMBER`. The token ID is generated from this property by retaining the first six and last four digits and randomizing the remaining digits.

            - [custom format-preserving templates](/guides/tokenize-personal-data/custom-js-format-preserving-template) do not require any properties.
          type: array
          items:
            type: string
            example: credit_card_no
        fptemplate:
          description: >
            The template used to format the generated ID. Supports: 

            - `primary_account_number` that generates an ID that is a valid 16-digit PAN (credit card number).

            - function name formatted as `<bundle-name>.<function-name>` for [custom format-preserving templates](/guides/tokenize-personal-data/custom-js-format-preserving-template).

            If empty, the format of the ID is a UUID.
          type: string
      required:
        - type
        - object
    EncryptionRequest:
      type: object
      additionalProperties: false
      properties:
        type:
          $ref: "#/components/schemas/EncryptionType"
        object:
          $ref: "#/components/schemas/InputObject"
        props:
          description: >
            A list of the properties to include in the encrypted object.

            If not provided, all properties are included, including the built-in properties, but omitting the object ID.
          type: array
          items:
            $ref: "#/components/schemas/PropertyName"
        scope:
          default: default
          description: >
            A classification for the encrypted object that is added to the
            ciphertext as associated data (AAD).

            An object encrypted with a scope can be decrypted only with the same scope.
          type: string
        tags:
          description: >
            Tags to attach to the metadata of the encrypted object.

            The maximum number of allowed tags is defined by the [`PVAULT_DB_MAX_TOKEN_TAGS` environment variable](/guides/configure/environment-variables#database) (default 10).

            Tags are not supported for the `deterministic` encryption type.
          type: array
          items:
            $ref: "#/components/schemas/Tag"
          maximum: 10
      required:
        - object
    UpdateEncryptionRequest:
      type: object
      additionalProperties: false
      properties:
        type:
          $ref: "#/components/schemas/EncryptionType"
        encrypted_object:
          $ref: "#/components/schemas/EncryptedObjectInput"
        fields:
          $ref: "#/components/schemas/ObjectFields"
        props:
          type: array
          items:
            $ref: "#/components/schemas/PropertyName"
          description: The properties to include in the updated encrypted object.
        scope:
          default: default
          description: >
            A classification for the updated encrypted object that is added to
            the ciphertext as associated data (AAD).

            An object encrypted with a scope can be decrypted only with the same scope.
          type: string
      required:
        - encrypted_object
        - fields
    EncryptionType:
      type: string
      description: >
        The type of the encryption:

        - `randomized` - generates a different randomized unpredictable, non-repeating ciphertext each time.

        - `deterministic` - generates the ciphertext deterministically based on the collection name, input object, and scope.

        Defaults to `randomized` if not set.
      default: randomized
      enum:
        - randomized
        - deterministic
    EncryptedValue:
      type: object
      properties:
        ciphertext:
          description: >
            The encrypted object is a base64 ciphertext of the request fields
            and built-in fields such as timestamps and expiration time.

            It does not include the ID field.
          type: string
      required:
        - ciphertext
    DecryptionRequest:
      type: object
      additionalProperties: false
      properties:
        encrypted_object:
          $ref: "#/components/schemas/EncryptedObjectInput"
        props:
          description: >
            The list of property names and transformers to include in the
            decrypted object. If not set, return all encrypted property values.
          type: array
          items:
            type: string
            example: credit_card_no
      required:
        - encrypted_object
    DecryptedObject:
      type: object
      additionalProperties: false
      properties:
        fields:
          $ref: "#/components/schemas/ObjectFields"
        metadata:
          $ref: "#/components/schemas/EncryptedObjectMetadata"
      required:
        - fields
    EncryptedObjectMetadata:
      type: object
      additionalProperties: false
      properties:
        type:
          $ref: "#/components/schemas/EncryptionType"
        scope:
          description: The scope of the tokens.
          type: string
          example: default
        expiration:
          description: Effective expiry time of the encrypted object (UTC).
          type: string
          nullable: true
          format: date-time
        tags:
          description: |
            Tags associated with the encrypted object.
          type: array
          items:
            $ref: "#/components/schemas/Tag"
      required:
        - type
        - scope
        - tags
    HashObjectRequest:
      type: object
      additionalProperties: false
      properties:
        object:
          $ref: "#/components/schemas/InputObject"
        props:
          description: A list of the properties to tokenize.
          type: array
          items:
            type: string
            example: credit_card_no
        scope:
          default: default
          description: A classification for the hash.
          type: string
        fpprops:
          description: >
            Properties used by the format preserving template for the ID
            generation. The templates require these properties:

            - the `primary_account_number` template requires a property of type `CC_NUMBER`. The token ID is generated from this property by retaining the first six and last four digits and randomizing the remaining digits.

            - [custom format-preserving templates](/guides/tokenize-personal-data/custom-js-format-preserving-template) do not require any properties.
          type: array
          items:
            type: string
            example: credit_card_no
        fptemplate:
          description: >
            The template used to format the generated ID. Supports: 

            - `primary_account_number` that generates an ID that is a valid 16-digit PAN (credit card number).

            - function name formatted as `<bundle-name>.<function-name>` for [custom format-preserving templates](/guides/tokenize-personal-data/custom-js-format-preserving-template).

            If empty, the format of the ID is a UUID.
          type: string
      required:
        - object
      example:
        object:
          id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
        props:
          - phone_number
        scope: default
    InputObject:
      description: >
        The input object, defined as one and only one of the following
        properties.

        - `id`: the ID of an object.

        - `fields`: property values of an object.

        - `encrypted`: an encrypted object.

        - `request_index`: the index of the object in the request array.


        In stateless mode, `id` is not supported and either `fields` or `encrypted` must be supplied.
      type: object
      minProperties: 1
      maxProperties: 1
      additionalProperties: false
      properties:
        id:
          description: The ID of an object.
          type: string
          format: uuid
        fields:
          $ref: "#/components/schemas/ObjectFields"
        encrypted:
          $ref: "#/components/schemas/EncryptedObjectInput"
        request_index:
          description: The index of the object in the request array.
          type: integer
          minimum: 0
      example:
        fields:
          first_name: John
          email: patfar@example.com
    EncryptedObjectInput:
      description: An encrypted object.
      additionalProperties: false
      type: object
      properties:
        ciphertext:
          description: The encrypted object base64 cipher text.
          type: string
        scope:
          description: The scope used to encrypt the object. By default, it uses the scope
            of the encrypted object.
          type: string
      required:
        - ciphertext
    UpdateTokenRequest:
      type: object
      additionalProperties: false
      properties:
        tags:
          description: Replacement tags for the tokens.
          type: array
          items:
            $ref: "#/components/schemas/Tag"
          maximum: 10
        ensure_unique_tenant_tags:
          description: >
            Tags to validate as unique in tenant scope. Must be a subset of
            'tags'. Note: The need to ensure the uniqueness of the tags prior to
            insertion means this feature impacts the operation's performance.
          type: array
          items:
            $ref: "#/components/schemas/Tag"
          maximum: 10
        object:
          $ref: "#/components/schemas/InputObject"
        props:
          description: A list of the properties to update.
          type: array
          items:
            $ref: "#/components/schemas/PropertyName"
    TokenDataPage:
      type: object
      additionalProperties: false
      properties:
        results:
          description: A page of tokens.
          type: array
          items:
            $ref: "#/components/schemas/TokenData"
        paging:
          $ref: "#/components/schemas/Paging"
      required:
        - results
        - paging
    TokenData:
      type: object
      properties:
        token_id:
          description: The token ID.
          type: string
        token_type:
          $ref: "#/components/schemas/TokenType"
        props:
          type: array
          items:
            $ref: "#/components/schemas/PropertyName"
        fields:
          $ref: "#/components/schemas/ObjectFields"
        object_id:
          type: string
          format: uuid
        scope:
          type: string
        tags:
          type: array
          items:
            type: string
        expiration:
          $ref: "#/components/schemas/TokenExpiration"
        created_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
        fptemplate:
          type: string
      required:
        - token_id
        - token_type
        - props
        - scope
        - created_at
        - modified_at
    TokenExpiration:
      type: object
      properties:
        expiration_time:
          type: string
          format: date-time
    ImportTokensBulkResponse:
      type: object
      additionalProperties: false
      properties:
        ok:
          description: >
            Indicates whether all the tokens are imported.

            If the import fails for one or more of the tokens, this property is set to `false`.
          type: boolean
          example: false
        results:
          description: >
            An array of objects representing the result of importing each item.

            The order of the objects in the array matches the order of the objects in the request.
          type: array
          items:
            $ref: "#/components/schemas/ImportTokenResult"
      required:
        - ok
        - results
    ImportTokenResult:
      description: The result of importing a token.
      type: object
      additionalProperties: false
      properties:
        token_id:
          description: The token ID.
          type: string
        ok:
          description: >
            Indicates whether the token is imported.

            If `true`, the token is imported.

            If `false`, the import fails, and the `error` field contains more information.
          type: boolean
          example: false
        error:
          $ref: "#/components/schemas/rest.HTTPError"
      required:
        - token_id
        - ok
    Tag:
      type: string
      example: credit_cards
      maxLength: 256
    TransactionID:
      type: object
      description: The list of referenced token IDs.
      additionalProperties: false
      properties:
        ref_ids:
          type: array
          items:
            type: string
            description: The ID of a referenced token.
            example: de15a638-354a-11ed-a261-0242ac120002
      required:
        - token_id
    Bundle:
      allOf:
        - $ref: "#/components/schemas/PartialBundle"
        - type: object
          properties:
            name:
              $ref: "#/components/schemas/BundleName"
            exports:
              $ref: "#/components/schemas/BundleExports"
            creation_time:
              description: The time when the bundle was created.
              type: string
              format: date-time
              example: 2022-07-05T08:47:12.047Z
              readOnly: true
          required:
            - name
            - code
    PartialBundle:
      type: object
      properties:
        description:
          $ref: "#/components/schemas/Description"
        code:
          type: string
          format: byte
          description: A base64 encoded self-contained JavaScript code snippet.
      minProperties: 1
    BundleExports:
      description: the functions exported by the bundle.
      type: object
      readOnly: true
      properties:
        validators:
          type: array
          items:
            $ref: "#/components/schemas/FunctionPrototype"
          description: The list of validators.
        normalizers:
          type: array
          items:
            $ref: "#/components/schemas/FunctionPrototype"
          description: The list of normalizers.
        transformers:
          type: array
          items:
            $ref: "#/components/schemas/FunctionPrototype"
          description: The list of transformers.
        actions:
          type: array
          items:
            $ref: "#/components/schemas/FunctionPrototype"
          description: The list of actions.
        format_preserving_templates:
          type: array
          items:
            $ref: "#/components/schemas/FunctionPrototype"
          description: The list of format-preserving templates.
    FunctionPrototype:
      type: object
      properties:
        name:
          $ref: "#/components/schemas/JavaScriptFunctionName"
        type:
          $ref: "#/components/schemas/FunctionType"
        description:
          type: string
          description: An optional description of the function
        dependencies:
          $ref: "#/components/schemas/Dependencies"
      required:
        - name
        - type
    Dependencies:
      description: The list of dependencies of the function on the invocation context.
      type: object
      properties:
        properties:
          type: array
          items:
            type: string
          description: The list of glob strings indicating which property values of the
            object should be provided in the "object" argument.
    FunctionType:
      type: string
      enum:
        - transformer
        - validator
        - normalizer
        - action
    DataType:
      description: The data type and its function. default_transformer is the default
        transformer for the data type and should be taken from the transformers
        list.
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: "#/components/schemas/DataTypeName"
        is_builtin:
          type: boolean
          description: Whether this data type is built-in or user defined.
          readOnly: true
        base_type_name:
          $ref: "#/components/schemas/BaseDataTypeName"
        description:
          $ref: "#/components/schemas/Description"
        validator:
          $ref: "#/components/schemas/FunctionName"
        normalizer:
          $ref: "#/components/schemas/FunctionName"
        transformers:
          type: array
          items:
            $ref: "#/components/schemas/FunctionName"
          description: The names of transformers that are supported for the data type.
        default_transformer:
          $ref: "#/components/schemas/FunctionName"
        creation_time:
          description: The time when the data type was created.
          type: string
          format: date-time
          example: 2022-07-05T08:47:12.047Z
          readOnly: true
      required:
        - name
        - base_type_name
    FunctionName:
      description: The bundle and function name formatted as
        `<bundle-name>.<function-name>`.
      type: string
      example: bundle1.function1
    AllGenerations:
      type: object
      additionalProperties: false
      properties:
        vault:
          $ref: "#/components/schemas/VaultGeneration"
        workers:
          description: Workers generations.
          type: array
          items:
            $ref: "#/components/schemas/Worker"
      required:
        - vault
        - workers
    VaultGeneration:
      description: Vault Generation.
      type: object
      additionalProperties: false
      properties:
        generation_number:
          description: Generation number.
          type: integer
        modified_at:
          description: Modified at.
          type: string
          format: date-time
      required:
        - generation_number
        - modified_at
    Worker:
      description: Worker.
      type: object
      additionalProperties: false
      properties:
        worker_id:
          description: Worker id.
          type: integer
          format: int64
        generation_number:
          description: Generation number.
          type: integer
        generation_checked_at:
          description: Modified at.
          type: string
          format: date-time
        refresh_interval_seconds:
          description: Refresh interval in seconds.
          type: integer
        priority:
          description: Priority in aquiring the responsibility of the worker to run the
            cluster level jobs.
          type: integer
        component:
          description: Components of the worker (e.g. "data", "control").
          type: string
      required:
        - worker_id
        - generation_number
        - generation_checked_at
        - refresh_interval_seconds
        - component
        - priority
    APIKey:
      type: object
      additionalProperties: false
      properties:
        api_key:
          description: The new API key generated for the user.
          example: some_user
          type: string
        api_key_expiry:
          description: The expiry time of the API key.
          example: 2022-07-05T08:47:12.047Z
          type: string
          format: date-time
      required:
        - api_key
        - api_key_expiry
    APIKeyExpiry:
      type: object
      additionalProperties: false
      properties:
        name:
          description: The user name.
          example: some_user
          type: string
        api_key_expiry:
          description: The expiry time of the API key.
          example: 2022-07-05T08:47:12.047Z
          type: string
          format: date-time
      required:
        - name
        - api_key_expiry
    UserDetails:
      type: object
      additionalProperties: false
      properties:
        name:
          description: The user name.
          example: some_user
          type: string
        api_key:
          description: The metadata associated with the API key of the caller.
          type: object
          properties:
            expiry:
              description: The expiry time of the API key.
              example: 2022-07-05T08:47:12.047Z
              type: string
              format: date-time
          required:
            - expiry
      required:
        - name
        - api_key
    ExportKeyResponse:
      type: object
      additionalProperties: false
      properties:
        export_key:
          description: The key used to encrypt and decrypt exported data.
          type: string
      required:
        - export_key
    rest.HTTPError:
      type: object
      additionalProperties: false
      properties:
        context:
          description: The error context.
          example:
            objectid: b56dd6aa-35f0-11ed-a261-0242ac120002
          type: object
          additionalProperties:
            type: string
        error_code:
          description: The error code.
          example: PVxxxx
          type: string
        message:
          description: The error message.
          example: The object is not found.
          type: string
        error_url:
          description: The URL to the error documentation.
          example: https://docs.piiano.com/api/error-codes#PV1005
          type: string
      required:
        - context
        - error_code
        - message
    BulkObjectResponse:
      type: object
      additionalProperties: false
      properties:
        ok:
          description: >
            Indicates whether the operation was completed successfully for all
            objects in the bulk operation.

            If the operation failed for one or more of the provided objects, this property will be set to `false`.
          type: boolean
          example: false
        results:
          description: >
            An array of objects representing the processing result of each item
            in the bulk operation.

            The order of the objects in the array will match the order of the objects in the request.
          type: array
          items:
            $ref: "#/components/schemas/BulkObjectResult"
      required:
        - ok
        - results
    BulkObjectResult:
      description: >
        A result object representing the processing of an object in the bulk
        operation.

        Each result object includes there fields:

        - `ok` a boolean that indicates whether the operation completed successfully for the object.

        - `id` the unique identifier for the processed object.
           This field might be omitted if the operation failed before an `id` was assigned to the object. 
        - `error` is present when `ok` is `false` and provides more information about any error.
           The `error` field follows the same structure as the [error objects](/api/status-codes#error-response-schema) returned in single object operations.
      type: object
      additionalProperties: false
      properties:
        id:
          description: The unique identifier for the object.
          type: string
          format: uuid
        ok:
          description: >
            Indicates whether the operation was completed successfully for this
            object.

            If `true`, the operation completed successfully.

            If `false`, the operation failed and the `error` field will contain more information.
          type: boolean
          example: false
        error:
          $ref: "#/components/schemas/rest.HTTPError"
      required:
        - ok
    CollectionName:
      description: The name of a collection.
      type: string
      maxLength: 40
      pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
      example: customers
    PropertyName:
      description: The name of a property.
      type: string
      maxLength: 40
      pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
      example: first_name
    DataTypeName:
      description: The name of a data type.
      type: string
      maxLength: 450
      pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
      example: STRING
    BaseDataTypeName:
      description: The name of the base data type.
      type: string
      maxLength: 450
      pattern: ^[a-zA-Z][a-zA-Z0-9_]*|$
      example: STRING
    BundleName:
      description: The name of a bundle.
      type: string
      maxLength: 450
      pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
      example: bundle
    JavaScriptFunctionName:
      description: The name of a JavaScript function in a bundle.
      type: string
      pattern: ^[a-zA-Z_$][a-zA-Z0-9_$]*$
      example: to_upper
    Description:
      description: The description of a model.
      type: string
      maxLength: 450
    Action:
      description: An action definition.
      type: object
      properties:
        name:
          type: string
          description: |
            The name of the action.
          maxLength: 450
          pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
        description:
          type: string
          description: A description of the action.
          maxLength: 450
        function:
          $ref: "#/components/schemas/FunctionName"
        role:
          description: >
            The IAM role for the action. 

            The role determine the operations or data available to the action.

            For example, a role can allow an action to read the email address from any object but deny it from reading credit card numbers.
          type: string
          maxLength: 450
          pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
        is_builtin:
          description: |
            Whether this action is built-in or user-defined.
            Sending a value for this field is ignored.
          type: boolean
          example: true
          readOnly: true
        creation_time:
          description: The time when the action was created.
          type: string
          format: date-time
          example: 2022-07-05T08:47:12.047Z
          readOnly: true
        modification_time:
          description: The time when the action was last modified.
          type: string
          format: date-time
          example: 2022-07-05T08:47:12.047Z
          readOnly: true
      required:
        - name
        - function
        - role
    ActionInput:
      description: Any valid JSON value to be used as an input to the action function.
    ActionResult:
      description: The result of an action invocation serialized as a JSON value.
    HTTPCallActionInput:
      additionalProperties: false
      type: object
      properties:
        template_variables:
          description: >
            A key-value map of template variable names to Vault global
            identifiers.
          type: object
          additionalProperties:
            type: string
          example:
            to_email: "pvlt:detokenize:customers:email:463a83d0-a816-4902-abba-2486e0c0a0bb\
              :"
            first_name: "pvlt:read_object:customers:first_name:463a83d0-a816-4902-abba-2486\
              e0c0a0bb:"
        request:
          $ref: "#/components/schemas/HTTPCallRequest"
        include_response_body:
          description: >
            Whether to include the response body in the action result.

            Set as `false`, or use the default, to ensure any sensitive data in the response body isn't returned in the action result.
          type: boolean
          default: false
      required:
        - template_variables
        - request
    HTTPCallRequest:
      description: |
        The HTTP request template.
      additionalProperties: false
      type: object
      properties:
        url:
          description: The URL to call.
          type: string
          example: https://example-email-server.com/send-email
        method:
          description: The HTTP method to use.
          type: string
          enum:
            - GET
            - HEAD
            - POST
            - PUT
            - PATCH
            - DELETE
            - CONNECT
            - OPTIONS
            - TRACE
          default: GET
          example: POST
        headers:
          description: The HTTP headers to send.
          type: object
          additionalProperties:
            type: string
          example:
            Content-Type: application/json
        body:
          description: The HTTP body to send.
          type: string
          example: '{"to": "{{ .to_email }}", "message": "Hello {{ .first_name }}!" }'
      required:
        - url
    HTTPCallActionResult:
      additionalProperties: false
      type: object
      properties:
        status_code:
          description: The HTTP status code of the response.
          type: integer
          example: 200
        headers:
          description: The HTTP headers of the response.
          type: object
          additionalProperties:
            type: string
          example:
            Content-Type: application/json
        body:
          description: The HTTP body of the response.
          type: string
          example: '{"status": "success"}'
      required:
        - status_code
        - headers
    AnalysisEntityLabels:
      type: object
      description: Identified PII entity labels.
      additionalProperties: false
      properties:
        type:
          description: PII entity type. See <a
            href="/guides/reference/analysis-identified-pii-types">Analysis
            identified PII types</a> for details of the types detected abd codes
            returned.
          type: string
          example: CREDIT_DEBIT_NUMBER
        score:
          description: Accuracy of the PII match.
          type: number
          example: 0.9999213
    AnalysisEntity:
      type: object
      description: Identified PII entity type and location.
      additionalProperties: false
      properties:
        type:
          description: PII entity type. See <a
            href="/guides/reference/analysis-identified-pii-types">Analysis
            identified PII types</a> for details of the types detected abd codes
            returned.
          type: string
          example: CREDIT_DEBIT_NUMBER
        score:
          description: Accuracy of the PII match.
          type: number
          example: 0.9999213
        begin_offset:
          description: Text start offset for the match.
          type: integer
          format: int32
          example: 22
        end_offset:
          description: Text end offset for the match.
          type: integer
          format: int32
          example: 41
    AnalysisContainsFinding:
      type: object
      description: PII entity detection result.
      additionalProperties: false
      properties:
        pii:
          description: Whether the text contains PII.
          type: boolean
          default: true
          example: true
        labels:
          description: List of PII entity labels detected.
          type: array
          items:
            $ref: "#/components/schemas/AnalysisEntityLabels"
    AnalysisLocateFinding:
      type: object
      description: PII entity identification result.
      additionalProperties: false
      properties:
        pii:
          description: Whether the text contains PII.
          type: boolean
          default: true
          example: true
        detections:
          description: A list of PII entities identified.
          type: array
          items:
            $ref: "#/components/schemas/AnalysisEntity"
    AnalysisLanguage:
      description: Language of the text.
      type: string
      enum:
        - de
        - en
        - es
        - it
        - pt
        - fr
        - ja
        - ko
        - hi
        - ar
        - zh
        - zh-TW
      default: en
      example: en
    AnalysisRequest:
      type: object
      additionalProperties: false
      properties:
        language:
          $ref: "#/components/schemas/AnalysisLanguage"
        text:
          description: A list of text strings to locate and identify PII in.
          type: array
          items:
            type: string
          example:
            - My credit card number 1111-0000-1111-0000 has a minimum payment of
              $24.53.
      required:
        - text
    AnalysisContainsResponseBody:
      description: List of PII entity labels detected.
      type: array
      items:
        $ref: "#/components/schemas/AnalysisContainsFinding"
    AnalysisLocateResponseBody:
      description: A list of PII entities identified.
      type: array
      items:
        $ref: "#/components/schemas/AnalysisLocateFinding"
      example:
        - '{"text":"My credit card number 1111-0000-1111-0000 has a minimum
          payment of
          $24.53.","entities":[{"type":"CREDIT_DEBIT_NUMBER","score":0.99997807,"begin_offset":22,"end_offset":41}]}'
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
      description: >-
        ---

        sidebar_position: 2

        sidebar_label: Authentication

        ---


        # API authentication


        ### Bearer authorization header


        The Piiano Vault REST API uses API keys or JWT access tokens generated by an external identity provider to authenticate and authorize requests. It accepts Bearer tokens in the HTTP `Authorization` header using the `Bearer <api-key|jwt-token>` scheme.


        To enable evaluation and testing, Vault ships with a default API key of `pvaultauth` for the admin user. See [Set the admin's API key](/guides/manage-users-and-policies/set-admin-api-key) for information on how to set a value for this key.


        To obtain an API key for any other user, use the regenerate user API key [REST API operation](/api/operations/regenerate-user-api-key) or [CLI command](/cli/reference#regenerate-user-api-key).


        To learn how to create a JWT access token and set up Vault to authenticate it, see [Configure JWT authentication](/guides/manage-users-and-policies/direct-jwt-authentication).


        See [Manage users and policies](/guides/manage-users-and-policies) to learn more about how Vault controls access to operations and data.


        ### Tenant isolation header


        The Piiano Vault REST API supports an optional enforcement header to ensure tenant isolation. This header ensures that each operation is limited to the intended tenant.


        The enforcement header is `X-Tenant-Id`; its value is a comma-separated list of tenant IDs. The entire request fails with status code 403 when an enforcement violation is detected.


        For example, if the enforcement header is `X-Tenant-Id: 1,2,3`, then the operation is executed only if the resources are owned by tenant 1, 2, or 3.


        ### Object-level access


        When using JWT authentication, Vault supports object-level access control using special claims included in the JWT token. See [Namespace claims for JWT tokens](/guides/reference/namespace-claims-for-jwt) for more information.


        :::note

        Object-level access control for the tenant takes precedence over the tenant enforcement header if both are present.

        :::
