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

  Default: jsonAllowed values: pvschema, json
• options - array of strings

  Each string:

  Allowed values: show_builtins

Request body

application/json

object required*

Additional properties: falseProperties:

• creation_time - string

  Format: date-timeExample: "2022-07-05T08:47:12.041234Z"
• modification_time - string

  Format: date-timeExample: "2022-07-05T08:47:12.041234Z"
• name - string required*

  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

    Format: date-timeExample: "2022-07-05T08:47:12.041234Z"
  • modification_time - string

    Format: date-timeExample: "2022-07-05T08:47:12.047Z"
  • description - string

    Max length: 450
  • is_builtin - boolean

    Default: falseExample: false
  • is_encrypted - boolean

    Default: trueExample: true
  • is_index - boolean

    Default: falseExample: false
  • is_substring_index - boolean

    Default: falseExample: false
  • is_nullable - boolean

    Default: falseExample: false
  • is_readonly - boolean

    Default: falseExample: false
  • is_unique - boolean

    Default: falseExample: false
  • name - string required*

    Match pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$Max length: 40Example: "first_name"
  • data_type_name - string required*

    Match pattern: ^[a-zA-Z][a-zA-Z0-9_]*$Max length: 450Example: "STRING"
• type - string required*

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

application/pvschema

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

200

application/json

object required*

Additional properties: falseProperties:

• creation_time - string

  Format: date-timeExample: "2022-07-05T08:47:12.041234Z"
• modification_time - string

  Format: date-timeExample: "2022-07-05T08:47:12.041234Z"
• name - string required*

  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

    Format: date-timeExample: "2022-07-05T08:47:12.041234Z"
  • modification_time - string

    Format: date-timeExample: "2022-07-05T08:47:12.047Z"
  • description - string

    Max length: 450
  • is_builtin - boolean

    Default: falseExample: false
  • is_encrypted - boolean

    Default: trueExample: true
  • is_index - boolean

    Default: falseExample: false
  • is_substring_index - boolean

    Default: falseExample: false
  • is_nullable - boolean

    Default: falseExample: false
  • is_readonly - boolean

    Default: falseExample: false
  • is_unique - boolean

    Default: falseExample: false
  • name - string required*

    Match pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$Max length: 40Example: "first_name"
  • data_type_name - string required*

    Match pattern: ^[a-zA-Z][a-zA-Z0-9_]*$Max length: 450Example: "STRING"
• type - string required*

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

application/pvschema

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

400

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  Example: "PVxxxx"
• message - string required*

  Example: "The object is not found."
• error_url - string

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

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

401

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  Example: "PVxxxx"
• message - string required*

  Example: "The object is not found."
• error_url - string

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

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

403

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  Example: "PVxxxx"
• message - string required*

  Example: "The object is not found."
• error_url - string

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

404

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  Example: "PVxxxx"
• message - string required*

  Example: "The object is not found."
• error_url - string

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

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

405

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  Example: "PVxxxx"
• message - string required*

  Example: "The object is not found."
• error_url - string

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

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

409

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  Example: "PVxxxx"
• message - string required*

  Example: "The object is not found."
• error_url - string

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

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

410

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  Example: "PVxxxx"
• message - string required*

  Example: "The object is not found."
• error_url - string

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

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

500

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  Example: "PVxxxx"
• message - string required*

  Example: "The object is not found."
• error_url - string

  Example: "https://docs.piiano.com/api/error-codes#PV1005"

Example

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

503

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  Example: "PVxxxx"
• message - string required*

  Example: "The object is not found."
• error_url - string

  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:

Options:

Request body

Content-Type:

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

Code examples

Example