> ## Documentation Index
> Fetch the complete documentation index at: https://humanity-eaeda8f6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Engine · Evaluate

> Evaluate a query against the authenticated user's credentials.
This endpoint allows declarative queries to check user claims.

<Callout>
  **SDK equivalent**

  ```ts theme={null}
  // Predicate query (boolean check)
  const result = await sdk.evaluateQuery({
    accessToken: token.accessToken,
    query: {
      check: { claim: 'identity.age', operator: '>=', value: 18 }
    }
  });

  // Projection query (data extraction)
  const data = await sdk.evaluateQuery({
    accessToken: token.accessToken,
    query: {
      projections: [{ claim: 'identity.email', lens: 'pluck' }]
    }
  });
  ```
</Callout>

The Query Engine allows declarative queries against user credentials. Use it for access control, eligibility checks, or data extraction without hardcoding preset names.

## Query Types

### Predicate Queries (Boolean Checks)

Return `true` or `false` based on credential values.

```json theme={null}
{
  "query": {
    "check": {
      "claim": "identity.age",
      "operator": ">=",
      "value": 18
    }
  }
}
```

**Available Operators:**

| Operator     | Description           | Example                                                                              |
| ------------ | --------------------- | ------------------------------------------------------------------------------------ |
| `==`         | Equals                | `{ "claim": "kyc.passed", "operator": "==", "value": true }`                         |
| `!=`         | Not equals            | `{ "claim": "identity.country", "operator": "!=", "value": "US" }`                   |
| `>`          | Greater than          | `{ "claim": "financial.net_worth", "operator": ">", "value": 100000 }`               |
| `>=`         | Greater than or equal | `{ "claim": "identity.age", "operator": ">=", "value": 21 }`                         |
| `<`          | Less than             | `{ "claim": "identity.age", "operator": "<", "value": 65 }`                          |
| `<=`         | Less than or equal    | `{ "claim": "financial.loan_balance", "operator": "<=", "value": 50000 }`            |
| `in`         | Value in array        | `{ "claim": "identity.country", "operator": "in", "value": ["US", "CA", "UK"] }`     |
| `notIn`      | Value not in array    | `{ "claim": "identity.country", "operator": "notIn", "value": ["RU", "CN"] }`        |
| `contains`   | Array contains value  | `{ "claim": "identity.social_accounts", "operator": "contains", "value": "github" }` |
| `isDefined`  | Claim exists          | `{ "claim": "kyc.document_number", "operator": "isDefined" }`                        |
| `startsWith` | String prefix         | `{ "claim": "identity.email", "operator": "startsWith", "value": "admin@" }`         |
| `matchRegex` | Regex match           | `{ "claim": "identity.phone", "operator": "matchRegex", "value": "^\\+1" }`          |

### Compound Policies

Combine multiple checks with logical operators:

```json theme={null}
{
  "query": {
    "policy": {
      "allOf": [
        { "check": { "claim": "identity.age", "operator": ">=", "value": 21 } },
        { "check": { "claim": "identity.country", "operator": "==", "value": "US" } }
      ]
    }
  }
}
```

**Logical Operators:**

| Operator | Description                           |
| -------- | ------------------------------------- |
| `allOf`  | AND - all conditions must pass        |
| `anyOf`  | OR - at least one condition must pass |
| `not`    | NOT - negate the result               |

**Nested Example:**

```json theme={null}
{
  "query": {
    "policy": {
      "allOf": [
        { "check": { "claim": "kyc.passed", "operator": "==", "value": true } },
        {
          "policy": {
            "anyOf": [
              { "check": { "claim": "financial.net_worth", "operator": ">=", "value": 1000000 } },
              { "check": { "claim": "financial.income", "operator": ">=", "value": 200000 } }
            ]
          }
        }
      ]
    }
  }
}
```

### Projection Queries (Data Extraction)

Extract values from credentials:

```json theme={null}
{
  "query": {
    "projections": [
      { "claim": "identity.email", "lens": "pluck" },
      { "claim": "identity.country", "lens": "pluck" }
    ]
  }
}
```

**Lens Operators:**

| Lens    | Description                     |
| ------- | ------------------------------- |
| `pluck` | Extract single value at path    |
| `pick`  | Extract subset of object fields |
| `at`    | Array index access              |

## Response Types

### Predicate Response

```json theme={null}
{
  "type": "predicate",
  "passed": true,
  "evaluatedAt": "2026-01-16T12:00:00.000Z",
  "evidence": {
    "claimsUsed": [
      { "path": "identity.age", "value": 25, "credentialId": "cred_123" }
    ],
    "checkResults": [
      {
        "claim": "identity.age",
        "operator": ">=",
        "expectedValue": 18,
        "actualValue": 25,
        "passed": true
      }
    ]
  },
  "expiresAt": "2026-02-16T12:00:00.000Z"
}
```

### Projection Response

```json theme={null}
{
  "type": "projection",
  "data": {
    "identity.email": "user@example.com",
    "identity.country": "US"
  },
  "evaluatedAt": "2026-01-16T12:00:00.000Z",
  "claimsUsed": [
    { "path": "identity.email", "value": "user@example.com" },
    { "path": "identity.country", "value": "US" }
  ],
  "expiresAt": "2026-02-16T12:00:00.000Z"
}
```

## Claim Paths

Claims are accessed using dot-notation paths based on credential categories:

| Category    | Example Claims                                                            |
| ----------- | ------------------------------------------------------------------------- |
| `identity`  | `identity.age`, `identity.email`, `identity.country_of_residence`         |
| `kyc`       | `kyc.passed`, `kyc.document_country`, `kyc.last_updated_at`               |
| `financial` | `financial.net_worth`, `financial.bank_balance`, `financial.loan_balance` |

## Scope Requirements

Query evaluation respects OAuth scopes. You can only query claims covered by the granted scopes. For example:

* `identity:read` - Access to basic identity claims
* `identity:date_of_birth` - Access to age-related claims
* `financial:net_worth` - Access to net worth data

See the [Scopes documentation](/concepts/scopes) for the full scope model.


## OpenAPI

````yaml api-reference/openapi.json post /queries/evaluate
openapi: 3.1.0
info:
  version: 0.1.0
  title: hp-public-dev-api-server
  description: NestJS CQRS + TDD base for Humanity Public Dev API
servers:
  - url: https://api.sandbox.humanity.org/v2
    description: Sandbox environment for development and testing
  - url: https://api.humanity.org/v2
    description: Production environment
security: []
tags: []
paths:
  /queries/evaluate:
    post:
      tags: []
      summary: Evaluate a query against the authenticated user's credentials
      description: |-
        Evaluate a query against the authenticated user's credentials.
        This endpoint allows declarative queries to check user claims.
      parameters: []
      requestBody:
        description: The query to evaluate
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryEvaluateRequest'
        required: true
      responses:
        '200':
          description: Query evaluation result
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PredicateEvaluateResponse'
                  - $ref: '#/components/schemas/ProjectionEvaluateResponse'
                discriminator:
                  propertyName: type
                  mapping:
                    predicate: '#/components/schemas/PredicateEvaluateResponse'
                    projection: '#/components/schemas/ProjectionEvaluateResponse'
components:
  schemas:
    QueryEvaluateRequest:
      type: object
      properties:
        query:
          oneOf:
            - type: object
              properties:
                check:
                  type: object
                  properties:
                    claim:
                      type: string
                    operator:
                      oneOf:
                        - const: '=='
                        - const: '!='
                        - const: '>'
                        - const: '>='
                        - const: <
                        - const: <=
                        - const: in
                        - const: notIn
                        - const: contains
                        - const: isDefined
                        - const: startsWith
                        - const: matchRegex
                    value: {}
                  required:
                    - claim
                    - operator
              required:
                - check
            - $ref: '#/components/schemas/__type.o2'
            - type: object
              properties:
                projections:
                  type: array
                  items:
                    type: object
                    properties:
                      claim:
                        type: string
                      lens:
                        oneOf:
                          - const: pluck
                          - const: pick
                          - const: at
                    required:
                      - claim
                      - lens
              required:
                - projections
          description: The query to evaluate. Can be a simple check or compound policy.
      required:
        - query
      description: Request body for query evaluation.
    PredicateEvaluateResponse:
      type: object
      properties:
        type:
          const: predicate
        passed:
          type: boolean
          description: Whether the query passed.
        evaluatedAt:
          type: string
          description: Timestamp when the query was evaluated.
        evidence:
          type: object
          properties:
            claimsUsed:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: string
                  value: {}
                  credentialId:
                    type: string
                  source:
                    type: string
                required:
                  - path
                  - value
            checkResults:
              type: array
              items:
                type: object
                properties:
                  claim:
                    type: string
                  operator:
                    type: string
                  expectedValue: {}
                  actualValue: {}
                  passed:
                    type: boolean
                required:
                  - claim
                  - operator
                  - expectedValue
                  - actualValue
                  - passed
          required:
            - claimsUsed
            - checkResults
          description: Evidence collected during evaluation.
        expiresAt:
          type: string
          description: Earliest credential expiry date (if any).
      required:
        - type
        - passed
        - evaluatedAt
        - evidence
      description: Response from predicate query evaluation.
    ProjectionEvaluateResponse:
      type: object
      properties:
        type:
          const: projection
        data:
          $ref: '#/components/schemas/Recordstringunknown'
          description: Extracted data from the projection query.
        evaluatedAt:
          type: string
          description: Timestamp when the query was evaluated.
        claimsUsed:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              value: {}
              credentialId:
                type: string
              source:
                type: string
            required:
              - path
              - value
          description: Claims used during evaluation.
        expiresAt:
          type: string
          description: Earliest credential expiry date (if any).
      required:
        - type
        - data
        - evaluatedAt
        - claimsUsed
      description: Response from projection query evaluation.
    __type.o2:
      type: object
      properties:
        policy:
          $ref: '#/components/schemas/PredicatePolicy'
      required:
        - policy
    Recordstringunknown:
      type: object
      properties: {}
      required: []
      description: Construct a type with a set of properties K of type T
      additionalProperties: {}
    PredicatePolicy:
      type: object
      properties:
        allOf:
          type: array
          items:
            oneOf:
              - type: object
                properties:
                  check:
                    type: object
                    properties:
                      claim:
                        type: string
                      operator:
                        oneOf:
                          - const: '=='
                          - const: '!='
                          - const: '>'
                          - const: '>='
                          - const: <
                          - const: <=
                          - const: in
                          - const: notIn
                          - const: contains
                          - const: isDefined
                          - const: startsWith
                          - const: matchRegex
                      value: {}
                    required:
                      - claim
                      - operator
                required:
                  - check
              - $ref: '#/components/schemas/__type.o2'
        anyOf:
          type: array
          items:
            oneOf:
              - type: object
                properties:
                  check:
                    type: object
                    properties:
                      claim:
                        type: string
                      operator:
                        oneOf:
                          - const: '=='
                          - const: '!='
                          - const: '>'
                          - const: '>='
                          - const: <
                          - const: <=
                          - const: in
                          - const: notIn
                          - const: contains
                          - const: isDefined
                          - const: startsWith
                          - const: matchRegex
                      value: {}
                    required:
                      - claim
                      - operator
                required:
                  - check
              - $ref: '#/components/schemas/__type.o2'
        not:
          oneOf:
            - type: object
              properties:
                check:
                  type: object
                  properties:
                    claim:
                      type: string
                    operator:
                      oneOf:
                        - const: '=='
                        - const: '!='
                        - const: '>'
                        - const: '>='
                        - const: <
                        - const: <=
                        - const: in
                        - const: notIn
                        - const: contains
                        - const: isDefined
                        - const: startsWith
                        - const: matchRegex
                    value: {}
                  required:
                    - claim
                    - operator
              required:
                - check
            - $ref: '#/components/schemas/__type.o2'
      required: []
      description: Forward declaration for recursive predicate policy schema.

````