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 /search

Authentication

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 discussed

Returns 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 choices

Returns 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 yet

For 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 projects

Performance 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 });

Messages API - Direct message operations
Dialogues API - Direct dialogue operations
Memory API - Direct memory operations
Best Practices - Optimization strategies

Search API ​

Overview ​

Search ​

Endpoint ​

Authentication ​

Request Body ​

Response ​

Behavior ​

Search Types Explained ​

Message Search ​

Dialogue Search ​

Memory Search ​

Use Cases ​

Errors ​

Examples ​

Search Patterns ​

Finding Similar Conversations ​

Knowledge Retrieval for Context ​

Duplicate Detection ​

User-Specific Memory Search ​

Tag-Based Filtering ​

Best Practices ​

Query Formulation ​

Limit Results Appropriately ​

Namespace for Multi-Tenancy ​

Combine Search with Filters ​

Cache Common Searches ​

Understanding Semantic Search ​

How It Differs from Keyword Search ​

Example Comparisons ​

How It Works ​

Limitations ​

Not Real-Time ​

No Exact Match Guarantee ​

Project Scoped Only ​

Performance Considerations ​

Search Cost ​

Limit Wisely ​

Related Endpoints ​

Search API

Overview

Search

Endpoint

Authentication

Request Body

Response

Behavior

Search Types Explained

Message Search

Dialogue Search

Memory Search

Use Cases

Errors

Examples

Search Patterns

Finding Similar Conversations

Knowledge Retrieval for Context

Duplicate Detection

User-Specific Memory Search

Tag-Based Filtering

Best Practices

Query Formulation

Limit Results Appropriately

Namespace for Multi-Tenancy

Combine Search with Filters

Cache Common Searches

Understanding Semantic Search

How It Differs from Keyword Search

Example Comparisons

How It Works

Limitations

Not Real-Time

No Exact Match Guarantee

Project Scoped Only

Performance Considerations

Search Cost

Limit Wisely

Related Endpoints