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
- Filter by namespace and tags
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/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/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/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/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/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/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/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
Finding Similar Conversations
Locate past conversations about specific topics:
typescript
// Find all dialogues where customers discussed refunds
const { items: dialogues } = await search({
query: 'refund or return request',
object: 'dialogue',
limit: 20
});
// Get details of the most relevant dialogue
const topDialogue = dialogues[0];
const messages = await listMessages(topDialogue.id);Knowledge Retrieval for Context
Build LLM context from relevant past information:
typescript
async function buildContextForQuery(userQuery: string) {
// Search for relevant messages
const messageResults = await search({
query: userQuery,
object: 'message',
limit: 5
});
// Search for relevant memories
const memoryResults = await search({
query: userQuery,
object: 'memory',
limit: 3
});
// Combine into context for LLM
const context = {
relevantMessages: messageResults.items,
relevantMemories: memoryResults.items
};
return context;
}Duplicate Detection
Find similar existing inquiries before creating new dialogue:
typescript
async function checkForDuplicates(newInquiry: string) {
const results = await search({
query: newInquiry,
object: 'message',
limit: 3
});
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;
}User-Specific Memory Search
Search memories for a specific user:
typescript
const results = await search({
query: 'communication preferences',
object: 'memory',
namespace: 'user_789', // Limit to this user's memories
limit: 10
});
// Results only include memories from this namespace
console.log('User preferences:', results.items);Tag-Based Filtering
Combine semantic search with tag filtering:
typescript
const results = await search({
query: 'payment issue',
object: 'message',
tags: ['support', 'billing'], // Only messages with these tags
limit: 10
});Best Practices
Query Formulation
Write queries as natural language, not keywords:
typescript
// Good: Natural language
await search({
query: 'How do customers typically cancel their subscriptions?',
object: 'message'
});
// Also good: Descriptive phrase
await search({
query: 'subscription cancellation process',
object: 'message'
});
// Works but less optimal: Single keywords
await search({
query: 'cancel',
object: 'message'
});Limit Results Appropriately
Request only what you need:
typescript
// For display to users
await search({
query: 'shipping delays',
object: 'dialogue',
limit: 10 // Top 10 most relevant
});
// For LLM context building
await search({
query: userQuery,
object: 'message',
limit: 5 // Just enough for context
});Namespace for Multi-Tenancy
Use namespace to isolate searches by user or organization:
typescript
// Search only within this user's data
const userResults = await search({
query: 'preferences and settings',
object: 'memory',
namespace: `user_${userId}`
});
// Or search across organization
const orgResults = await search({
query: 'company policies',
object: 'memory',
namespace: `org_${orgId}`
});Combine Search with Filters
Use search to find candidates, then filter further:
typescript
const results = await search({
query: 'technical support',
object: 'dialogue',
limit: 50
});
// 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
});Cache Common Searches
For frequently repeated searches, cache results:
typescript
const searchCache = new Map();
async function cachedSearch(query: string, object: string) {
const cacheKey = `${query}:${object}`;
if (searchCache.has(cacheKey)) {
const cached = searchCache.get(cacheKey);
// Cache for 5 minutes
if (Date.now() - cached.timestamp < 5 * 60 * 1000) {
return cached.results;
}
}
const results = await search({ query, object });
searchCache.set(cacheKey, {
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
Not Real-Time
Newly created content may take a few seconds to appear in search results:
typescript
// Create a message
await createMessage(dialogueId, {
role: 'user',
content: 'New question about billing'
});
// May not appear in search immediately
const results = await search({
query: 'billing question',
object: 'message'
});
// Might not include the just-created message yetFor real-time queries, use list/get endpoints instead of search.
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 getMessage(dialogueId, messageId);
// Don't use search for exact identifier lookups
// const results = await search({ query: messageId, object: 'message' });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 search({
query: 'any query',
object: 'message'
});
// 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 getDialogue(dialogueId);
// Use search when you need semantic matching
const results = await search({
query: 'conversations about X',
object: 'dialogue'
});Limit Wisely
Larger limits require more processing:
typescript
// Expensive
await search({ query: 'anything', object: 'message', limit: 1000 });
// Efficient
await search({ query: 'anything', object: 'message', limit: 10 });Related Endpoints
- Messages API - Direct message operations
- Dialogues API - Direct dialogue operations
- Memory API - Direct memory operations
- Best Practices - Optimization strategies

