> For the complete documentation index, see [llms.txt](https://guardian.hedera.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guardian.hedera.com/docs/develop/guardian/workspace/policies/verifiable-credential-documents/dynamic-data-query/query-policy-data-documents.md). # Query Policy Data Documents **`GET /policy-data/query`** Returns a paginated list of Verifiable Credential (VC) documents committed by a published policy, filtered by schema name. Supports field-level filtering, sorting, and pagination. This endpoint requires authentication. The policy must be in `PUBLISH` status. *** ## Authentication This endpoint requires a valid JWT Bearer token. The authenticated user must hold at least one of the following permissions: `POLICIES_POLICY_AUDIT`, `POLICIES_POLICY_MANAGE`. `POLICIES_POLICY_MANAGE` callers are restricted to policies owned by their own Standard Registry tenant (a policy from a different tenant returns `403 Forbidden`); `POLICIES_POLICY_AUDIT` (the Auditor role) is exempt from this restriction, since Auditors are a cross-organization role by design. *** ## Request ### Query Parameters | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `policyId` | string | Yes | MongoDB ObjectId of the published policy | | `schemaName` | string | Yes | Human-readable schema name as registered in the policy (e.g. `Installer Activity Report`). If multiple versions of a schema with this name exist under the policy's topic, the latest version is used | | `filters` | string | No | URL-encoded JSON filter map. See [Filters](#filters) below | | `sort` | string | No | Field to sort by. Prefix `-` for descending (e.g. `-createDate`, `owner`). Limited to system fields (same set as the filter whitelist below, minus `option.*`/`document.*`); default is `-createDate` | | `page` | number | No | 1-based page number. Default: `1` | | `pageSize` | number | No | Results per page. Min `1`, max `200`. Default: `20` | ### Filters The `filters` parameter is a URL-encoded JSON object. Each key is a field name and each value has the shape `{ "op": "", "value": }`. Multiple filters are combined with AND logic. **Allowed field prefixes:** | Prefix | Example | Description | | ------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | System fields | `owner`, `hederaStatus`, `createDate`, `tag` | Fixed set of top-level document fields | | `option.` | `option.status` | Workflow option fields set by `sendToGuardianBlock` | | `document.` | `document.credentialSubject[0].field3` | Credential subject fields cached by the policy grid configuration. Bracket `[0]` and dot `.0.` notation both accepted | **Supported operators:** | Operator | Description | Value type | | ---------- | ------------------------------------- | ------------------------------------------------------------------------- | | `eq` | Equals | string, number, boolean, or `null` | | `ne` | Not equal | string, number, boolean, or `null` | | `in` | Value in list — exact match | array of string, number, or boolean (no `null`, no nested objects/arrays) | | `nin` | Value not in list | array of string, number, or boolean (no `null`, no nested objects/arrays) | | `gt` | Greater than | string, number, or boolean (no `null`) | | `gte` | Greater than or equal | string, number, or boolean (no `null`) | | `lt` | Less than | string, number, or boolean (no `null`) | | `lte` | Less than or equal | string, number, or boolean (no `null`) | | `contains` | Case-insensitive partial string match | string, max 256 characters | **Example — single filter (Compliance Score greater than or equal to 80):** ```json { "document.credentialSubject[0].field3": { "op": "gte", "value": 80 } } ``` **Example — enum field using `in` (Rating is Pass or Conditional):** ```json { "document.credentialSubject[0].field2": { "op": "in", "value": ["Pass", "Conditional"] } } ``` **Example — partial text match using `contains`:** ```json { "document.credentialSubject[0].field1": { "op": "contains", "value": "Lanka" } } ``` **Example — option field filter:** ```json { "option.status": { "op": "eq", "value": "Submitted" } } ``` **Example — multiple filters combined (AND):** ```json { "document.credentialSubject[0].field2": { "op": "in", "value": ["Pass", "Conditional"] }, "document.credentialSubject[0].field3": { "op": "gte", "value": 70 }, "option.status": { "op": "eq", "value": "Submitted" }, "createDate": { "op": "gte", "value": "2025-01-01T00:00:00Z" } } ``` *** ## Response ### Success Response **Status:** `200 OK` ```json { "data": [ { "_id": "69efa3aa5a5a844b0cd2153a", "policyId": "6812a1f3e4b0f1a2b3c4d5e6", "schema": "#auditor-inspection-report&1.0.0", "owner": "did:hedera:testnet:z...", "hederaStatus": "NEW", "tag": "save_auditor_doc", "option": { "status": "Submitted" }, "document": { "credentialSubject": [ { "field0": "SITE-001", "field1": "2025-04-15", "field2": "Pass", "field3": 92, "field4": "All compliance criteria met." } ] }, "createDate": "2025-04-15T10:22:00.000Z", "updateDate": "2025-04-15T10:22:01.000Z" } ], "pagination": { "page": 1, "pageSize": 20, "total": 1, "totalPages": 1 }, "query": { "policyId": "6812a1f3e4b0f1a2b3c4d5e6", "schemaName": "Auditor Inspection Report", "appliedFilters": { "document.credentialSubject[0].field3": { "op": "gte", "value": 80 } } } } ``` | Field | Type | Description | | ----------------------- | ------ | ------------------------------------------------------------------------------ | | `data` | array | Array of VC document objects matching the query | | `data[].policyId` | string | MongoDB ObjectId of the owning policy | | `data[].schema` | string | Schema IRI | | `data[].owner` | string | DID of the document owner | | `data[].hederaStatus` | string | HCS anchoring status (`NEW`, `ISSUE`, `REVOKE`, `SUSPEND`, `RESUME`, `FAILED`) | | `data[].tag` | string | Policy block tag that produced the document | | `data[].option` | object | Workflow option bag (e.g. `{ "status": "Submitted" }`) | | `data[].document` | object | Cached credential subject fields | | `data[].createDate` | string | ISO 8601 creation timestamp | | `data[].updateDate` | string | ISO 8601 last update timestamp | | `pagination.page` | number | Current page (1-based) | | `pagination.pageSize` | number | Results per page | | `pagination.total` | number | Total matching documents | | `pagination.totalPages` | number | Total number of pages | | `query` | object | Echo of the resolved query parameters including applied filters | ### Error Responses | Status | Description | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400 Bad Request` | Missing required parameter, invalid JSON in `filters`, unknown filter field, unsupported operator, non-primitive filter value, `contains` value over 256 characters, or an unsupported `sort` field | | `401 Unauthorized` | JWT token is missing or invalid | | `403 Forbidden` | Insufficient permissions; the policy belongs to a different Standard Registry tenant; or the policy is not in `PUBLISH` status | | `404 Not Found` | Policy not found, or schema name not found under the policy topic | | `500 Internal Server Error` | Unexpected server failure | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://guardian.hedera.com/docs/develop/guardian/workspace/policies/verifiable-credential-documents/dynamic-data-query/query-policy-data-documents.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.