VQL API Headers

Vault API supports specific HTTP headers that provide additional metadata or record properties in the VQL query response. Use these headers to retrieve detailed information about your query structure or to access record-level data such as field permissions and additional formula field attributes.

Query Describe

When you set the X-VaultAPI-DescribeQuery header to true, the response includes the queryDescribe object. This object provides metadata on your query, such as the name and label of the query target and retrieved fields. Learn more in the VQL API Reference.

For example, this response provides a description of a query that uses a SELECT statement to retrieve the id and name__v from documents:

{
    "responseStatus": "SUCCESS",
    "queryDescribe": {
        "type": "select__sys",
        "object": {
            "name": "documents",
            "label": "documents",
            "label_plural": "documents"
        },
        "fields": [
            {
                "type": "id",
                "required": true,
                "name": "id"
            },
            {
                "label": "Name",
                "type": "String",
                "required": true,
                "name": "name__v",
                "max_length": 100
            }
        ]
    },
    "responseDetails": {
        "pagesize": 1000,
        "pageoffset": 0,
        "size": 3,
        "total": 3
    },
    "data": [
        {
            "id": 26,
            "name__v": "Verntorvastatin Batch Manufacturing Record"
        },
        {
            "id": 6,
            "name__v": "Cholecap-Logo"
        },
        {
            "id": 5,
            "name__v": "CholeCap Visual Aid"
        }
    ]
}

Record Properties

The X-VaultAPI-RecordProperties header retrieves record properties for a query result and returns them in the record_properties object. Record properties provide additional record data that is not otherwise included in the query response:

Field properties:
- Hidden fields: Fields that are not visible to the user for this record. A field might not be visible on a record if it is hidden from the user by Atomic Security.
- Redacted fields: Fields that are redacted for this record. A field is redacted if the querying user is System and the field contains Protected Health Information (PHI) or Personally Identifiable Information (PII). Learn more in Vault Help.
- Editable fields: Fields that are editable for this record.
Record permissions: The Edit, Delete, Create, and Read permissions for this record.
Weblink: Additional attributes for formula fields that use the Hyperlink() function. Learn more about the Hyperlink() function in Vault Help.
Hidden subqueries: Hidden subquery relationships for this record. For example, attachments__sysr if attachments are hidden from the user by Atomic Security.

Learn more about the X-VaultAPI-RecordProperties header in the VQL API Reference.

For example, the following query retrieves the id and hyperlink__c formula field for the product named Cholecap:

SELECT id, hyperlink__c
FROM product__v
WHERE name__v = 'Cholecap'

When a request for the above query uses the X-VaultAPI-RecordProperties=all header, the response provides the record_properties object containing field_properties, permissions, and field_additional_data:

{
    "responseStatus": "SUCCESS",
    "responseDetails": {
        "pagesize": 1000,
        "pageoffset": 0,
        "size": 1,
        "total": 1
    },
    "data": [
        {
            "id": "cholecap",
            "hyperlink__c": "https://cholecap.com"
        }
    ],
    "record_properties": [
        {
            "id": "cholecap",
            "permissions": {
               "read": true,
               "edit": true,
               "create": true,
               "delete": true
           },
           "field_properties": {
               "hidden": [],
               "redacted": [],
               "edit": []
           },


            "subquery_properties": {},
            "field_additional_data": {
                "hyperlink__c": {
                    "web_link": {
                        "label": "Cholecap Site",
                        "target": "new_window",
                        "connection": null
                    }
                }
            }
        }
    ]
}