Search Judgments

POST /v2/memory/search

Search Judgments

cURL

curl --request POST \
  --url https://api.velt.dev/v2/memory/search \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "query": "<string>",
    "embeddingType": "<string>",
    "scope": "<string>",
    "organizationId": "<string>",
    "documentId": "<string>",
    "documentIds": [
      "<string>"
    ],
    "limit": 123,
    "filters": {},
    "filters.excludeDocumentIds": [
      "<string>"
    ],
    "recencyDays": 123
  }
}
'

{
  "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
  }
}

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

​

Body

​

Params

data · object · required

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

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

{
  "data": {
    "query": "marketing copy with unsupported medical claims",
    "limit": 5,
    "filters": { "decision": "rejected" }
  }
}

​

Search across a set of documents

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

​

Read one comment thread chronologically

{
  "data": {
    "query": "thread summary",
    "organizationId": "org_eu",
    "filters": { "annotationId": "annotation_123" }
  }
}

​

Last week’s activity (recency-true mode)

{
  "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

{
  "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.

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

{
  "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
  }
}