API Reference

Welcome to the DialogueDB API reference. This documentation covers all available endpoints for managing conversations and messages.

Base URL

https://api.dialoguedb.com

Authentication

All API requests require authentication via bearer token:

http

Authorization: Bearer DIALOGUE_DB_API_KEY

See the Authentication Guide for details.

Response Format

All successful responses return JSON with the following structure:

json

{
  "id": "resource_id",
  "...": "resource_properties"
}

List endpoints return paginated results:

json

{
  "items": [],
  "next": "pagination_token_or_null"
}

Error Responses

All errors return appropriate HTTP status codes and detailed information:

json

{
  "error": {
    "code": "DIALOGUE_NOT_FOUND",
    "message": "Dialogue 'dlg_abc123' not found",
    "type": "not_found",
    "details": [],
    "requestId": "req_xyz789",
    "timestamp": "2025-11-06T21:34:21.117Z"
  }
}

Error Object Fields

code - Machine-readable error code (e.g., DIALOGUE_NOT_FOUND, MISSING_PARAMETER)
message - Human-readable description
type - Error category: validation_error, not_found, conflict, rate_limit, server
details - Optional array of field-level validation errors
requestId - Unique identifier for debugging and support
timestamp - When the error occurred (ISO 8601)

Common Status Codes

Code	Meaning	When Used
200	OK	Request successful
400	Bad Request	Validation errors, missing required fields, invalid input
401	Unauthorized	Missing or invalid authentication token
404	Not Found	Resource (dialogue, message, project) does not exist
409	Conflict	Resource conflict (e.g., immutability violation)
429	Too Many Requests	Rate limit exceeded - retry with backoff
500	Server Error	Unexpected server error - use requestId for support

See the Error Handling Guide for detailed error codes, examples, and best practices.

Rate Limits

API requests are rate-limited to ensure fair usage and system stability:

Additionally, monthly quotas apply based on your subscription plan. Rate limit headers are included in all responses:

http

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

Pagination

List endpoints support pagination using the next token:

typescript

// Initial request
const { items, next } = await fetch('/dialogue?limit=20');

// Next page
if (next) {
  const { items: more, next: nextToken } = await fetch(`/dialogue?limit=20&next=${next}`);
}

Endpoints Overview

Dialogues

Method	Endpoint	Description
POST	`/dialogue`	Create new dialogue
PUT	`/dialogue/{id}`	Update dialogue (tags, label, state, messages)
GET	`/dialogue`	List dialogues
GET	`/dialogue/{id}`	Get single dialogue
DELETE	`/dialogue/{id}`	Delete dialogue
POST	`/dialogue/{id}/{action}`	Perform action on dialogue (end, compact)

Messages

Method	Endpoint	Description
POST	`/dialogue/{id}/messages`	Create message
GET	`/dialogue/{id}/messages`	List messages
GET	`/dialogue/{id}/message/{messageId}`	Get single message
PUT	`/dialogue/{id}/message/{messageId}`	Update message tags
DELETE	`/dialogue/{id}/message/{messageId}`	Delete message

State

Method	Endpoint	Description
PUT	`/dialogue/{id}/state`	Create or update dialogue state
GET	`/dialogue/{id}`	Get dialogue (includes state)

Memory

Method	Endpoint	Description
POST	`/memory`	Create memory
GET	`/memory`	List memories
GET	`/memory/{id}`	Get single memory
PUT	`/memory/{id}`	Update memory tags
DELETE	`/memory/{id}`	Delete memory

Search

Method	Endpoint	Description
POST	`/search`	Semantic search across messages, dialogues, or memories

Quick Examples

Create a Dialogue

cURLTypeScript (fetch)SDKPython

bash

curl -X POST https://api.dialoguedb.com/dialogue \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "role": "user",
      "content": "Hello!"
    }
  }'

typescript

const response = await fetch('https://api.dialoguedb.com/dialogue', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: {
      role: 'user',
      content: 'Hello!'
    }
  })
});

const dialogue = await response.json();

typescript

import { DialogueDB } from "dialogue-db";

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

const dialogue = await db.createDialogue({
  messages: [{
    role: "user",
    content: "Hello!"
  }]
});

python

import requests

response = requests.post(
    "https://api.dialoguedb.com/dialogue",
    headers={
        "Authorization": "Bearer DIALOGUE_DB_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "message": {
            "role": "user",
            "content": "Hello!"
        }
    }
)

dialogue = response.json()

List Dialogues

cURLTypeScript (fetch)SDKPython

bash

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

typescript

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

const { items, next } = await response.json();

typescript

import { DialogueDB } from "dialogue-db";


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

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

python

import requests

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

data = response.json()
items = data["items"]
next_token = data["next"]

Create a Message

cURLTypeScript (fetch)SDKPython

bash

curl -X POST https://api.dialoguedb.com/dialogue/DIALOGUE_ID/messages \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "assistant",
    "content": "Hello! How can I help you today?"
  }'

typescript

const response = await fetch(
  `https://api.dialoguedb.com/dialogue/${dialogueId}/messages`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      role: 'assistant',
      content: 'Hello! How can I help you today?'
    })
  }
);

const message = await response.json();

typescript

const dialogue = await db.getDialogue(dialogueId);


await dialogue.saveMessage({
  role: "assistant",
  content: "Hello! How can I help you today?"
});

python

import requests

dialogue_id = "DIALOGUE_ID"

response = requests.post(
    f"https://api.dialoguedb.com/dialogue/{dialogue_id}/messages",
    headers={
        "Authorization": "Bearer DIALOGUE_DB_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "role": "assistant",
        "content": "Hello! How can I help you today?"
    }
)

message = response.json()

Update Dialogue State

cURLTypeScript (fetch)SDKPython

bash

curl -X PUT https://api.dialoguedb.com/dialogue/DIALOGUE_ID/state \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currentStep": "checkout",
    "cartTotal": 149.99
  }'

typescript

const response = await fetch(
  `https://api.dialoguedb.com/dialogue/${dialogueId}/state`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      currentStep: 'checkout',
      cartTotal: 149.99
    })
  }
);

const state = await response.json();

typescript

const dialogue = await db.getDialogue(dialogueId);

await dialogue.saveState({
  currentStep: "checkout",
  cartTotal: 149.99
});

python

import requests

dialogue_id = "DIALOGUE_ID"

response = requests.put(
    f"https://api.dialoguedb.com/dialogue/{dialogue_id}/state",
    headers={
        "Authorization": "Bearer DIALOGUE_DB_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "currentStep": "checkout",
        "cartTotal": 149.99
    }
)

state = response.json()

Create Memory

cURLTypeScript (fetch)SDKPython

bash

curl -X POST https://api.dialoguedb.com/memory \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "User prefers email notifications",
    "label": "Communication Preference",
    "namespace": "user_789"
  }'

typescript

const response = await fetch(
  'https://api.dialoguedb.com/memory',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      value: 'User prefers email notifications',
      label: 'Communication Preference',
      namespace: 'user_789'
    })
  }
);

const memory = await response.json();

typescript

import { DialogueDB } from "dialogue-db";


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

const memory = await db.createMemory({
  value: "User prefers email notifications",
  label: "Communication Preference",
  namespace: "user_789"
});

python

import requests

response = requests.post(
    "https://api.dialoguedb.com/memory",
    headers={
        "Authorization": "Bearer DIALOGUE_DB_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "value": "User prefers email notifications",
        "label": "Communication Preference",
        "namespace": "user_789"
    }
)

memory = response.json()

Search

cURLTypeScript (fetch)SDKPython

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": "message"}'

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: 'billing issue',
      object: 'message'
    })
  }
);

const { items } = await response.json();

typescript

import { DialogueDB } from "dialogue-db";


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

const results = await db.searchMessages("billing issue");

python

import requests

response = requests.get(
    "https://api.dialoguedb.com/search",
    headers={
        "Authorization": "Bearer DIALOGUE_DB_API_KEY"
    },
    params={
        "query": "billing issue",
        "object": "message"
    }
)

results = response.json()

Resource Details

For detailed information about each endpoint:

Dialogues API - Full dialogue management
Messages API - Message operations
State API - Dialogue state management
Memory API - Long-term knowledge storage
Search API - Search by meaning across your data

SDKs

Official SDKs:

JavaScript/TypeScript: npm install dialogue-db
Python: Use the requests library (examples included throughout docs)

Community SDKs:

Check our GitHub for community contributions

Support

Need help?

Guides - Comprehensive guides
Examples - Code examples
Best Practices - Optimization tips

Changelog

Stay updated with API changes and improvements:

v1.0.2 (2025-02) - Documentation improvements, SDK example fixes
v1.0.1 (2025-01) - Bug fixes and stability improvements
v1.0.0 (2025-01-15) - Initial release
- Dialogue management
- Message operations
- Thread support
- State management

API Reference ​

Base URL ​

Authentication ​

Response Format ​

Error Responses ​

Error Object Fields ​

Common Status Codes ​

Rate Limits ​

Pagination ​

Endpoints Overview ​

Dialogues ​

Messages ​

State ​

Memory ​

Search ​

Quick Examples ​

Create a Dialogue ​

List Dialogues ​

Create a Message ​

Update Dialogue State ​

Create Memory ​

Search ​

Resource Details ​

SDKs ​

Support ​

Changelog ​

API Reference

Base URL

Authentication

Response Format

Error Responses

Error Object Fields

Common Status Codes

Rate Limits

Pagination

Endpoints Overview

Dialogues

Messages

State

Memory

Search

Quick Examples

Create a Dialogue

List Dialogues

Create a Message

Update Dialogue State

Create Memory

Search

Resource Details

SDKs

Support

Changelog