feat: Provide Dynamic Read API Endpoint for Guardian Policy Data #5796

[gayanath8]

Issue Labels

#5796

Requirements

• Provide a separate, dynamic API endpoint that allows external consumers to read data committed by Guardian policies.
• The endpoint should execute queries against MongoDB and support dynamic filter fields provided by the API caller.
• API users should be able to filter by policy IDs, schema names, and system field names.
• Users can discover available policy IDs and schema names via the existing /policies and /schema endpoints.
• All system field names that can be used for filtering must be documented so external users can reference them.
• This endpoint addresses read-only data access concerns.

Summary of Changes

• GET /policy-data/query — Read-only endpoint that returns paginated Verifiable Credential (VC) documents committed by a published policy. The caller supplies a policy ID, schema name and optional field-level filters; the service resolves the schema IRI internally, applies safe MongoDB operator translation, and returns matching documents with pagination metadata.

End User should have JWT Bearer token present and valid signature and hold one of POLICIES_POLICY_READ, POLICIES_POLICY_EXECUTE, POLICIES_POLICY_AUDIT, POLICIES_POLICY_MANAGE

The endpoint does not check whether the caller's DID is registered as a participant in the policy. Any authenticated user with the correct platform permission can query any published policy.

The endpoint does not read permissions from documentsSourceAddon blocks. It returns all documents matching the filter. Callers who need own-only results must supply an owner filter themselves.

Revoked documents are included unless filtered out with hederaStatus ne REVOKE.

Query Parameters

Parameter	Required	Type	Description
policyId	yes	string	MongoDB ObjectId of the published policy
schemaName	yes	string	Schema name as registered in the policy (e.g. Installer Activity Report)
filters	no	JSON string	Field-level filter map — see Filter Fields section
sort	no	string	Field to sort by. Prefix - for descending (e.g. -createDate)
page	no	number	1-based page number (default: 1)
pageSize	no	number	Results per page, max 200 (default: 20)

Filter Options

1. System Fields (direct MongoDB document properties)

Field	Type	Notes
owner	string	DID of the document owner
assignedTo	string	DID assigned to
assignedToGroup	string	Group assigned to
group	string	User group that created the doc
hederaStatus	string	NEW | ISSUE | REVOKE | SUSPEND | RESUME | FAILED
signature	number	Document signature numeric code
type	string	Internal block document type
draft	boolean	Whether document is in draft
edited	boolean	Whether this version supersedes an earlier one
disconnected	boolean	Disconnected from policy
policyId	string	MongoDB ObjectId of owning policy
schema	string	Schema IRI (e.g. #MySchema)
tag	string	Policy block tag that produced the document
messageId	string	HCS message ID
topicId	string	Hedera topic ID
hash	string	Document content hash
createDate	string	ISO 8601 date
updateDate	string	ISO 8601 date

2. Option Fields

Any option.* sub-field stored by the policy engine.

e.g. option.status (set by sendToGuardianBlock options array)

3. Document Credential Fields

Any document.credentialSubject[n].fieldX path cached by the grid columns.

e.g. document.credentialSubject[0].field3

Bracket notation [0] and dot notation .0. are both accepted.

Filter Operators

Token	MongoDB	Example
contains	$regex	{"op": "contains", "value": "Voluptatem"}
eq	$eq	{"op": "eq", "value": "Pass"}
ne	$ne	{"op": "ne", "value": "Fail"}
in	$in	{"op": "in", "value": ["Pass", "Conditional"]}
nin	$nin	{"op": "nin", "value": ["Germany"]}
gt	$gt	{"op": "gt", "value": 5000}
gte	$gte	{"op": "gte", "value": 80}
lt	$lt	{"op": "lt", "value": 100}
lte	$lte	{"op": "lte", "value": 70}

1. No Filters Defaults

2. Custom Page and Size

3. Sort By Filed 3 (Number Field)

Screen.Recording.2026-04-28.153228.mp4

4. Different Filters

5. Multiple Filters

Validations

(Page Size Set 200 Max)

(Page default to 1 when missing)

[gayanath8]

Hi @Pyatakov
Regarding the two concerns raised on permission and data querying we would like to get your feedback, also here are our proposed methods on those
As for the permission concern we can apply that caller must be a valid assigned user or owner of the particular policy. Additionally, we can enforce role-based access if the caller has no active role within the policy, the request will be rejected.
For data querying part we can Limit the number of filter entries per request (e.g. max 5) to prevent wide AND queries and also apart from can apply a standard API-gateway-level rate limit on the endpoint per user
Also, If you would like to allow only a particular set of fields, please mention them and we will restrict the endpoint accordingly