Documents API

Create a Document

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
POST /v2/vaults/(string: vault_id)/documents

Note

This is a V2 Endpoint, so the path should start with v2

POST a JSON object with the following fields:

  • document (req’d) - the JSON object you wish to store (e.g. {"foo": "bar"}). Must be an Object if schema_id present.
  • schema_id string(optional) - schema_id of the Schema definition by which the Document will be indexed against
  • owner_id string(optional) - owner_id of the newly created Document. If null or omitted, the newly created Document will be ownerless.

Request Headers:

  • Authorization: API_KEY or ACCESS_TOKEN
  • Content-Type: application/json

Status Codes:

  • 200: success

Example Request

curl https://api.truevault.com/v2/vaults/fd6b3fbf-41a0-4781-b179-32a34d854b92/documents \
    -X POST \
    -H 'Content-Type: application/json' \
    -u [API_KEY | ACCESS_TOKEN]: \
    -d '{"document": {"foo": "bar"}}'

Example Response

{
  "document": {
    "id": "f608a711-af4e-45c4-8742-af8d2a61a840",
    "owner_id": null,
    "vault_id": "fd6b3fbf-41a0-4781-b179-32a34d854b92"
  },
  "document_id": "f608a711-af4e-45c4-8742-af8d2a61a840",
  "result": "success",
  "transaction_id": "796de512-e939-4167-8d44-db05eb6804e1"
}
Deprecated version

A previous version of this endpoint used an HTML form post instead of a JSON object. It is still supported for now, but new development should use the version described above.

  • document b64 string(req’d) - base64 encoded JSON Document string. Must be an Object if schema_id present.
  • schema_id string(optional) - schema_id of the Schema definition by which the Document will be indexed against
  • owner_id string(optional) - owner_id of the newly created Document. If null or omitted, the newly created Document will be ownerless.

Request Headers:

  • Authorization API_KEY or ACCESS_TOKEN

Status Codes:

  • 200: success
  • 400: invalid base64 encoded JSON Document

Example Request

curl https://api.truevault.com/v1/vaults/00000000-0000-0000-0000-000000000000/documents \
    -u [API_KEY | ACCESS_TOKEN]: \
    -X POST \
    -d "document=e30=&schema_id=00000000-0000-0000-0000-000000000000&owner_id=00000000-0000-0000-0000-000000000000"

Example Response

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

Read a Document

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
GET /v2/vaults/(string: vault_id)/documents/(string: document_id)

Get one or more documents.

Parameters:
  • vault_id – string(req’d)
  • document_id – string(req’d) comma-separated list of one or more document IDs

Note

This is a V2 Endpoint, so the path should start with v2

Note: This endpoint consumes an Operation for every document returned, so a request with 50 ids will count as 50 Operations.

Request Headers:

  • Authorization: API_KEY or ACCESS_TOKEN

Status Codes:

  • 200: success

Example Request

curl https://api.truevault.com/v2/vaults/fd6b3fbf-41a0-4781-b179-32a34d854b92/documents/11b887e6-1b71-419d-abda-2b8c2e4348e1 \
    -u [API_KEY | ACCESS_TOKEN]:

Example Response

{
  "documents": [
    {
      "document": {
        "foo": "baz"
      },
      "id": "11b887e6-1b71-419d-abda-2b8c2e4348e1",
      "owner_id": null
    }
  ],
  "result": "success",
  "transaction_id": "5e328ef2-a403-44b6-97ee-3f7abeed8356"
}
Deprecated version
GET /v1/vaults/(string: vault_id)/documents/(string: document_id)

Gets multiple Documents at once. If reading a single document, returns only the document’s contents as a base64-encoded string with no JSON framing.

Parameters:
  • vault_id – string(req’d)
  • document_id – string(req’d) - comma separated list of Document IDs to retrieve. At most 100 ids can be fetched at a time. Note: This endpoint consumes an Operation for every document returned, so a request with 50 ids will count as 50 Operations.
Request Headers:
 
Status Codes:

Example Request

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

Example Response (multiple documents)

{
    "documents": [
        {
            "document": "e30=",
            "id": "00000000-0000-0000-0000-000000000000",
            "owner_id": "00000000-0000-0000-0000-000000000000"
        },
        {
            "document": "e30=",
            "id": "00000000-0000-0000-0000-000000000001",
            "owner_id": "00000000-0000-0000-0000-000000000000"
        }
    ],
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Example Response (single document)

e30=

List all Documents

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
GET /v1/vaults/(string: vault_id)/documents

List all Documents in a Vault.

Parameters:
  • vault_id – string(req’d)
Query Parameters:
 
  • full – boolean(optional, default: ‘false’) - retrieve entire Document contents. Note: If true, then this endpoint consumes an Operation for every document returned. If false, only a single Operation is used.
  • page – integer(optional, default: 1) - specify page number for paginated response
  • per_page – integer(optional, default: 100, max: 500) - specify number of results per page in paginated response
Request Headers:
 
Status Codes:

Example Request

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

Example Response

{
    "data": {
        "full_document": false,
        "items": [
            {
                "id": "00000000-0000-0000-0000-000000000000",
                "schema_id": "00000000-0000-0000-0000-000000000000",
                "vault_id": "00000000-0000-0000-0000-000000000000",
                "owner_id": "00000000-0000-0000-0000-000000000000"
            }
        ],
        "page": 1,
        "per_page": 100,
        "total": 1
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

List all Documents with Schema

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

List all Documents in a vault associated with a specified Schema.

Parameters:
  • vault_id – string(req’d)
  • schema_id – string(req’d)
Query Parameters:
 
  • full – boolean(optional, default: ‘false’) - retrieve entire Document contents. Note: If true, then this endpoint consumes an Operation for every document returned. If false, only a single Operation is used.
  • page – integer(optional, default: 1) - specify page number for paginated response
  • per_page – integer(optional, default: 100, max: 500) - specify number of results per page in paginated response
Request Headers:
 
Status Codes:

Example Request

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

Example Response

{
    "data": {
        "full_document": false,
        "items": [
            {
                "id": "00000000-0000-0000-0000-000000000000",
                "schema_id": "00000000-0000-0000-0000-000000000000",
                "vault_id": "00000000-0000-0000-0000-000000000000",
                "owner_id": "00000000-0000-0000-0000-000000000000"
            }
        ],
        "page": 1,
        "per_page": 100,
        "total": 1
    },
    "result": "success",
    "transaction_id": "00000000-0000-0000-0000-000000000000"
}

Update a Document

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
PUT /v2/vaults/(string: vault_id)/documents/(string: document_id)

Note

This is a V2 Endpoint, so the path should start with v2

PUT a JSON object with the following fields:

  • document (req’d) - the JSON object you wish to store (e.g. {"foo": "baz"}). Must be an Object if schema_id present or if the Document was previously associated with a schema.
  • schema_id string(optional) - schema_id of the Schema definition by which the Document will be indexed against. If no schema_id is provided, then the Document will stay associated to its existing Schema.
  • owner_id string(optional) - owner_id of the user the Document will be owned by. If no owner_id is provided, then the Document will stay owned by its existing owner. If it is null, then the Document will become ownerless.

Request Headers:

  • Authorization: API_KEY or ACCESS_TOKEN
  • Content-Type: application/json

Status Codes:

  • 200: success

Example Request

curl https://api.truevault.com/v2/vaults/fd6b3fbf-41a0-4781-b179-32a34d854b92/documents/11b887e6-1b71-419d-abda-2b8c2e4348e1 \\
    -X PUT \\
    -H 'Content-Type: application/json' \\
    -u [API_KEY | ACCESS_TOKEN]: \\
    -d '{"document": {"foo": "baz"}}'

Example Response

{
  "document": {
    "id": "11b887e6-1b71-419d-abda-2b8c2e4348e1",
    "owner_id": null,
    "vault_id": "fd6b3fbf-41a0-4781-b179-32a34d854b92"
  },
  "document_id": "11b887e6-1b71-419d-abda-2b8c2e4348e1",
  "result": "success",
  "transaction_id": "f47deaa3-74f8-478f-983d-957ef91c6106"
}
Deprecated version
  • document b64 string(req’d) - new base64 encoded JSON Document string. Must be an Object if schema_id present or if the Document was previously associated with a schema.
  • schema_id string(optional) - schema_id of the Schema definition by which the Document will be indexed against. If no schema_id is provided, then the Document will stay associated to its existing Schema.
  • owner_id string(optional) - owner_id of the user the Document will be owned by. If no owner_id is provided, then the Document will stay owned by its existing owner. If it is an empty string, then the Document will become ownerless.

Request Headers:

  • Authorization: API_KEY or ACCESS_TOKEN

Status Codes:

  • 200: success
  • 400: invalid base64 encoded JSON Document
  • 404: Document does not exist

Example Request

curl https://api.truevault.com/v1/vaults/00000000-0000-0000-0000-000000000000/documents/00000000-0000-0000-0000-000000000000 \\
    -u [API_KEY | ACCESS_TOKEN]: \\
    -X PUT \\
    -d "document=e30=&schema_id=00000000-0000-0000-0000-000000000000&owner_id=00000000-0000-0000-0000-000000000000"

Example Response

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

Update a Document’s Owner

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
PUT /v1/vaults/(string: vault_id)/documents/(string: document_id)/owner

Updates only the owner_id for a Document having document_id. This can be used to update the owner of a document if changes to the document content are undesirable. If changes to the document content are desired, see the Update Document operation.

Parameters:
  • vault_id – string(req’d)
  • document_id – string(req’d)
Form Parameters:
 
  • owner_id – string(req’d) - owner_id of the user the Document will be owned by. If '', then the Document will become ownerless. Note: unlike the update endpoint, the owner_id field cannot be omitted, it must be specified with an empty value to remove the owner.
Request Headers:
 
Status Codes:

Example Requests

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

Removing an owner:

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

Example Response

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

Delete a Document

https://d33wubrfki0l68.cloudfront.net/46256db48654ea43d1fd9377023f4d876582d839/ab631/_images/plans-available-all.png
DELETE /v1/vaults/(string: vault_id)/documents/(string: document_id)

Deletes a Document from a Vault.

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

Example Request

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

Example Response

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

Reindex a Document

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

Reindex a Document against its Schema.

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

Example Request

curl https://api.truevault.com/v1/vaults/00000000-0000-0000-0000-000000000000/documents/00000000-0000-0000-0000-000000000000/reindex \
    -X POST \
    -u [API_KEY]:

Example Response

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