> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Judgments

Use this API to list judgments by metadata only, with no semantic search. Use it when you want to enumerate decisions by decision value, reviewer, content type, or thread instead of ranking by similarity.

# Endpoint

`POST https://api.velt.dev/v2/memory/judgments/query`

# Headers

**x-velt-api-key** `string` *required*

Your API key.

**x-velt-auth-token** `string` *required*

Your [Auth Token](https://velt.dev/docs/security/auth-tokens.md).

# Body

#### Params

**data** `object` *required*

**properties**

**organizationId** `string`

Narrow to one organization.

**documentId** `string`

Narrow to one document. Only applied when `organizationId` is also set. Sent alone, it is ignored and the query stays workspace-wide.

**documentIds** `string[]`

Narrow to a set of documents. 1 to 25 document ids, each non-empty. Same rules as on [Search Judgments](https://velt.dev/docs/api-reference/rest-apis/v2/memory/search.md): it needs `organizationId`, `documentId` wins when you send both, ids are trimmed and deduplicated on the server, and the 25 cap applies to the list you send, before deduplication.

`annotationId` ignores this field, because an annotation belongs to one document.

**decision** `string`

Filter by decision value. One of `comment`, `resolve`, `approved`, `rejected`, `in_progress`, `agree`, `disagree`, `endorse`, `document_approved`, or `document_rejected`.

**judgeType** `string`

`human` or `agent`.

**contentType** `string`

Filter by the reviewed content type.

**reviewerId** `string`

Filter by the deciding user.

**annotationId** `string`

When set, returns the judgments for that one comment thread. Requires `organizationId`.

**limit** `integer`

1 to 100. Defaults to 20.

## **Example Requests**

#### List a reviewer's rejections

```JSON theme={null}
{
  "data": {
    "decision": "rejected",
    "reviewerId": "u_sarah",
    "limit": 20
  }
}
```

#### List rejections across a set of documents

```JSON theme={null}
{
  "data": {
    "organizationId": "org_eu",
    "documentIds": ["checkout-flow-v3", "homepage-redesign"],
    "decision": "rejected",
    "limit": 20
  }
}
```

# Response

Each record includes the reasoning, decision, confidence, `judgeType`, `contentType`, who decided (`actionUser`), timestamps, and scope ids. An `agent` block is present when an AI agent decided.

`organizationId` and `documentId` on each record are Velt's internal ids, not the ids you passed in. Results are newest-first. When you set `annotationId`, the newest `limit` records for that thread come back in chronological order, oldest first. `total` is the number of records in `results` after filtering. It never exceeds `limit`, and this endpoint does not report a match count beyond the returned page.

#### Success Response

```JSON theme={null}
{
  "result": {
    "results": [
      {
        "recordId": "act_8f3...",
        "reasoning": "Approved after fixing the citation.",
        "decision": "approved",
        "confidence": 0.81,
        "judgeType": "human",
        "contentType": "marketing-copy",
        "actionUser": { "userId": "u_sarah", "name": "Sarah Lee", "email": "sarah@acme.com" },
        "createdAt": 1731432000000,
        "organizationId": "1873625104",
        "documentId": "992310445",
        "agent": null
      }
    ],
    "total": 1
  }
}
```

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

```js theme={null}
{
  "result": {
    "results": [
      {
        "recordId": "act_8f3...",
        "reasoning": "Approved after fixing the citation.",
        "decision": "approved",
        "confidence": 0.81,
        "judgeType": "human",
        "contentType": "marketing-copy",
        "actionUser": { "userId": "u_sarah", "name": "Sarah Lee", "email": "sarah@acme.com" },
        "createdAt": 1731432000000,
        "organizationId": "1873625104",
        "documentId": "992310445",
        "agent": null
      }
    ],
    "total": 1
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.