Search Judgments
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>",
"limit": 123,
"filters": {},
"filters.excludeDocumentIds": [
"<string>"
],
"recencyDays": 123
}
}
'import requests
url = "https://api.velt.dev/v2/memory/search"
payload = { "data": {
"query": "<string>",
"embeddingType": "<string>",
"scope": "<string>",
"organizationId": "<string>",
"documentId": "<string>",
"limit": 123,
"filters": {},
"filters.excludeDocumentIds": ["<string>"],
"recencyDays": 123
} }
headers = {
"x-velt-api-key": "<x-velt-api-key>",
"x-velt-auth-token": "<x-velt-auth-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-velt-api-key': '<x-velt-api-key>',
'x-velt-auth-token': '<x-velt-auth-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {
query: '<string>',
embeddingType: '<string>',
scope: '<string>',
organizationId: '<string>',
documentId: '<string>',
limit: 123,
filters: {},
'filters.excludeDocumentIds': ['<string>'],
recencyDays: 123
}
})
};
fetch('https://api.velt.dev/v2/memory/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.velt.dev/v2/memory/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'query' => '<string>',
'embeddingType' => '<string>',
'scope' => '<string>',
'organizationId' => '<string>',
'documentId' => '<string>',
'limit' => 123,
'filters' => [
],
'filters.excludeDocumentIds' => [
'<string>'
],
'recencyDays' => 123
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-velt-api-key: <x-velt-api-key>",
"x-velt-auth-token: <x-velt-auth-token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.velt.dev/v2/memory/search"
payload := strings.NewReader("{\n \"data\": {\n \"query\": \"<string>\",\n \"embeddingType\": \"<string>\",\n \"scope\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"limit\": 123,\n \"filters\": {},\n \"filters.excludeDocumentIds\": [\n \"<string>\"\n ],\n \"recencyDays\": 123\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/memory/search")
.header("x-velt-api-key", "<x-velt-api-key>")
.header("x-velt-auth-token", "<x-velt-auth-token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"query\": \"<string>\",\n \"embeddingType\": \"<string>\",\n \"scope\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"limit\": 123,\n \"filters\": {},\n \"filters.excludeDocumentIds\": [\n \"<string>\"\n ],\n \"recencyDays\": 123\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/memory/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"query\": \"<string>\",\n \"embeddingType\": \"<string>\",\n \"scope\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"limit\": 123,\n \"filters\": {},\n \"filters.excludeDocumentIds\": [\n \"<string>\"\n ],\n \"recencyDays\": 123\n }\n}"
response = http.request(request)
puts response.read_body{
"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
}
}
Search and Ask
Search Judgments
POST
/
v2
/
memory
/
search
Search Judgments
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>",
"limit": 123,
"filters": {},
"filters.excludeDocumentIds": [
"<string>"
],
"recencyDays": 123
}
}
'import requests
url = "https://api.velt.dev/v2/memory/search"
payload = { "data": {
"query": "<string>",
"embeddingType": "<string>",
"scope": "<string>",
"organizationId": "<string>",
"documentId": "<string>",
"limit": 123,
"filters": {},
"filters.excludeDocumentIds": ["<string>"],
"recencyDays": 123
} }
headers = {
"x-velt-api-key": "<x-velt-api-key>",
"x-velt-auth-token": "<x-velt-auth-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-velt-api-key': '<x-velt-api-key>',
'x-velt-auth-token': '<x-velt-auth-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {
query: '<string>',
embeddingType: '<string>',
scope: '<string>',
organizationId: '<string>',
documentId: '<string>',
limit: 123,
filters: {},
'filters.excludeDocumentIds': ['<string>'],
recencyDays: 123
}
})
};
fetch('https://api.velt.dev/v2/memory/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.velt.dev/v2/memory/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'query' => '<string>',
'embeddingType' => '<string>',
'scope' => '<string>',
'organizationId' => '<string>',
'documentId' => '<string>',
'limit' => 123,
'filters' => [
],
'filters.excludeDocumentIds' => [
'<string>'
],
'recencyDays' => 123
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-velt-api-key: <x-velt-api-key>",
"x-velt-auth-token: <x-velt-auth-token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.velt.dev/v2/memory/search"
payload := strings.NewReader("{\n \"data\": {\n \"query\": \"<string>\",\n \"embeddingType\": \"<string>\",\n \"scope\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"limit\": 123,\n \"filters\": {},\n \"filters.excludeDocumentIds\": [\n \"<string>\"\n ],\n \"recencyDays\": 123\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/memory/search")
.header("x-velt-api-key", "<x-velt-api-key>")
.header("x-velt-auth-token", "<x-velt-auth-token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"query\": \"<string>\",\n \"embeddingType\": \"<string>\",\n \"scope\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"limit\": 123,\n \"filters\": {},\n \"filters.excludeDocumentIds\": [\n \"<string>\"\n ],\n \"recencyDays\": 123\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/memory/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"query\": \"<string>\",\n \"embeddingType\": \"<string>\",\n \"scope\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"limit\": 123,\n \"filters\": {},\n \"filters.excludeDocumentIds\": [\n \"<string>\"\n ],\n \"recencyDays\": 123\n }\n}"
response = http.request(request)
puts response.read_body{
"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
string
required
Your API key.
string
required
Your Auth Token.
Body
Params
object
required
Show properties
Show properties
string
required
Non-empty search text. Ignored when
filters.annotationId or recencyDays is set; those shortcut paths skip vector search.string
review (default) searches the decision + reasoning. content searches the reviewed content itself.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.string
Narrow to one organization.
orgId is accepted as an alias.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.integer
1 to 50. Defaults to 10.
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.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.
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" }
}
}
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
}
}
Was this page helpful?
⌘I

