> ## 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](https://velt.dev/docs/api-reference/rest-apis/v2/memory/knowledge/search.md), which searches the content of your ingested files.

# Endpoint

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

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

**query** `string` *required*

Non-empty search text. Ignored when `filters.annotationId` or `recencyDays` is set; those shortcut paths skip vector search.

**embeddingType** `string`

`review` (default) searches the decision + reasoning. `content` searches the reviewed content itself.

**scope** `string`

`document`, `organization`, or `apiKey`. Defaults from `organizationId`/`documentId`/`documentIds` presence. Setting it explicitly also clamps the scope ids: `apiKey` ignores `organizationId`, `documentId`, and `documentIds`; `organization` ignores `documentId` and `documentIds`. Returns `INVALID_ARGUMENT` if `scope` is `organization` without `organizationId`, or `document` without `organizationId` plus either `documentId` or `documentIds`. When `filters.annotationId` is set, `document` scope needs only `organizationId`.

**organizationId** `string`

Narrow to one organization. `orgId` is accepted as an alias.

**documentId** `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.

**documentIds** `string[]`

Narrow to a set of documents. 1 to 25 document ids, each non-empty. Use it to search several documents at once, instead of one document or the whole workspace.

Only applied when `organizationId` is also set. Without `organizationId`, `documentIds` is ignored and the search runs across the whole workspace, just as a lone `documentId` is. When you send both `documentId` and `documentIds`, `documentId` wins and the list is ignored.

Ids are trimmed and deduplicated on the server. The 25 cap applies to the list you send, before deduplication, so 26 ids are rejected even when two of them repeat. An empty array, more than 25 ids, or an empty id returns `INVALID_ARGUMENT`.

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

**limit** `integer`

1 to 50. Defaults to 10.

**filters** `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](https://velt.dev/docs/api-reference/rest-apis/v2/memory/judgments/query.md).

**filters.excludeDocumentIds** `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.

**recencyDays** `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.

## **Example Requests**

#### Search rejected decisions

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

#### Search across a set of documents

```JSON theme={null}
{
  "data": {
    "query": "accessibility labels on form inputs",
    "organizationId": "org_eu",
    "documentIds": ["checkout-flow-v3", "homepage-redesign", "pricing-page"]
  }
}
```

#### 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" }
      ]
    }
  }
}
```

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


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