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
`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 (immutable 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
messages[] treated as history and added first (in order)
message (singular) added after messages[] if both provided
Maximum 25 messages in initial creation
Returns dialogue with created messages

Field Mutability

User-settable on creation:

namespace - Optional namespace for user isolation
threadOf - Parent dialogue reference
tags - Categorization tags
metadata - Custom metadata (⚠️ immutable after creation)
messages/message - Initial conversation history
state - Initial state data

System-managed (read-only):

id - Auto-generated identifier
projectId - Your project identifier
status - Dialogue status (active, ended, canceled, expired)
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 is immutable 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 are immutable after creation
Dialogue IDs are auto-generated

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

Create Simple DialogueCreate ThreadTypeScriptSDK

bash

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

bash

curl -X POST https://api.dialoguedb.com/dialogue \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "threadOf": "dlg_abc123xyz",
    "message": {"role": "user", "content": "Follow-up question"}
  }'

typescript

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

typescript

const dialogue = await client.dialogues.create({
  message: {
    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 (PATCH semantics)
Metadata cannot be updated - it is immutable after dialogue creation
Cannot modify existing messages or status through this endpoint

Metadata Immutability

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

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

cURL - Update tagscURL - Update state and add messageTypeScriptSDK

bash

curl -X PUT https://api.dialoguedb.com/dialogue/dlg_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["support", "resolved"],
    "label": "Support Request #123"
  }'

bash

curl -X PUT https://api.dialoguedb.com/dialogue/dlg_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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 YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tags: ['support', 'resolved'],
      state: { status: 'completed' }
    })
  }
).then(r => r.json());

typescript

const updated = await client.dialogues.update(dialogueId, {
  tags: ['support', 'resolved'],
  label: 'Resolved Support Ticket'
});

List Dialogues

Retrieve dialogues with pagination and filtering.

Endpoint

http

GET /dialogue

Authentication

Bearer token (via Authorization header)

Query Parameters

Parameter	Type	Required	Description
`query`	string	No	Query template (default: "default", use "threads" for thread listing)
`threadOf`	string	No	Parent dialogue ID (when query="threads")
`namespace`	string	No	Filter by namespace
`date`	string	No	Filter by date
`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

List Root DialoguesList ThreadsTypeScriptSDK

bash

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

bash

curl -X GET "https://api.dialoguedb.com/dialogue?query=threads&threadOf=dlg_abc123xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"

typescript

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

typescript

const { items, next } = await client.dialogues.list({
  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" | "canceled" | "expired" | "deleted";
  expired: boolean;
  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

cURLTypeScriptSDK

bash

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

typescript

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

typescript

const dialogue = await client.dialogues.get(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}/messages/{messageId} to remove messages
Threads unaffected: Child threads remain as independent dialogues

PUT /dialogue/{id}/end - Mark dialogue as ended (prevents further messages)
DELETE /dialogue/{dialogueId}/messages/{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

cURLTypeScriptSDK

bash

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

typescript

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

typescript

await client.dialogues.delete(dialogueId);

Dialogue Actions

Perform actions on a dialogue.

Endpoint

http

PUT /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", "compact", or "continue"

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.

continue

Creates a new dialogue continuing from this one. (Note: Currently returns empty object, future implementation planned)

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, compact, or continue)
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

End DialogueCompact DialogueTypeScriptSDK

bash

curl -X PUT https://api.dialoguedb.com/dialogue/dlg_abc123xyz/end \
  -H "Authorization: Bearer YOUR_API_KEY"

bash

curl -X PUT https://api.dialoguedb.com/dialogue/dlg_abc123xyz/compact \
  -H "Authorization: Bearer YOUR_API_KEY"

typescript

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

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

typescript

// End dialogue
await client.dialogues.action(dialogueId, 'end');

// Compact dialogue
const summary = await client.dialogues.action(dialogueId, 'compact');

Dialogues API ​

Create Dialogue ​

Endpoint ​

Authentication ​

Request Body ​

Response ​

Behavior ​

Field Mutability ​

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 ​

continue ​

Response ​

Errors ​

Examples ​

Dialogues API

Create Dialogue

Endpoint

Authentication

Request Body

Response

Behavior

Field Mutability

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

continue

Response

Errors

Examples