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 YOUR_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
PUT	`/dialogue/{id}/{action}`	Perform action on dialogue (end, compact, continue)

Messages

Method	Endpoint	Description
POST	`/dialogue/{id}/messages`	Create message
GET	`/dialogue/{id}/messages`	List messages
GET	`/dialogue/{dialogueId}/messages/{messageId}`	Get single message
DELETE	`/dialogue/{id}/messages/{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
GET	`/search`	Semantic search across messages, dialogues, or memories

Quick Examples

Create a Dialogue

cURLTypeScriptDialogueDB SDK

bash

curl -X POST https://api.dialoguedb.com/dialogue \
  -H "Authorization: Bearer YOUR_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 YOUR_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: "your-api-key" });

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

List Dialogues

cURLTypeScriptNode.js SDK

bash

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

typescript

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

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

typescript

import { listDialogues } from 'dialoguedb';

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

Create a Message

cURLTypeScriptNode.js SDK

bash

curl -X POST https://api.dialoguedb.com/dialogue/DIALOGUE_ID/messages \
  -H "Authorization: Bearer YOUR_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 YOUR_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

import { api } from 'dialoguedb';

const message = await api.message.create({
  dialogueId,
  role: 'assistant',
  content: 'Hello! How can I help you today?'
});

Update Dialogue State

cURLTypeScriptNode.js SDK

bash

curl -X PUT https://api.dialoguedb.com/dialogue/DIALOGUE_ID/state \
  -H "Authorization: Bearer YOUR_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 YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      currentStep: 'checkout',
      cartTotal: 149.99
    })
  }
);

const state = await response.json();

typescript

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

const state = await response.json();

Create Memory

cURLTypeScriptNode.js SDK

bash

curl -X POST https://api.dialoguedb.com/memory \
  -H "Authorization: Bearer YOUR_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 YOUR_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 { api } from 'dialoguedb';

const memory = await api.memory.create({
  value: 'User prefers email notifications',
  label: 'Communication Preference',
  namespace: 'user_789'
});

Search

cURLTypeScriptNode.js SDK

bash

curl -X GET "https://api.dialoguedb.com/search?query=billing%20issue&object=message" \
  -H "Authorization: Bearer YOUR_API_KEY"

typescript

const response = await fetch(
  'https://api.dialoguedb.com/search?' + new URLSearchParams({
    query: 'billing issue',
    object: 'message'
  }),
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

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

typescript

import { api } from 'dialoguedb';

const results = await api.search({
  query: 'billing issue',
  object: 'message'
});

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 - Semantic vector search

SDKs

Official SDKs:

JavaScript/TypeScript: npm install dialogue-db
Python: Coming soon

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.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