Appearance
Search API
Search across dialogues, messages, and memories by meaning - not just keywords.
Overview
The Search API lets you find conversation data using natural language. Unlike keyword matching, search understands meaning and context, returning relevant results even when exact words don't match.
Key capabilities:
- Understands intent and meaning, not just keywords
- Search across messages, dialogues, or memories
- Automatically scoped to your project
- Returns full object data, not just IDs
- Results ranked by relevance
- Filter by namespace and tags
INFO
Newly created messages and memories are vectorized asynchronously and typically searchable within a few seconds.
Search
Perform semantic search across your data.
Endpoint
http
POST /searchAuthentication
Bearer token (via Authorization header)
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Natural language search query |
object | string | Yes | Type to search: "message", "dialogue", or "memory" |
limit | number | No | Maximum results to return (default varies by provider) |
namespace | string | No | Filter results by namespace |
tags | string[] | No | Filter results by tags |
Response
typescript
{
items: Array<Message | Dialogue | Memory>;
}Response includes full object details based on the object type:
For object="message":
typescript
{
items: [
{
id: string;
dialogueId: string;
role: string;
content: string; // Full message content
contentLength: number;
created: string;
metadata: object;
tags: string[];
}
]
}For object="dialogue":
typescript
{
items: [
{
id: string;
projectId: string;
totalMessages: number;
status: string;
created: string;
modified: string;
tags: string[];
metadata: object;
}
]
}For object="memory":
typescript
{
items: [
{
id: string;
namespace?: string;
label?: string;
description?: string;
value: any;
tags: string[];
metadata: object;
created: string;
modified: string;
}
]
}Behavior
- Searches by meaning, not just keywords
- Results automatically scoped to your project
- Returns full objects with all fields (not just IDs)
- Relevance-based ranking (most relevant first)
- Search types:
- message: Searches message content across all dialogues
- dialogue: Finds dialogues based on their message content
- memory: Searches memory values by meaning
Search Types Explained
Message Search
Searches the content of all messages across your dialogues:
typescript
// Query: "How do I reset my password?"
// Finds messages about password resets, account recovery, etc.Returns matching messages with their full content and metadata.
Dialogue Search
Searches message content but returns the containing dialogues:
typescript
// Query: "billing issue"
// Finds dialogues where billing problems were discussedReturns dialogue metadata (not the messages themselves). Useful for finding conversations about specific topics.
Memory Search
Searches stored memories semantically:
typescript
// Query: "user preferences"
// Finds memories about settings, preferences, and user choicesReturns memories that semantically match your query.
Use Cases
- Find similar conversations: Locate past discussions on a topic
- Knowledge retrieval: Search for specific information across all messages
- Duplicate detection: Find similar customer inquiries
- Context building: Retrieve relevant memories for LLM context
- Support ticket routing: Find related past issues
- FAQ matching: Find answers from previous conversations
Errors
| Status | Error Code | Description |
|---|---|---|
| 400 | MISSING_PARAMETER | Missing required query or object parameter |
| 400 | INVALID_PARAMETER | Invalid object type (must be message, dialogue, or memory) |
| 401 | N/A | Unauthorized - invalid or missing API key |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests - retry with backoff |
| 500 | INTERNAL_ERROR | Server error - contact support with requestId |
See Error Handling for complete error reference.
Examples
bash
curl -X POST https://api.dialoguedb.com/api/v1/search \
-H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "refund policy", "object": "message", "limit": 5}'bash
curl -X POST https://api.dialoguedb.com/api/v1/search \
-H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "billing issue", "object": "dialogue"}'bash
curl -X POST https://api.dialoguedb.com/api/v1/search \
-H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "user preferences", "object": "memory", "namespace": "user_789"}'typescript
const response = await fetch(
'https://api.dialoguedb.com/api/v1/search',
{
method: 'POST',
headers: {
'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: 'how to cancel subscription',
object: 'message',
limit: 10
})
}
);
const { items } = await response.json();
items.forEach(message => {
console.log(`Found in dialogue ${message.dialogueId}: ${message.content}`);
});typescript
const response = await fetch(
'https://api.dialoguedb.com/api/v1/search',
{
method: 'POST',
headers: {
'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: 'technical support request',
object: 'dialogue',
limit: 20
})
}
);
const { items } = await response.json();
console.log(`Found ${items.length} relevant dialogues`);typescript
import { DialogueDB } from 'dialogue-db';
const db = new DialogueDB({ apiKey: 'DIALOGUE_DB_API_KEY' });
const results = await db.searchMessages('product recommendations', {
limit: 5
});
console.log(`Found ${results.length} relevant messages`);typescript
import { DialogueDB } from 'dialogue-db';
const db = new DialogueDB({ apiKey: 'DIALOGUE_DB_API_KEY' });
const results = await db.searchMemories('dietary restrictions', {
namespace: 'user_456'
});
results.forEach(memory => {
console.log(`${memory.label}: ${memory.value}`);
});python
import requests
response = requests.post(
"https://api.dialoguedb.com/api/v1/search",
headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
json={
"query": "how to cancel subscription",
"object": "message",
"limit": 10
}
)
results = response.json()
for message in results["items"]:
print(f"Found in dialogue {message['dialogueId']}: {message['content']}")python
import requests
response = requests.post(
"https://api.dialoguedb.com/api/v1/search",
headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
json={
"query": "user preferences",
"object": "memory",
"namespace": "user_789"
}
)
results = response.json()
for memory in results["items"]:
print(f"{memory['label']}: {memory['value']}")Search Patterns
Using search in code
The examples below use the low-level search() function from the direct API. Most developers should use the SDK class methods instead:
typescript
import { DialogueDB } from 'dialogue-db';
const db = new DialogueDB({ apiKey: process.env.DIALOGUE_DB_API_KEY });
const dialogues = await db.searchDialogues('refund request');
const messages = await db.searchMessages('order tracking', { namespace: 'user_456' });
const memories = await db.searchMemories('preferences', { namespace: 'user_456' });To use the low-level API directly:
typescript
import { api, createConfig } from 'dialogue-db';
createConfig({ apiKey: process.env.DIALOGUE_DB_API_KEY });
const { items } = await api.search({ query: 'hello', object: 'message' });Finding Similar Conversations
Locate past conversations about specific topics:
bash
curl -X POST https://api.dialoguedb.com/api/v1/search \
-H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "refund or return request", "object": "dialogue", "limit": 20}'typescript
const response = await fetch(
'https://api.dialoguedb.com/api/v1/search',
{
method: 'POST',
headers: {
'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: 'refund or return request',
object: 'dialogue',
limit: 20
})
}
);
const { items: dialogues } = await response.json();
// Get details of the most relevant dialogue
const topDialogue = dialogues[0];
console.log(`Top dialogue: ${topDialogue.id}, messages: ${topDialogue.totalMessages}`);python
import requests
response = requests.post(
"https://api.dialoguedb.com/api/v1/search",
headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
json={
"query": "refund or return request",
"object": "dialogue",
"limit": 20
}
)
dialogues = response.json()["items"]
# Get details of the most relevant dialogue
top_dialogue = dialogues[0]
print(f"Top dialogue: {top_dialogue['id']}, messages: {top_dialogue['totalMessages']}")typescript
import { DialogueDB } from 'dialogue-db';
const db = new DialogueDB({ apiKey: 'DIALOGUE_DB_API_KEY' });
const dialogues = await db.searchDialogues('refund or return request', {
limit: 20
});
// Get details of the most relevant dialogue
const topDialogue = dialogues[0];
console.log(`Top dialogue: ${topDialogue.id}, messages: ${topDialogue.totalMessages}`);Knowledge Retrieval for Context
Build LLM context from relevant past information:
bash
# Search for relevant messages
curl -X POST https://api.dialoguedb.com/api/v1/search \
-H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "How do I upgrade my plan?", "object": "message", "limit": 5}'
# Search for relevant memories
curl -X POST https://api.dialoguedb.com/api/v1/search \
-H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "How do I upgrade my plan?", "object": "memory", "limit": 3}'typescript
async function buildContextForQuery(userQuery: string) {
const headers = {
'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
'Content-Type': 'application/json'
};
// Search for relevant messages and memories in parallel
const [messageResponse, memoryResponse] = await Promise.all([
fetch('https://api.dialoguedb.com/api/v1/search', {
method: 'POST',
headers,
body: JSON.stringify({ query: userQuery, object: 'message', limit: 5 })
}),
fetch('https://api.dialoguedb.com/api/v1/search', {
method: 'POST',
headers,
body: JSON.stringify({ query: userQuery, object: 'memory', limit: 3 })
})
]);
const messageResults = await messageResponse.json();
const memoryResults = await memoryResponse.json();
return {
relevantMessages: messageResults.items,
relevantMemories: memoryResults.items
};
}python
import requests
def build_context_for_query(user_query: str) -> dict:
headers = {"Authorization": "Bearer DIALOGUE_DB_API_KEY"}
url = "https://api.dialoguedb.com/api/v1/search"
# Search for relevant messages
message_results = requests.post(
url,
headers=headers,
json={"query": user_query, "object": "message", "limit": 5}
).json()
# Search for relevant memories
memory_results = requests.post(
url,
headers=headers,
json={"query": user_query, "object": "memory", "limit": 3}
).json()
return {
"relevant_messages": message_results["items"],
"relevant_memories": memory_results["items"]
}typescript
import { DialogueDB } from 'dialogue-db';
const db = new DialogueDB({ apiKey: 'DIALOGUE_DB_API_KEY' });
async function buildContextForQuery(userQuery: string) {
// Search for relevant messages and memories in parallel
const [messages, memories] = await Promise.all([
db.searchMessages(userQuery, { limit: 5 }),
db.searchMemories(userQuery, { limit: 3 })
]);
return {
relevantMessages: messages,
relevantMemories: memories
};
}Duplicate Detection
Find similar existing inquiries before creating new dialogue:
bash
curl -X POST https://api.dialoguedb.com/api/v1/search \
-H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "I was charged twice for my order", "object": "message", "limit": 3}'typescript
async function checkForDuplicates(newInquiry: string) {
const response = await fetch(
'https://api.dialoguedb.com/api/v1/search',
{
method: 'POST',
headers: {
'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: newInquiry,
object: 'message',
limit: 3
})
}
);
const results = await response.json();
if (results.items.length > 0) {
console.log('Found similar past inquiries:');
results.items.forEach(msg => {
console.log(`- Dialogue ${msg.dialogueId}: "${msg.content}"`);
});
}
return results.items;
}python
import requests
def check_for_duplicates(new_inquiry: str) -> list:
response = requests.post(
"https://api.dialoguedb.com/api/v1/search",
headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
json={
"query": new_inquiry,
"object": "message",
"limit": 3
}
)
results = response.json()
if results["items"]:
print("Found similar past inquiries:")
for msg in results["items"]:
print(f"- Dialogue {msg['dialogueId']}: \"{msg['content']}\"")
return results["items"]typescript
import { DialogueDB } from 'dialogue-db';
const db = new DialogueDB({ apiKey: 'DIALOGUE_DB_API_KEY' });
async function checkForDuplicates(newInquiry: string) {
const results = await db.searchMessages(newInquiry, { limit: 3 });
if (results.length > 0) {
console.log('Found similar past inquiries:');
results.forEach(msg => {
console.log(`- Dialogue ${msg.dialogueId}: "${msg.content}"`);
});
}
return results;
}User-Specific Memory Search
Search memories for a specific user:
bash
curl -X POST https://api.dialoguedb.com/api/v1/search \
-H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "communication preferences", "object": "memory", "namespace": "user_789", "limit": 10}'typescript
const response = await fetch(
'https://api.dialoguedb.com/api/v1/search',
{
method: 'POST',
headers: {
'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: 'communication preferences',
object: 'memory',
namespace: 'user_789',
limit: 10
})
}
);
const results = await response.json();
// Results only include memories from this namespace
console.log('User preferences:', results.items);python
import requests
response = requests.post(
"https://api.dialoguedb.com/api/v1/search",
headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
json={
"query": "communication preferences",
"object": "memory",
"namespace": "user_789",
"limit": 10
}
)
results = response.json()
# Results only include memories from this namespace
print("User preferences:", results["items"])typescript
import { DialogueDB } from 'dialogue-db';
const db = new DialogueDB({ apiKey: 'DIALOGUE_DB_API_KEY' });
const results = await db.searchMemories('communication preferences', {
namespace: 'user_789',
limit: 10
});
// Results only include memories from this namespace
console.log('User preferences:', results);Tag-Based Filtering
Combine semantic search with tag filtering:
bash
curl -X POST https://api.dialoguedb.com/api/v1/search \
-H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "payment issue", "object": "message", "tags": ["support", "billing"], "limit": 10}'typescript
const response = await fetch(
'https://api.dialoguedb.com/api/v1/search',
{
method: 'POST',
headers: {
'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: 'payment issue',
object: 'message',
tags: ['support', 'billing'],
limit: 10
})
}
);
const results = await response.json();
console.log(`Found ${results.items.length} tagged messages`);python
import requests
response = requests.post(
"https://api.dialoguedb.com/api/v1/search",
headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
json={
"query": "payment issue",
"object": "message",
"tags": ["support", "billing"],
"limit": 10
}
)
results = response.json()
print(f"Found {len(results['items'])} tagged messages")typescript
import { DialogueDB } from 'dialogue-db';
const db = new DialogueDB({ apiKey: 'DIALOGUE_DB_API_KEY' });
const results = await db.searchMessages('payment issue', {
tags: ['support', 'billing'],
limit: 10
});
console.log(`Found ${results.length} tagged messages`);Best Practices
Query Formulation
Write queries as natural language, not keywords:
typescript
// Good: Natural language
const results = await db.searchMessages(
'How do customers typically cancel their subscriptions?'
);
// Also good: Descriptive phrase
const results = await db.searchMessages('subscription cancellation process');
// Works but less optimal: Single keywords
const results = await db.searchMessages('cancel');Limit Results Appropriately
Request only what you need:
typescript
// For display to users
const results = await db.searchDialogues('shipping delays', {
limit: 10 // Top 10 most relevant
});
// For LLM context building
const context = await db.searchMessages(userQuery, {
limit: 5 // Just enough for context
});Namespace for Multi-Tenancy
Use namespace to isolate searches by user or organization:
bash
# Search only within this user's data
curl -X POST https://api.dialoguedb.com/api/v1/search \
-H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "preferences and settings", "object": "memory", "namespace": "user_123"}'
# Or search across organization
curl -X POST https://api.dialoguedb.com/api/v1/search \
-H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "company policies", "object": "memory", "namespace": "org_456"}'typescript
const headers = {
'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
'Content-Type': 'application/json'
};
// Search only within this user's data
const userResponse = await fetch(
'https://api.dialoguedb.com/api/v1/search',
{
method: 'POST',
headers,
body: JSON.stringify({
query: 'preferences and settings',
object: 'memory',
namespace: `user_${userId}`
})
}
);
const userResults = await userResponse.json();
// Or search across organization
const orgResponse = await fetch(
'https://api.dialoguedb.com/api/v1/search',
{
method: 'POST',
headers,
body: JSON.stringify({
query: 'company policies',
object: 'memory',
namespace: `org_${orgId}`
})
}
);
const orgResults = await orgResponse.json();python
import requests
headers = {"Authorization": "Bearer DIALOGUE_DB_API_KEY"}
url = "https://api.dialoguedb.com/api/v1/search"
# Search only within this user's data
user_results = requests.post(
url,
headers=headers,
json={
"query": "preferences and settings",
"object": "memory",
"namespace": f"user_{user_id}"
}
).json()
# Or search across organization
org_results = requests.post(
url,
headers=headers,
json={
"query": "company policies",
"object": "memory",
"namespace": f"org_{org_id}"
}
).json()typescript
import { DialogueDB } from 'dialogue-db';
const db = new DialogueDB({ apiKey: 'DIALOGUE_DB_API_KEY' });
// Search only within this user's data
const userResults = await db.searchMemories('preferences and settings', {
namespace: `user_${userId}`
});
// Or search across organization
const orgResults = await db.searchMemories('company policies', {
namespace: `org_${orgId}`
});Combine Search with Filters
Use search to find candidates, then filter further:
bash
# Search for candidates, then filter client-side
curl -X POST https://api.dialoguedb.com/api/v1/search \
-H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "technical support", "object": "dialogue", "limit": 20}'typescript
const response = await fetch(
'https://api.dialoguedb.com/api/v1/search',
{
method: 'POST',
headers: {
'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: 'technical support',
object: 'dialogue',
limit: 20
})
}
);
const results = await response.json();
// Filter by additional criteria
const recentDialogues = results.items.filter(d => {
const createdDate = new Date(d.created);
const daysSince = (Date.now() - createdDate.getTime()) / (1000 * 60 * 60 * 24);
return daysSince <= 7; // Last 7 days only
});python
import requests
from datetime import datetime, timezone
response = requests.post(
"https://api.dialoguedb.com/api/v1/search",
headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
json={
"query": "technical support",
"object": "dialogue",
"limit": 20
}
)
results = response.json()
# Filter by additional criteria
now = datetime.now(timezone.utc)
recent_dialogues = [
d for d in results["items"]
if (now - datetime.fromisoformat(d["created"])).days <= 7
]typescript
import { DialogueDB } from 'dialogue-db';
const db = new DialogueDB({ apiKey: 'DIALOGUE_DB_API_KEY' });
const results = await db.searchDialogues('technical support', {
limit: 20
});
// Filter by additional criteria
const recentDialogues = results.filter(d => {
const createdDate = new Date(d.created);
const daysSince = (Date.now() - createdDate.getTime()) / (1000 * 60 * 60 * 24);
return daysSince <= 7; // Last 7 days only
});Cache Common Searches
For frequently repeated searches, cache results:
typescript
const searchCache = new Map();
async function cachedSearch(query: string) {
if (searchCache.has(query)) {
const cached = searchCache.get(query);
// Cache for 5 minutes
if (Date.now() - cached.timestamp < 5 * 60 * 1000) {
return cached.results;
}
}
const results = await db.searchMessages(query);
searchCache.set(query, {
results,
timestamp: Date.now()
});
return results;
}Understanding Semantic Search
How It Differs from Keyword Search
Keyword search (traditional):
- Matches exact words
- Query: "cancel subscription" only finds messages with those exact words
- Misses synonyms and related concepts
Semantic search (DialogueDB):
- Understands meaning and intent
- Query: "cancel subscription" also finds:
- "I want to stop my membership"
- "How do I end my plan?"
- "Terminate account"
- Captures conceptual similarity
Example Comparisons
Query: "How do I reset my password?"
Semantic results include:
- "I forgot my login credentials"
- "Can't access my account"
- "Need to change my authentication"
- "Locked out of my profile"
Query: "shipping is late"
Semantic results include:
- "order hasn't arrived"
- "package delayed"
- "delivery taking too long"
- "still waiting for my items"
How It Works
Behind the scenes, DialogueDB converts text into numerical representations that capture meaning. Similar concepts end up close together, so a search for "cancel my plan" also finds "stop my subscription." You don't need to understand the internals - just write natural queries and search handles the rest.
Limitations
Search Indexing
Search indexes content asynchronously. There may be a slight delay before newly created memories or messages appear in search results. For immediate access, use the get/list endpoints.
No Exact Match Guarantee
Semantic search optimizes for relevance, not exact matches:
typescript
// If you need exact ID lookups, use GET endpoints
const message = await api.message.get({ dialogueId, id: messageId });
// Don't use search for exact identifier lookups
// const results = await db.searchMessages(messageId);Project Scoped Only
Cannot search across projects - results always scoped to your API key's project:
typescript
// All results are from your project only
const results = await db.searchMessages('any query');
// No way to search across multiple projectsPerformance Considerations
Search Cost
Search operations are more expensive than direct lookups:
typescript
// When you know the ID, use direct get
const dialogue = await db.getDialogue(dialogueId);
// Use search when you need semantic matching
const results = await db.searchDialogues('conversations about X');Limit Wisely
Larger limits require more processing:
typescript
// Expensive
await db.searchMessages('anything', { limit: 100 });
// Efficient
await db.searchMessages('anything', { limit: 10 });Related Endpoints
- Messages API - Direct message operations
- Dialogues API - Direct dialogue operations
- Memory API - Direct memory operations
- Best Practices - Optimization strategies

