Schemas API

A Schema specifies the fields in a Document to index by the search engine. Schemas are specific to a Vault so you may update schemas in one Vault without affecting the schemas in another Vault. When a Schema is updated, all Documents associated with the updated Schema will be automatically re-indexed by our search engine.

An account’s User Schema is used to index the attributes fields of all the Users in the Account. There is only one User Schema per Account. Thus, you do not need to specify the User Schema ID when creating a new User.

Warning

A Schema with Documents associated with it cannot be deleted. You must delete or disassociate all documents first.

A Schema definition has two key/value pairs:

  • name: string(req’d) - the name of the schema
  • fields: array(req’d) - an array of field

Each field in the fields array has three key/value pairs:

  • name: string(req’d) - the name of the field in the Document that is to be indexed
  • index: boolean(req’d) - indicates if the field should be indexed
  • type: string(optional) - indicates the datatype of the field. Defaults to string if absent.

Warning

Field names must be case-insensitive unique. For example, two fields with name ‘first_name’ and ‘First_Name’ will not be accepted.

Accepted Datatypes: string, integer, long, float, double, boolean, date (yyyy-MM-dd), and geo_point.

In order to best represent a datetime object, you should store it as a string in ISO 8601 format or as a Unix timestamp integer.

Warning

Only one geo_point field is allowed per schema (indexed or no).

Example Schema Definition

{
   "name": "user",
   "fields": [
      {
         "name": "first_name",
         "index": true,
         "type": "string"
      },
      {
         "name": "street",
         "index": false,
         "type": "string"

      },
      {
         "name": "internal_id",
         "index": true,
         "type": "integer"
      },
      {
         "name": "created_date",
         "index": true,
         "type": "date"
      }
   ]
}

Create a Schema

https://d33wubrfki0l68.cloudfront.net/8513b318bb356a4044b0b241683868db1da61329/895a1/_images/plans-available-standard-plus.png
POST /v1/vaults/(string: vault_id)/schemas

Creates a new Schema in the specified Vault.

Parameters:
  • vault_id – string(req’d)
Form Parameters:
 
  • schema – b64 string(req’d) - the Schema definition as a base64 encoded JSON Document
Request Headers:
 
Status Codes:
  • 200 OK – success
  • 400 Bad Request – invalid vault_id, invalid base64 encoded JSON Document, Schema definition missing required fields, Schema name already exists

Example Request

curl https://api.truevault.com/v1/vaults/00000000-0000-0000-0000-000000000000/schemas \
    -X POST \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d "schema=eyJuYW1lIjoidGVzdF9zY2hlbWEiLCJmaWVsZHMiOltdfQ=="

Example Response

{
    "schema": {
        "fields": [],
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "test_schema",
        "vault_id": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Read a Schema

https://d33wubrfki0l68.cloudfront.net/8513b318bb356a4044b0b241683868db1da61329/895a1/_images/plans-available-standard-plus.png
GET /v1/vaults/(string: vault_id)/schemas/(string: schema_id)

Gets an existing Schema.

Parameters:
  • vault_id – string(req’d)
  • schema_id – string(req’d)
Request Headers:
 
Status Codes:

Example Request

curl https://api.truevault.com/v1/vaults/00000000-0000-0000-0000-000000000000/schemas/00000000-0000-0000-0000-000000000000 \
    -X GET \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "schema": {
        "fields": [],
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "test_schema",
        "vault_id": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

List all Schemas

https://d33wubrfki0l68.cloudfront.net/8513b318bb356a4044b0b241683868db1da61329/895a1/_images/plans-available-standard-plus.png
GET /v1/vaults/(string: vault_id)/schemas

Returns all Schemas in the specified Vault.

Parameters:
  • vault_id – string(req’d)
Request Headers:
 
Status Codes:

Example Request

curl https://api.truevault.com/v1/vaults/00000000-0000-0000-0000-000000000000/schemas \
    -X GET \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "schemas": [
        {
            "fields": [],
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "test_schema",
            "vault_id": "00000000-0000-0000-0000-000000000000"
        }
    ],
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Update a Schema

https://d33wubrfki0l68.cloudfront.net/8513b318bb356a4044b0b241683868db1da61329/895a1/_images/plans-available-standard-plus.png
PUT /v1/vaults/(string: vault_id)/schemas/(string: schema_id)

Updates an existing Schema in the specified Vault.

Note

This endpoint consumes one operation for every document in this schema. For example, if you have 10k documents in a schema and you update the schema, that costs 10k operations from your monthly allotment.

Parameters:
  • vault_id – string(req’d)
  • schema_id – string(req’d)
Form Parameters:
 
  • schema – b64 string(req’d) - Schema definition as a base64 encoded JSON document
Request Headers:
 
Status Codes:
  • 200 OK – success
  • 400 Bad Request – invalid vault_id, invalid base64 encoded JSON document, Schema definition missing required field, Schema name already exists

Example Request

curl https://api.truevault.com/v1/vaults/00000000-0000-0000-0000-000000000000/schemas/00000000-0000-0000-0000-000000000000 \
    -X PUT \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d "schema=eyJuYW1lIjoidGVzdF9zY2hlbWFfMCIsImZpZWxkcyI6W119"

Example Response

{
    "schema": {
        "fields": [],
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "test_schema_0",
        "vault_id": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Delete a Schema

https://d33wubrfki0l68.cloudfront.net/8513b318bb356a4044b0b241683868db1da61329/895a1/_images/plans-available-standard-plus.png
DELETE /v1/vaults/(string: vault_id)/schemas/(string: schema_id)

Deletes a specified Schema. Must not have any associated documents.

Parameters:
  • vault_id – string(req’d)
  • schema_id – string(req’d)
Request Headers:
 
Status Codes:

Example Request

curl https://api.truevault.com/v1/vaults/00000000-0000-0000-0000-000000000000/schemas/00000000-0000-0000-0000-000000000000 \
    -X DELETE \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "result": "success",
    "schema_id": "00000000-0000-0000-0000-000000000000",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Create the User Schema

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
POST /v1/accounts/(string: account_id)/user_schema

Create the Account’s UserSchema.

Requires Policy C on UserSchema::

Note

Accounts are created with a default schema that only supports searching on system fields. If you want to add fields to the User Schema, see the Update User Schema endpoint.

Parameters:
  • account_id – string(req’d)
Form Parameters:
 
  • schema – string(req’d) - Schema definition
Request Headers:
 
Status Codes:

Example Request

curl https://api.truevault.com/v1/accounts/00000000-0000-0000-0000-000000000000/user_schema \
    -X POST \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d "schema=eyJuYW1lIjoidGVzdF9zY2hlbWEiLCJmaWVsZHMiOltdfQ=="

Example Response

{
    "user_schema": {
        "fields": [],
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "test_schema",
        "vault_id": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Read the User Schema

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
GET /v1/accounts/(string: account_id)/user_schema

Retrieve the account’s UserSchema.

Requires Policy R on UserSchema::

Parameters:
  • account_id – string(req’d)
Request Headers:
 
Status Codes:

Example Request

curl https://api.truevault.com/v1/accounts/00000000-0000-0000-0000-000000000000/user_schema \
    -X GET \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "user_schema": {
        "fields": [],
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "test_schema",
        "vault_id": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Update the User Schema

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
PUT /v1/accounts/(string: account_id)/user_schema

Update the Account’s UserSchema.

Note

This endpoint consumes one operation for every user in the account. For example, if you have 10k users in your account and you update the user schema, that costs 10k operations from your monthly allotment.

Requires Policy U on UserSchema::

Parameters:
  • account_id – string(req’d)
Request Headers:
 
Status Codes:

Example Request

curl https://api.truevault.com/v1/accounts/00000000-0000-0000-0000-000000000000/user_schema \
    -X PUT \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d "schema=eyJuYW1lIjoidGVzdF9zY2hlbWEiLCJmaWVsZHMiOltdfQ=="

Example Response

{
    "user_schema": {
        "fields": [],
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "test_schema",
        "vault_id": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Delete the User Schema

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
DELETE /v1/accounts/(string: account_id)/user_schema

Delete the Account’s UserSchema.

Requires Policy D on UserSchema::

Parameters:
  • account_id – string(req’d)
Request Headers:
 
Status Codes:

Example Request

curl https://api.truevault.com/v1/accounts/00000000-0000-0000-0000-000000000000/user_schema \
    -X DELETE \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
    "user_schema": {
        "fields": [],
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "test_schema",
        "vault_id": "00000000-0000-0000-0000-000000000000"
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}