> ## 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

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/docs/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="organizationId" type="string">
      Narrow to one organization.
    </ParamField>

    <ParamField body="documentId" type="string">
      Narrow to one document. Only applied when `organizationId` is also set. Sent alone, it is ignored and the query stays workspace-wide.
    </ParamField>

    <ParamField body="decision" type="string">
      Filter by decision value. One of `comment`, `resolve`, `approved`, `rejected`, `in_progress`, `agree`, `disagree`, `endorse`, `document_approved`, or `document_rejected`.
    </ParamField>

    <ParamField body="judgeType" type="string">
      `human` or `agent`.
    </ParamField>

    <ParamField body="contentType" type="string">
      Filter by the reviewed content type.
    </ParamField>

    <ParamField body="reviewerId" type="string">
      Filter by the deciding user.
    </ParamField>

    <ParamField body="annotationId" type="string">
      When set, returns the judgments for that one comment thread. Requires `organizationId`.
    </ParamField>

    <ParamField body="limit" type="integer">
      1 to 100. Defaults to 20.
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

#### List a reviewer's rejections

```JSON theme={null}
{
  "data": {
    "decision": "rejected",
    "reviewerId": "u_sarah",
    "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"
  }
}
```

<ResponseExample>
  ```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
    }
  }
  ```
</ResponseExample>