Add collection

post

/api/pvlt/1.0/ctl/collections

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 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.

The role performing this operation must have the CapCollectionsWriter capability. See Access control for more information about how capabilities are used to control access to operations.

Request

Query parameters

format - string
The format of the response. Overrides any Accept header value provided.
Default: jsonAllowed values: pvschema, json
custom_audit - string
Custom audit information to be included in the audit log.
options - array of strings
Options for the operation. Options include:
- show_builtins – show built-in properties in the response.
Each string:
Allowed values: show_builtins

Request body

Details of the collection including its properties.

application/json
application/pvschema

object required*

Additional properties: falseProperties:

creation_time - string
The time when the collection was created, in RFC3339Nano format. Vault sets this value automatically. Sending a value for this field is ignored.
Format: date-timeExample: "2022-07-05T08:47:12.041234Z"
modification_time - string
The time when the collection was last modified, in RFC3339Nano format. Vault sets this value automatically. Sending a value for this field is ignored.
Format: date-timeExample: "2022-07-05T08:47:12.041234Z"
name - string required*
The name of a collection.
Match pattern: ^[a-zA-Z][a-zA-Z0-9_]*$Max length: 40Example: "customers"
properties - array of objects required*
Each object:
Additional properties: falseProperties:
- creation_time - string
  The time when the property was created, in RFC3339Nano format. Vault sets this value automatically. Sending a value for this field is ignored.
  Format: date-timeExample: "2022-07-05T08:47:12.041234Z"
- modification_time - string
  The time when the property was last modified, in RFC3339 format. Vault sets this value automatically. Sending a value for this field is ignored.
  Format: date-timeExample: "2022-07-05T08:47:12.047Z"
- description - string
  The description of a model.
  Max length: 450
- is_builtin - boolean
  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.
  Default: falseExample: false
- is_encrypted - boolean
  Whether the value is stored encrypted.
  Default: trueExample: true
- is_index - boolean
  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.
  Default: falseExample: false
- is_substring_index - boolean
  Whether the backend storage is optimized for substring searches on this property. See indexing in the data type reference for a list of supported data types.
  Default: falseExample: false
- is_nullable - boolean
  Whether the value of the property can be removed (set to null).
  Default: falseExample: false
- is_readonly - boolean
  Whether the user can modify values of this property. Ignored for user define properties. Sending a value for this field is ignored.
  Default: falseExample: false
- is_unique - boolean
  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.
  Default: falseExample: false
- name - string required*
  The name of a property.
  Match pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$Max length: 40Example: "first_name"
- data_type_name - string required*
  The name of a data type.
  Match pattern: ^[a-zA-Z][a-zA-Z0-9_]*$Max length: 450Example: "STRING"
type - string required*
The schema prototype the collection is based on.
Allowed values: 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
    }
  ]
}

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
    }
  ]
}

string required*

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',
);

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',
);

Possible responses

The request is successful.

application/json
application/pvschema

object required*

Additional properties: falseProperties:

creation_time - string
The time when the collection was created, in RFC3339Nano format. Vault sets this value automatically. Sending a value for this field is ignored.
Format: date-timeExample: "2022-07-05T08:47:12.041234Z"
modification_time - string
The time when the collection was last modified, in RFC3339Nano format. Vault sets this value automatically. Sending a value for this field is ignored.
Format: date-timeExample: "2022-07-05T08:47:12.041234Z"
name - string required*
The name of a collection.
Match pattern: ^[a-zA-Z][a-zA-Z0-9_]*$Max length: 40Example: "customers"
properties - array of objects required*
Each object:
Additional properties: falseProperties:
- creation_time - string
  The time when the property was created, in RFC3339Nano format. Vault sets this value automatically. Sending a value for this field is ignored.
  Format: date-timeExample: "2022-07-05T08:47:12.041234Z"
- modification_time - string
  The time when the property was last modified, in RFC3339 format. Vault sets this value automatically. Sending a value for this field is ignored.
  Format: date-timeExample: "2022-07-05T08:47:12.047Z"
- description - string
  The description of a model.
  Max length: 450
- is_builtin - boolean
  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.
  Default: falseExample: false
- is_encrypted - boolean
  Whether the value is stored encrypted.
  Default: trueExample: true
- is_index - boolean
  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.
  Default: falseExample: false
- is_substring_index - boolean
  Whether the backend storage is optimized for substring searches on this property. See indexing in the data type reference for a list of supported data types.
  Default: falseExample: false
- is_nullable - boolean
  Whether the value of the property can be removed (set to null).
  Default: falseExample: false
- is_readonly - boolean
  Whether the user can modify values of this property. Ignored for user define properties. Sending a value for this field is ignored.
  Default: falseExample: false
- is_unique - boolean
  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.
  Default: falseExample: false
- name - string required*
  The name of a property.
  Match pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$Max length: 40Example: "first_name"
- data_type_name - string required*
  The name of a data type.
  Match pattern: ^[a-zA-Z][a-zA-Z0-9_]*$Max length: 450Example: "STRING"
type - string required*
The schema prototype the collection is based on.
Allowed values: 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
    }
  ]
}

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"
}

string required*

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',
);

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',
);

The request is invalid.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1001",
  "message": "The access reason is missing.",
  "context": {
    "reason": null
  }
}

Authentication credentials are incorrect or missing.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1005",
  "message": "The request is unauthorized.",
  "context": {}
}

The caller doesn't have the required access rights.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1007",
  "message": "The operation is forbidden due to missing capabilities.",
  "context": {
    "username": "WebServer"
  }
}

Reserved for future use.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1004",
  "message": "The collection is not found.",
  "context": {}
}

The operation is not allowed.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1026",
  "message": "The operation is not allowed in in-memory mode.",
  "context": {}
}

A conflict occurs.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV3218",
  "message": "Concurrent conflicting updates to the same object.",
  "context": {}
}

Access to a resource that is no longer available occurs.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1033",
  "message": "The resource is gone.",
  "context": {}
}

An error occurs on the server.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1000",
  "message": "Something went wrong",
  "context": {}
}

The service is unavailable.

application/json

object required*

Additional properties: falseProperties:

context - object required*
The error context.
Values of additional properties are strings
Example
{ "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002" }
error_code - string required*
The error code.
Example: "PVxxxx"
message - string required*
The error message.
Example: "The object is not found."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example
{
  "error_code": "PV1009",
  "message": "The operation timed out on the server.",
  "context": {}
}

Try the API

Authorization

API key:

Query parameters

Format:

Custom_audit:

Options:

Request body

Content-Type:

Navigate to the docs of your local Vault installation to try the API directly from there.

Code examples

Example

Request​

Query parameters​

Request body​

Possible responses​

Try the API

Authorization

Query parameters

Request body

Code examples

Request

Query parameters

Request body

Possible responses