Quickstart Guide

Get started with DialogueDB in under 5 minutes. This guide will walk you through creating your first conversation and sending messages.

Prerequisites

Before you begin, you'll need:

A DialogueDB API key
An HTTP client (cURL, Postman, or your preferred programming language)
The API base URL: https://api.dialoguedb.com

TIP

Don't have an API key yet? Create one in your project dashboard or visit the Authentication guide for details on obtaining one.

Installation

If you're using the SDK, install the DialogueDB package:

bash

npm install dialogue-db

Step 1: Create Your First Dialogue

Create a new dialogue with an initial message:

SDKcURLTypeScript (fetch)Python

typescript

import { DialogueDB } from 'dialogue-db';

const db = new DialogueDB({
  apiKey: 'DIALOGUE_DB_API_KEY'
});

const dialogue = await db.createDialogue({
  messages: [{
    role: 'user',
    content: 'Hello! Can you help me understand DialogueDB?'
  }]
});

console.log('Dialogue ID:', dialogue.id);

bash

curl -X POST https://api.dialoguedb.com/api/v1/dialogue \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "role": "user",
      "content": "Hello! Can you help me understand DialogueDB?"
    }]
  }'

typescript

const response = await fetch('https://api.dialoguedb.com/api/v1/dialogue', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [{
      role: 'user',
      content: 'Hello! Can you help me understand DialogueDB?'
    }]
  })
});

const dialogue = await response.json();
console.log('Dialogue ID:', dialogue.id);

python

import requests

response = requests.post(
    "https://api.dialoguedb.com/api/v1/dialogue",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
    json={
        "messages": [{
            "role": "user",
            "content": "Hello! Can you help me understand DialogueDB?"
        }]
    }
)

dialogue = response.json()
print("Dialogue ID:", dialogue["id"])

TIP

You can include messages at creation time (as shown above) or create an empty dialogue and add messages later with saveMessage().

Response:

json

{
  "id": "01KACE6RAZKQ93354SF18CJHHC",
  "requestId": "cf7cbe59-9882-4539-a760-7eb68fbb6275",
  "tags": [],
  "totalMessages": 1,
  "threadCount": 0,
  "lastMessageCreated": "2025-11-18T21:33:49.795Z",
  "metadata": {},
  "created": "2025-11-18T21:33:49.899Z",
  "modified": "2025-11-18T21:33:49.899Z",
  "messages": [
    {
      "dialogueId": "01KACE6RAZKQ93354SF18CJHHC",
      "id": "01KACE6RB06C5E1CCJKG8TTJ5B",
      "role": "user",
      "content": "Hello! Can you help me understand DialogueDB?",
      "created": "2025-11-18T21:33:49.795Z",
      "metadata": {},
      "tags": []
    }
  ],
  "state": {}
}

TIP

Save the dialogue id - you'll need it to add more messages to this conversation!

Step 2: Add a Message to the Dialogue

Add an assistant response to the conversation:

SDKcURLTypeScript (fetch)Python

typescript

const message = await dialogue.saveMessage({
  role: 'assistant',
  content: 'Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications.'
});

console.log('Message ID:', message.id);

bash

curl -X POST https://api.dialoguedb.com/api/v1/message \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dialogueId": "DIALOGUE_ID",
    "role": "assistant",
    "content": "Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications."
  }'

typescript

const messageResponse = await fetch(
  'https://api.dialoguedb.com/api/v1/message',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      dialogueId: dialogue.id,
      role: 'assistant',
      content: 'Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications.'
    })
  }
);

const message = await messageResponse.json();
console.log('Message ID:', message.id);

python

response = requests.post(
    "https://api.dialoguedb.com/api/v1/message",
    headers={
        "Authorization": "Bearer DIALOGUE_DB_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "dialogueId": dialogue_id,
        "role": "assistant",
        "content": "Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications."
    }
)

message = response.json()
print("Message ID:", message["id"])

Response:

json

{
  "dialogueId": "01KAD6TA5XHAHESWVJ8TMWJQAW",
  "id": "01KAD7FYPBVZBF5J1KVVR9NR8S",
  "role": "assistant",
  "content": "Of course! DialogueDB is a conversation management API that helps you store and retrieve chat histories for AI applications.",
  "created": "2025-11-19T04:55:45.628Z",
  "metadata": {},
  "tags": []
}

Step 3: Retrieve the Conversation

Fetch the dialogue metadata and messages:

SDKcURLTypeScript (fetch)Python

typescript

// Get dialogue
const dialogue = await db.getDialogue(dialogueId);
console.log('Total messages:', dialogue.totalMessages);

// Load messages — returns a plain array of Message objects
const messages = await dialogue.loadMessages();
console.log('Message count:', messages.length);
console.log('First message:', messages[0].content);

bash

# Get dialogue metadata
curl -X GET https://api.dialoguedb.com/api/v1/dialogue/01KAD6TA5XHAHESWVJ8TMWJQAW \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY"

# Get messages
curl -X GET "https://api.dialoguedb.com/api/v1/messages?dialogueId=01KAD6TA5XHAHESWVJ8TMWJQAW" \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY"

typescript

// Get dialogue metadata
const dialogueResponse = await fetch(
  `https://api.dialoguedb.com/api/v1/dialogue/${dialogue.id}`,
  {
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_API_KEY'
    }
  }
);

const dialogueData = await dialogueResponse.json();
console.log('Total messages:', dialogueData.totalMessages);

// Get messages
const messagesResponse = await fetch(
  `https://api.dialoguedb.com/api/v1/messages?dialogueId=${dialogue.id}`,
  {
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_API_KEY'
    }
  }
);

const { items: messages } = await messagesResponse.json();
console.log('Messages:', messages);

python

# Get dialogue metadata
response = requests.get(
    f"https://api.dialoguedb.com/api/v1/dialogue/{dialogue_id}",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"}
)
dialogue_data = response.json()
print("Total messages:", dialogue_data["totalMessages"])

# Get messages
response = requests.get(
    f"https://api.dialoguedb.com/api/v1/messages?dialogueId={dialogue_id}",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"}
)
data = response.json()
print("Messages:", data["items"])

Dialogue Response:

json

{
  "id": "01KAD6TA5XHAHESWVJ8TMWJQAW",
  "projectId": "01KAD6R34620P1C5J0M2KRMGRG",
  "status": "active",
  "tags": [],
  "totalMessages": 2,
  "threadCount": 0,
  "lastMessageCreated": "2025-11-19T04:55:45.628Z",
  "metadata": {},
  "created": "2025-11-19T04:43:56.625Z",
  "modified": "2025-11-19T04:55:45.768Z",
  "messages": [
    {
      "dialogueId": "01KAD6TA5XHAHESWVJ8TMWJQAW",
      "id": "01KAD6TA5YCDQ87RMXPHRRJ05C",
      "role": "user",
      "content": "Hello! Can you help me understand DialogueDB?",
      "created": "2025-11-19T04:43:56.488Z",
      "metadata": {},
      "tags": []
    }
  ],
  "state": {}
}

Messages Response (REST API / cURL / fetch):

json

{
  "items": [
    {
      "dialogueId": "01KAD6TA5XHAHESWVJ8TMWJQAW",
      "id": "01KAD7FYPBVZBF5J1KVVR9NR8S",
      "role": "assistant",
      "content": "Of course! DialogueDB is a conversation management API.",
      "created": "2025-11-19T04:55:45.628Z",
      "metadata": {},
      "tags": []
    },
    {
      "dialogueId": "01KAD6TA5XHAHESWVJ8TMWJQAW",
      "id": "01KAD6TA5YCDQ87RMXPHRRJ05C",
      "role": "user",
      "content": "Hello! Can you help me understand DialogueDB?",
      "created": "2025-11-19T04:43:56.488Z",
      "metadata": {},
      "tags": []
    }
  ],
  "next": null
}

SDK vs REST response format

The SDK's loadMessages() returns a plain array of Message objects. Pagination is handled internally — use loadMessages({ next: true }) to load the next page and dialogue.hasMoreMessages to check if more pages exist.

The REST API returns { items: [...], next: "..." } with an explicit pagination token. The cURL, fetch, and Python examples above show this format.

Step 4: List All Dialogues

Retrieve all conversations in your project:

SDKcURLTypeScript (fetch)Python

typescript

const { items, next } = await db.listDialogues({
  limit: 10,
  order: 'desc'
});

console.log(`Found ${items.length} dialogues`);

bash

curl -X GET "https://api.dialoguedb.com/api/v1/dialogue?limit=10&order=desc" \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY"

typescript

const listResponse = await fetch(
  'https://api.dialoguedb.com/api/v1/dialogue?limit=10&order=desc',
  {
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_API_KEY'
    }
  }
);

const { items, next } = await listResponse.json();
console.log(`Found ${items.length} dialogues`);

python

response = requests.get(
    "https://api.dialoguedb.com/api/v1/dialogue",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
    params={"limit": 10, "order": "desc"}
)

data = response.json()
print(f"Found {len(data['items'])} dialogues")

Step 5: Store a Memory

Memories let you persist information across dialogues - such as user preferences, facts, or context that should be available long-term.

SDKcURLTypeScript (fetch)Python

typescript

const memory = await db.createMemory({
  value: 'User prefers dark mode',
  label: 'UI Preference',
  tags: ['preferences']
});

console.log('Memory ID:', memory.id);

// Retrieve the memory later
const retrieved = await db.getMemory(memory.id);
console.log('Value:', retrieved.value);

bash

curl -X POST https://api.dialoguedb.com/api/v1/memory \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "User prefers dark mode",
    "label": "UI Preference",
    "tags": ["preferences"]
  }'

typescript

const response = await fetch('https://api.dialoguedb.com/api/v1/memory', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    value: 'User prefers dark mode',
    label: 'UI Preference',
    tags: ['preferences']
  })
});

const memory = await response.json();
console.log('Memory ID:', memory.id);

python

response = requests.post(
    "https://api.dialoguedb.com/api/v1/memory",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
    json={
        "value": "User prefers dark mode",
        "label": "UI Preference",
        "tags": ["preferences"]
    }
)

memory = response.json()
print("Memory ID:", memory["id"])

Memories vs State vs Messages

Memories persist across dialogues and are searchable via semantic search - use for long-term facts and preferences
State is scoped to a single dialogue - use for conversation-specific context
Messages are the actual conversation turns - use for chat history

Learn more in the Memory API and Core Concepts guides.

INFO

Search indexes content asynchronously. There may be a slight delay before newly created memories or messages appear in search results.

Congratulations!

You've successfully:

Created your first dialogue
Added messages to a conversation
Retrieved conversation history
Listed all dialogues
Stored a memory

Next Steps

Now that you've created your first conversation, explore more advanced features:

Core Concepts - Learn about threads, state, and message management
Use Cases & Patterns - Common patterns for building conversational apps
API Reference - Complete API documentation
Best Practices - Optimization tips and error handling strategies

Common Patterns

Building a Chatbot

typescript

import { DialogueDB } from 'dialogue-db';

const db = new DialogueDB({ apiKey: process.env.DIALOGUE_DB_API_KEY });

// Initialize conversation
const dialogue = await db.createDialogue({
  messages: [{ role: 'system', content: 'You are a helpful assistant.' }]
});

// User sends a message
await dialogue.saveMessage({
  role: 'user',
  content: userInput
});

// Get AI response (from your LLM)
const aiResponse = await generateResponse(userInput);

// Store AI response
await dialogue.saveMessage({
  role: 'assistant',
  content: aiResponse
});

// Retrieve full history for context
const messages = await dialogue.loadMessages();

Managing Long Conversations

SDKcURLTypeScript (fetch)Python

typescript

await dialogue.end();

bash

curl -X POST https://api.dialoguedb.com/api/v1/dialogue/DIALOGUE_ID/end \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY"

typescript

await fetch(`https://api.dialoguedb.com/api/v1/dialogue/${dialogueId}/end`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer DIALOGUE_DB_API_KEY'
  }
});

python

import requests

requests.post(
    f"https://api.dialoguedb.com/api/v1/dialogue/{dialogue_id}/end",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"}
)

Creating Threads

SDKcURLTypeScript (fetch)Python

typescript

// Create a thread linked to a parent dialogue
const thread = await dialogue.createThread({
  metadata: { purpose: 'subtask' }
});

// Add messages after creation
await thread.saveMessage({
  role: 'system',
  content: 'Processing subtask...'
});

bash

# Create a thread linked to a parent dialogue
curl -X POST https://api.dialoguedb.com/api/v1/dialogue \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "threadOf": "PARENT_DIALOGUE_ID",
    "metadata": { "purpose": "subtask" }
  }'

# Add messages after creation
curl -X POST https://api.dialoguedb.com/api/v1/message \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dialogueId": "THREAD_ID",
    "role": "system",
    "content": "Processing subtask..."
  }'

typescript

// Create a thread linked to a parent dialogue
const response = await fetch('https://api.dialoguedb.com/api/v1/dialogue', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    threadOf: 'PARENT_DIALOGUE_ID',
    metadata: { purpose: 'subtask' }
  })
});

const thread = await response.json();

// Add messages after creation
await fetch('https://api.dialoguedb.com/api/v1/message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dialogueId: thread.id,
    role: 'system',
    content: 'Processing subtask...'
  })
});

python

import requests

# Create a thread linked to a parent dialogue
response = requests.post(
    "https://api.dialoguedb.com/api/v1/dialogue",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
    json={
        "threadOf": "PARENT_DIALOGUE_ID",
        "metadata": {"purpose": "subtask"}
    }
)

thread = response.json()

# Add messages after creation
requests.post(
    "https://api.dialoguedb.com/api/v1/message",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
    json={
        "dialogueId": thread["id"],
        "role": "system",
        "content": "Processing subtask..."
    }
)

Advanced Features

Custom Identifiers

Set your own IDs to match your database records:

SDKcURLTypeScript (fetch)Python

typescript

const dialogue = await db.createDialogue({
  id: 'customer_inquiry_12345',  // Your custom ID
  messages: [{
    id: 'initial_message_001',   // Custom message ID
    role: 'user',
    content: 'Help with billing'
  }]
});

bash

# Create dialogue with custom ID
curl -X POST https://api.dialoguedb.com/api/v1/dialogue \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "customer_inquiry_12345",
    "messages": [{
      "id": "initial_message_001",
      "role": "user",
      "content": "Help with billing"
    }]
  }'

typescript

// Create dialogue with custom ID
const response = await fetch('https://api.dialoguedb.com/api/v1/dialogue', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    id: 'customer_inquiry_12345',
    messages: [{
      id: 'initial_message_001',
      role: 'user',
      content: 'Help with billing'
    }]
  })
});

const dialogue = await response.json();

python

import requests

# Create dialogue with custom ID
response = requests.post(
    "https://api.dialoguedb.com/api/v1/dialogue",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
    json={
        "id": "customer_inquiry_12345",
        "messages": [{
            "id": "initial_message_001",
            "role": "user",
            "content": "Help with billing"
        }]
    }
)

dialogue = response.json()

Namespace for Multi-Tenancy

Use namespace to isolate data by user or organization:

SDKcURLTypeScript (fetch)Python

typescript

// Create user-specific dialogue
const dialogue = await db.createDialogue({
  namespace: `user_${userId}`,
  messages: [{
    role: 'user',
    content: 'Hello'
  }]
});

// List only this user's dialogues
const { items: userDialogues } = await db.listDialogues({
  namespace: `user_${userId}`
});

bash

# Create user-specific dialogue
curl -X POST https://api.dialoguedb.com/api/v1/dialogue \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "user_123",
    "messages": [{
      "role": "user",
      "content": "Hello"
    }]
  }'

# List only this user's dialogues
curl -X GET "https://api.dialoguedb.com/api/v1/dialogue?namespace=user_123" \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY"

typescript

// Create user-specific dialogue
const response = await fetch('https://api.dialoguedb.com/api/v1/dialogue', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    namespace: `user_${userId}`,
    messages: [{
      role: 'user',
      content: 'Hello'
    }]
  })
});

const dialogue = await response.json();

// List only this user's dialogues
const listResponse = await fetch(
  `https://api.dialoguedb.com/api/v1/dialogue?namespace=user_${userId}`,
  {
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_API_KEY'
    }
  }
);

const { items: userDialogues } = await listResponse.json();

python

import requests

# Create user-specific dialogue
response = requests.post(
    "https://api.dialoguedb.com/api/v1/dialogue",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
    json={
        "namespace": f"user_{user_id}",
        "messages": [{
            "role": "user",
            "content": "Hello"
        }]
    }
)

dialogue = response.json()

# List only this user's dialogues
response = requests.get(
    "https://api.dialoguedb.com/api/v1/dialogue",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
    params={"namespace": f"user_{user_id}"}
)

user_dialogues = response.json()["items"]

Quickstart Guide ​

Prerequisites ​

Installation ​

Step 1: Create Your First Dialogue ​

Step 2: Add a Message to the Dialogue ​

Step 3: Retrieve the Conversation ​

Step 4: List All Dialogues ​

Step 5: Store a Memory ​

Congratulations! ​

Next Steps ​

Common Patterns ​

Building a Chatbot ​

Managing Long Conversations ​

Creating Threads ​

Advanced Features ​

Custom Identifiers ​

Namespace for Multi-Tenancy ​

Quickstart Guide

Prerequisites

Installation

Step 1: Create Your First Dialogue

Step 2: Add a Message to the Dialogue

Step 3: Retrieve the Conversation

Step 4: List All Dialogues

Step 5: Store a Memory

Congratulations!

Next Steps

Common Patterns

Building a Chatbot

Managing Long Conversations

Creating Threads

Advanced Features

Custom Identifiers

Namespace for Multi-Tenancy