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

# Search Judgments

Use this API to run a semantic vector search over past **judgments**: the enriched records of the review decisions your users make in your app. Optional filters and retrieval-mode overrides let you narrow by decision, reviewer, content type, recency, or a single comment thread. This is distinct from [Search Knowledge Base](/docs/api-reference/rest-apis/v2/memory/knowledge/search), which searches the content of your ingested files.

# Endpoint

`POST https://api.velt.dev/v2/memory/search`

# 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="query" type="string" required>
      Non-empty search text. Ignored when `filters.annotationId` or `recencyDays` is set; those shortcut paths skip vector search.
    </ParamField>

    <ParamField body="embeddingType" type="string">
      `review` (default) searches the decision + reasoning. `content` searches the reviewed content itself.
    </ParamField>

    <ParamField body="scope" type="string">
      `document`, `organization`, or `apiKey`. Defaults from `organizationId`/`documentId` presence. Setting it explicitly also clamps the scope ids: `apiKey` ignores both `organizationId` and `documentId`; `organization` ignores `documentId`. Returns `INVALID_ARGUMENT` if `scope` is `organization` without `organizationId`, or `document` without both ids. When `filters.annotationId` is set, `document` scope needs only `organizationId`.
    </ParamField>

    <ParamField body="organizationId" type="string">
      Narrow to one organization. `orgId` is accepted as an alias.
    </ParamField>

    <ParamField body="documentId" type="string">
      Narrow to one document. Only applied when `organizationId` is also set. Without `organizationId`, `documentId` is ignored and the search runs across the whole workspace. `docId` is accepted as an alias.
    </ParamField>

    <ParamField body="limit" type="integer">
      1 to 50. Defaults to 10.
    </ParamField>

    <ParamField body="filters" type="object">
      `{ decision?, judgeType?, contentType?, reviewerId?, annotationId?, dateRange?, excludeDocumentIds? }`. `decision` filters by decision value: `comment`, `resolve`, `approved`, `rejected`, `in_progress`, `agree`, `disagree`, `endorse`, `document_approved`, or `document_rejected`. `judgeType` is `human` or `agent`. `dateRange` is `{ start, end }` as either ISO-8601 strings or epoch milliseconds; `start` must not be after `end`. `annotationId` requires `organizationId` and reads that one comment thread directly, oldest first.

      Filters are applied after retrieval, over the top matches the search returns (up to `limit * 3` records). A selective filter can return fewer results than `limit`, or none, even when matching judgments exist. For exhaustive metadata-only lookups, use [Query Judgments](/docs/api-reference/rest-apis/v2/memory/judgments/query).
    </ParamField>

    <ParamField body="filters.excludeDocumentIds" type="string[]">
      Leave out judgments belonging to specific documents. 1 to 20 ids, each non-empty. An empty array is rejected. Pass either the document id you sent to Velt or the id a Memory response returned; both forms match.

      A record is only excluded when it carries a document id. Records with no document id are kept.
    </ParamField>

    <ParamField body="recencyDays" type="integer">
      1 to 365. Recency-true mode: skips vector search and returns activity from the last `recencyDays` complete UTC days. The window ends at the start of the current UTC day, so activity later in the current UTC day is not returned. Overrides `filters.dateRange`. If `filters.annotationId` is also set, the annotation shortcut wins and `recencyDays` is ignored.
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

#### Search rejected decisions

```JSON theme={null}
{
  "data": {
    "query": "marketing copy with unsupported medical claims",
    "limit": 5,
    "filters": { "decision": "rejected" }
  }
}
```

#### Read one comment thread chronologically

```JSON theme={null}
{
  "data": {
    "query": "thread summary",
    "organizationId": "org_eu",
    "filters": { "annotationId": "annotation_123" }
  }
}
```

#### Last week's activity (recency-true mode)

```JSON theme={null}
{
  "data": {
    "query": "recent activity",
    "recencyDays": 7
  }
}
```

# Response

Each result includes the reasoning, decision, confidence, who decided (`actionUser`), and a `similarity` score (`1.0` for the annotation and recency shortcut paths). `totalInScope` is the number of records returned in `results[]` after filtering, so it never exceeds `limit`; it is not a count of every matching judgment in the workspace. `searchLatencyMs` reports the search time. `agent` is always present: `null` for a human decision, otherwise `{ agentId, agentType, executionId, agentFields }`. To retrieve only agent-originated judgments, set `filters.judgeType` to `agent`.

#### Success Response

```JSON theme={null}
{
  "result": {
    "results": [
      {
        "recordId": "act_8f3...",
        "reasoning": "Claim 'clinically proven' lacks a citation.",
        "decision": "rejected",
        "confidence": 0.92,
        "actionUser": { "name": "Sarah Lee" },
        "createdAt": 1731432000000,
        "similarity": 0.87,
        "scope": "organization",
        "agent": null
      }
    ],
    "totalInScope": 1,
    "searchLatencyMs": 142
  }
}
```

#### Failure Response

On a validation error, `details.issues` lists every failing field, not just the one in `message`.

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT",
    "details": {
      "issues": [
        { "code": "invalid_type", "path": ["query"], "message": "query is required" }
      ]
    }
  }
}
```

<ResponseExample>
  ```js theme={null}
  {
    "result": {
      "results": [
        {
          "recordId": "act_8f3...",
          "reasoning": "Claim 'clinically proven' lacks a citation.",
          "decision": "rejected",
          "confidence": 0.92,
          "actionUser": { "name": "Sarah Lee" },
          "createdAt": 1731432000000,
          "similarity": 0.87,
          "scope": "organization",
          "agent": null
        }
      ],
      "totalInScope": 1,
      "searchLatencyMs": 142
    }
  }
  ```
</ResponseExample>