Dialogues API

Manage conversations with threading and state management.

Create Dialogue

Create a new dialogue.

Endpoint

http

POST /dialogue

Authentication

Bearer token (via Authorization header)

Request Body

Field	Type	Required	Description
`id`	string	No	Custom dialogue ID (auto-generated if not provided)
`namespace`	string	No	Optional namespace for user isolation (e.g., `userId`)
`threadOf`	string	No	Parent dialogue ID if this is a thread
`message`	object	No	Single message to add
`message.id`	string	No	Custom message ID (auto-generated if not provided)
`message.content`	string	Yes	Message content
`message.role`	string	Yes	Message role (user, assistant, system)
`message.name`	string	No	Optional name for the speaker
`message.created`	string	No	Custom creation timestamp (ISO 8601)
`message.tags`	string[]	No	Message tags
`message.metadata`	object	No	Message metadata (immutable after creation)
`messages`	array	No	Array of messages (treated as history)
`messages[].id`	string	No	Custom message ID
`messages[].content`	string	Yes	Message content
`messages[].role`	string	Yes	Message role
`messages[].name`	string	No	Optional speaker name
`messages[].created`	string	No	Custom creation timestamp
`messages[].tags`	string[]	No	Message tags
`messages[].metadata`	object	No	Message metadata
`state`	object	No	Custom state data
`metadata`	object	No	Custom metadata (can't be changed after creation)
`tags`	string[]	No	Tags for the dialogue

Response

typescript

{
  id: string;
  projectId: string;
  threadOf?: string;
  totalMessages: number;
  threadCount?: number;
  status: string;
  tags: string[];
  metadata: Record<string, any>;
  created: string;
  modified: string;
  messages: Message[];  // Created messages returned
}

Behavior

Authenticated via bearer token
To create a thread: Set threadOf to parent dialogue's ID
Use message (singular object) for a single message, or messages (array) for multiple
Cannot provide both message and messages — use one or the other
Maximum 25 messages in initial creation
Returns dialogue with created messages

Which Fields Can Be Changed?

User-settable on creation:

id - Custom identifier (auto-generated if not provided)
namespace - Optional namespace for user isolation
threadOf - Parent dialogue reference
tags - Categorization tags
metadata - Custom metadata (can't be changed after creation)
messages/message - Initial conversation history
state - Initial state data

System-managed (read-only):

projectId - Your project identifier
status - Dialogue status (active, ended, archived)
totalMessages - Message count
threadCount - Number of child threads
lastMessageCreated - Timestamp of most recent message
created - Creation timestamp
modified - Last modification timestamp

Important Restrictions

Dialogue metadata can't be changed after creation - it cannot be updated via PUT /dialogue/
Once a dialogue status is "ended", you cannot add messages or update it
Use tags (mutable) for categorization that may change
Use state (mutable) for data that changes during conversation

Constraints

Maximum 25 messages in initial creation
Messages can't be changed after creation
Dialogue IDs are auto-generated if not provided (must be unique within project)

Use Cases

New Conversation: Omit threadOf to create a root dialogue
Threaded Reply: Include threadOf to branch from existing dialogue
Import History: Use messages array to restore conversation context

Errors

Status	Error Code	Description
400	`TOO_MANY_MESSAGES`	Exceeds 25 message limit on creation
400	`INVALID_INPUT`	Invalid input data or format
401	N/A	Unauthorized - invalid or missing API key
404	`PROJECT_NOT_FOUND`	Project does not exist
404	`PARENT_DIALOGUE_NOT_FOUND`	Parent dialogue not found (for threads)
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

cURLTypeScript (fetch)PythonSDK

bash

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

typescript

const dialogue = 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'
    },
    metadata: {
      userId: 'user_123',
      channel: 'web'
    },
    tags: ['support']
  })
});

python

import requests

response = requests.post(
    "https://api.dialoguedb.com/dialogue",
    headers={
        "Authorization": "Bearer DIALOGUE_DB_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "messages": [{"role": "user", "content": "Hello"}],
        "metadata": {"userId": "user_123"}
    }
)
dialogue = response.json()

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'
  }],
  metadata: {
    userId: 'user_123'
  }
});

Update Dialogue

Update an existing dialogue's mutable properties and optionally add messages.

Endpoint

http

PUT /dialogue/{id}

Authentication

Bearer token (via Authorization header)

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Dialogue ID (identifier)

Request Body

Field	Type	Required	Description
`tags`	string[]	No	Tags for the dialogue (replaces existing)
`label`	string	No	Human-readable label (max 128 chars)
`state`	object	No	State data (merged with existing state)
`message`	object	No	Single message to add
`messages`	array	No	Array of messages to add (max 25)

Response

typescript

{
  id: string;
  projectId: string;
  namespace?: string;
  threadOf?: string;
  totalMessages: number;
  threadCount?: number;
  status: string;
  tags: string[];
  metadata: Record<string, any>;  // Immutable - set at creation
  created: string;
  modified: string;
  messages: Message[];            // Created messages (if any provided)
  state: Record<string, any>;     // Current state data
}

Behavior

Updates mutable fields: tags, label, state
Adds messages if message or messages provided
Tags are replaced entirely (not merged)
State is merged with existing state (new keys added, existing keys updated, missing keys preserved)
Metadata cannot be updated - it is locked after dialogue creation
Cannot modify existing messages or status through this endpoint

Metadata Can't Be Changed

Dialogue metadata is set at creation and cannot be changed. If you need data that changes:

Use tags for categorization that may change
Use label for a human-readable identifier
Use state for conversation-specific data that changes

Errors

Status	Error Code	Description
400	`MISSING_PARAMETER`	Missing required dialogue ID
400	`INVALID_INPUT`	Invalid metadata or tags format
401	N/A	Unauthorized - invalid or missing API key
404	`DIALOGUE_NOT_FOUND`	Dialogue does not exist
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

cURLTypeScript (fetch)PythonSDK

bash

curl -X PUT https://api.dialoguedb.com/dialogue/dlg_abc123xyz \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["support", "resolved"],
    "label": "Support Request #123",
    "state": { "step": "completed", "resolution": "refunded" },
    "message": { "role": "assistant", "content": "Your refund has been processed." }
  }'

typescript

const updated = await fetch(
  `https://api.dialoguedb.com/dialogue/${dialogueId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tags: ['support', 'resolved'],
      state: { status: 'completed' }
    })
  }
).then(r => r.json());

python

import requests

response = requests.put(
    f"https://api.dialoguedb.com/dialogue/{dialogue_id}",
    headers={
        "Authorization": "Bearer DIALOGUE_DB_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "tags": ["support", "resolved"],
        "label": "Resolved Support Ticket",
        "state": {"step": "completed", "resolution": "refunded"}
    }
)
updated = response.json()

typescript

const dialogue = await db.getDialogue(dialogueId);
dialogue.tags = ['support', 'resolved'];
dialogue.label = 'Resolved Support Ticket';
await dialogue.save();

List Dialogues

Retrieve dialogues with pagination and filtering.

Endpoint

http

GET /dialogue

Authentication

Bearer token (via Authorization header)

Query Parameters

Parameter	Type	Required	Description
`threadOf`	string	No	Parent dialogue ID — returns threads of this dialogue
`namespace`	string	No	Filter by namespace
`created`	string	No	Filter by creation date prefix (e.g. "2025", "2025-01", "2025-01-15")
`startDate`	string	No	Filter dialogues created on or after this date (ISO 8601)
`endDate`	string	No	Filter dialogues created before or on this date (ISO 8601)
`limit`	number	No	Max items to return per page
`order`	string	No	Sort order ("asc" or "desc")
`next`	string	No	Pagination token for next page

Response

typescript

{
  items: Dialogue[];
  next?: string; // Pagination token if more results exist
}

Behavior

Results scoped to your project
Sorted by creation date (descending by default)
Paginated automatically - use next cursor for additional pages
Filter to threads using threadOf parameter

Errors

Status	Error Code	Description
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

cURLTypeScript (fetch)PythonSDK

bash

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

typescript

const { items, next } = await fetch(
  'https://api.dialoguedb.com/dialogue?limit=20',
  {
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_API_KEY'
    }
  }
).then(r => r.json());

python

import requests

response = requests.get(
    "https://api.dialoguedb.com/dialogue",
    headers={
        "Authorization": "Bearer DIALOGUE_DB_API_KEY"
    },
    params={
        "limit": 20,
        "order": "desc"
    }
)
data = response.json()
items = data["items"]
next_token = data.get("next")

typescript

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

Get Dialogue

Retrieve dialogue metadata by ID with the first 10 messages.

Endpoint

http

GET /dialogue/{id}

Authentication

Bearer token (via Authorization header)

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Dialogue ID (identifier)

Response

typescript

{
  id: string;
  projectId: string;
  threadOf?: string; // If this dialogue is a thread
  threadCount?: number;
  totalMessages: number;
  lastMessageCreated?: string;
  status: "active" | "ended" | "archived";
  tags: string[];
  metadata: Record<string, any>;
  created: string;
  modified: string;
  messages: Message[];  // First 10 messages
}

Behavior

Returns dialogue with up to 10 most recent messages
For complete message history, use GET /dialogue/{id}/messages
totalMessages field shows total count (not just returned messages)

Errors

Status	Error Code	Description
400	`MISSING_PARAMETER`	Missing required dialogue ID
401	N/A	Unauthorized - invalid or missing API key
404	`DIALOGUE_NOT_FOUND`	Dialogue does not exist
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

cURLTypeScript (fetch)PythonSDK

bash

curl -X GET https://api.dialoguedb.com/dialogue/dlg_abc123xyz \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY"

typescript

const dialogue = await fetch(
  `https://api.dialoguedb.com/dialogue/${dialogueId}`,
  {
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_API_KEY'
    }
  }
).then(r => r.json());

python

import requests

response = requests.get(
    f"https://api.dialoguedb.com/dialogue/{dialogue_id}",
    headers={
        "Authorization": "Bearer DIALOGUE_DB_API_KEY"
    }
)
dialogue = response.json()

typescript

const dialogue = await db.getDialogue(dialogueId);

Delete Dialogue

Delete a dialogue by ID.

Endpoint

http

DELETE /dialogue/{id}

Authentication

Bearer token (via Authorization header)

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Dialogue ID (identifier)

Response

typescript

{
  success: boolean;
  id: string;
}

Behavior

Permanently deletes the dialogue
Messages within this dialogue remain accessible
Child threads (if any) remain accessible
This operation cannot be undone

Warnings

Irreversible: Deleted dialogues cannot be recovered
Messages persist: Use DELETE /dialogue/{id}/message/{messageId} to remove messages
Threads unaffected: Child threads remain as independent dialogues

POST /dialogue/{id}/end - Mark dialogue as ended (prevents further messages)
DELETE /dialogue/{id}/message/{messageId} - Delete individual messages

Ended Dialogues

After ending a dialogue, you cannot add new messages or update the dialogue. State can still be updated via PUT /dialogue/{id}/state. This action is reversible - contact support if needed.

Errors

Status	Error Code	Description
400	`MISSING_PARAMETER`	Missing required dialogue ID
401	N/A	Unauthorized - invalid or missing API key
404	`DIALOGUE_NOT_FOUND`	Dialogue does not exist
409	`DIALOGUE_IMMUTABLE`	Cannot delete immutable dialogue (check project settings)
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

cURLTypeScript (fetch)PythonSDK

bash

curl -X DELETE https://api.dialoguedb.com/dialogue/dlg_abc123xyz \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY"

typescript

const result = await fetch(
  `https://api.dialoguedb.com/dialogue/${dialogueId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_API_KEY'
    }
  }
).then(r => r.json());

python

import requests

response = requests.delete(
    f"https://api.dialoguedb.com/dialogue/{dialogue_id}",
    headers={
        "Authorization": "Bearer DIALOGUE_DB_API_KEY"
    }
)
result = response.json()

typescript

await db.deleteDialogue(dialogueId);

// Or via the direct API:
// import { api } from 'dialogue-db';
// await api.dialogue.remove({ id: dialogueId });

Dialogue Actions

Perform actions on a dialogue.

Endpoint

http

POST /dialogue/{id}/{action}

Authentication

Bearer token (via Authorization header)

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Dialogue ID (identifier)
`action`	string	Yes	Action to perform: "end" or "compact"

Actions

end

Marks the dialogue as ended/closed. Finalizes the conversation and returns updated dialogue state.

compact

Summarizes/compacts the dialogue. Generates a summary of the conversation, useful for reducing token count while preserving context.

Response

Action-specific response object.

Errors

Status	Error Code	Description
400	`MISSING_PARAMETER`	Missing required dialogue ID
400	`INVALID_ACTION`	Unsupported action (must be: end or compact)
401	N/A	Unauthorized - invalid or missing API key
404	`DIALOGUE_NOT_FOUND`	Dialogue does not exist
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

cURLTypeScript (fetch)PythonSDK

bash

# End dialogue
curl -X POST https://api.dialoguedb.com/dialogue/dlg_abc123xyz/end \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY"

# Compact dialogue
curl -X POST https://api.dialoguedb.com/dialogue/dlg_abc123xyz/compact \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY"

typescript

// End dialogue
const result = await fetch(
  `https://api.dialoguedb.com/dialogue/${dialogueId}/end`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_API_KEY'
    }
  }
).then(r => r.json());

// Compact dialogue
const summary = await fetch(
  `https://api.dialoguedb.com/dialogue/${dialogueId}/compact`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer DIALOGUE_DB_API_KEY'
    }
  }
).then(r => r.json());

python

import requests

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

# Compact dialogue
response = requests.post(
    f"https://api.dialoguedb.com/dialogue/{dialogue_id}/compact",
    headers={
        "Authorization": "Bearer DIALOGUE_DB_API_KEY"
    }
)
summary = response.json()

typescript

// End dialogue
await dialogue.end();

// Compact is not yet available in the SDK — use the REST API or direct API:
import { api } from 'dialogue-db';
await api.dialogue.action({ id: dialogueId, action: 'compact' });

Dialogues API ​

Create Dialogue ​

Endpoint ​

Authentication ​

Request Body ​

Response ​

Behavior ​

Which Fields Can Be Changed? ​

Constraints ​

Use Cases ​

Errors ​

Examples ​

Update Dialogue ​

Endpoint ​

Authentication ​

Path Parameters ​

Request Body ​

Response ​

Behavior ​

Errors ​

Examples ​

List Dialogues ​

Endpoint ​

Authentication ​

Query Parameters ​

Response ​

Behavior ​

Errors ​

Examples ​

Get Dialogue ​

Endpoint ​

Authentication ​

Path Parameters ​

Response ​

Behavior ​

Errors ​

Examples ​

Delete Dialogue ​

Endpoint ​

Authentication ​

Path Parameters ​

Response ​

Behavior ​

Warnings ​

Related Endpoints ​

Errors ​

Examples ​

Dialogue Actions ​

Endpoint ​

Authentication ​

Path Parameters ​

Actions ​

end ​

compact ​

Response ​

Errors ​

Examples ​

Dialogues API

Create Dialogue

Endpoint

Authentication

Request Body

Response

Behavior

Which Fields Can Be Changed?

Constraints

Use Cases

Errors

Examples

Update Dialogue

Endpoint

Authentication

Path Parameters

Request Body

Response

Behavior

Errors

Examples

List Dialogues

Endpoint

Authentication

Query Parameters

Response

Behavior

Errors

Examples

Get Dialogue

Endpoint

Authentication

Path Parameters

Response

Behavior

Errors

Examples

Delete Dialogue

Endpoint

Authentication

Path Parameters

Response

Behavior

Warnings

Related Endpoints

Errors

Examples

Dialogue Actions

Endpoint

Authentication

Path Parameters

Actions

end

compact

Response

Errors

Examples