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¶

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.

Request Headers:
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.
	Authorization – `API_KEY` or `ACCESS_TOKEN`
Status Codes:	200 OK – success 404 Not Found – Document does not exist

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¶

GET /v1/vaults/(string: vault_id)/documents¶

List all Documents in a Vault.

Query Parameters:
Parameters:	vault_id – string(req’d)
	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:
	Authorization – `API_KEY` or `ACCESS_TOKEN`
Status Codes:	200 OK – success

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.

Query Parameters:
Parameters:	vault_id – string(req’d) schema_id – string(req’d)
	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:
	Authorization – `API_KEY` or `ACCESS_TOKEN`
Status Codes:	200 OK – success

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¶

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¶

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.

Form Parameters:
Parameters:	vault_id – string(req’d) document_id – string(req’d)
	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:
	Authorization – `API_KEY` or `ACCESS_TOKEN`
Status Codes:	200 OK – success 404 Not Found – Document does not exist

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¶

DELETE /v1/vaults/(string: vault_id)/documents/(string: document_id)¶

Deletes a Document from a Vault.

Request Headers:
Parameters:	vault_id – string(req’d) document_id – string(req’d)
	Authorization – `API_KEY` or `ACCESS_TOKEN`
Status Codes:	200 OK – success 404 Not Found – Document does not exist

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¶

POST /v1/vaults/(string: vault_id)/documents/(string: document_id)/reindex¶

Reindex a Document against its Schema.

Request Headers:
Parameters:	vault_id – string(req’d) document_id – string(req’d)
	Authorization – `API_KEY`
Status Codes:	200 OK – success

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