Conversations

Create a conversation

Start a new conversation with your clone. Returns a conversation ID and the clone's initial greeting.

Endpoint: POST /v3/conversation

Request body:

Field	Type	Required	Description
user_email	string	No	Email of the user starting the chat

If user_email is provided, the conversation is linked to that user. Otherwise, it's created as an anonymous conversation.

Example request:

curl -X POST https://api.delphi.ai/v3/conversation \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"user_email": "[e-mail]"}'

Example response:

{
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-06-15T10:30:00.000Z",
  "initial_message": "Hey! How can I help you today?"
}

Stream a response

Send a message and receive the clone's response as a real-time stream (Server-Sent Events).

Endpoint: POST /v3/stream

Request body:

Field	Type	Required	Description
conversation_id	string	Yes	UUID of the conversation
message	string	Yes	The user's message
file_urls	string[]	No	URLs of user-uploaded files for context
slug	string	No	Your clone's slug

Example request:

curl -X POST https://api.delphi.ai/v3/stream \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message": "What are your top 3 tips for getting started?"
  }'

Response format: text/event-stream

The response is a stream of Server-Sent Events. Each event contains a chunk of the clone's response. The stream ends with a [DONE] event.

List conversations

Retrieve all conversations for a specific user.

Endpoint: GET /v3/conversation/list

Query parameters:

Parameter	Type	Required	Description
email	string	Yes	The user's email address

Example request:

curl "https://api.delphi.ai/v3/conversation/list?email=[e-mail]" \
  -H "x-api-key: YOUR_API_KEY"

Example response:

{
  "conversations": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Getting started tips",
      "created_at": "2025-06-15T10:30:00.000Z",
      "medium": "API"
    },
    {
      "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
      "title": null,
      "created_at": "2025-06-14T08:15:00.000Z",
      "medium": "API"
    }
  ]
}

Conversations are sorted by newest first. Only active (non-deleted) conversations are returned.

Get conversation history

Retrieve the full message history for a conversation.Endpoint: GET /v3/conversation/{conversation_id}/historyPath parameters:

Parameter	Type	Description
conversation_id	string	UUID of the conversation

Query parameters:

Parameter	Type	Required	Default	Description
include_citations	boolean	No	false	Include source citations

Example request:

curl "https://api.delphi.ai/v3/conversation/a1b2c3d4/history?include_citations=true" \
  -H "x-api-key: YOUR_API_KEY"

Example response:

{
  "messages": [
    {
      "id": "msg-001",
      "text": "Hey! How can I help you today?",
      "sender": "CLONE",
      "created_at": "2025-06-15T10:30:00.000Z",
      "citations": []
    },
    {
      "id": "msg-002",
      "text": "What are your top 3 tips?",
      "sender": "USER",
      "created_at": "2025-06-15T10:30:15.000Z",
      "citations": []
    },
    {
      "id": "msg-003",
      "text": "Great question! Here are my top 3 tips...",
      "sender": "CLONE",
      "created_at": "2025-06-15T10:30:20.000Z",
      "citations": [
        {
          "url": "https://example.com/article",
          "text": "Relevant excerpt from source",
          "type": "WEB",
          "title": "Source Article Title",
          "created_at": "2025-06-15T10:30:20.000Z"
        }
      ]
    }
  ]
}

Citation fields (when include_citations=true):

Field	Type	Description
url	string	Source URL
text	string	Relevant excerpt
type	string	Source type: WEB, PDF, TWITTER
title	string	Source title (nullable)
page_num	number	PDF page number (nullable)
timestamp	number	Video/audio timestamp (nullable)
tweet_id	string	Tweet ID (nullable)
citation_url	string	Direct citation link (nullable)

Messages are returned in chronological order (oldest first).

Update conversation title

Set or update the title of a conversation.

Endpoint: PUT /v3/conversation/{conversation_id}/title

Path parameters:

Parameter	Type	Description
conversation_id	string	UUID of the conversation

Request body:

Field	Type	Required	Description
title	string	Yes	New title (1–500 characters)

Example request:

curl -X PUT "https://api.delphi.ai/v3/conversation/a1b2c3d4/title" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"title": "Getting started tips"}'

Example response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Getting started tips",
  "updated_at": "2025-06-15T11:00:00.000Z"
}

Append a clone message

Add a clone message to an existing conversation. Useful for seeding conversations or injecting a custom clone message mid-conversation.

Endpoint: POST /v3/conversation/{conversation_id}/append-clone-message

Path parameters:

Parameter	Type	Description
conversation_id	string	UUID of the conversation

Request body:

Field	Type	Required	Description
text	string	Yes	Message text (1–50,000 characters)

Example request:

curl -X POST "https://api.delphi.ai/v3/conversation/a1b2c3d4/append-clone-message" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"text": "Welcome! Here are some things you can ask me about."}'

Example response:

{
  "message_id": "1dababb1-ef17-4f9f-8ab6-a5d7c4291c12",
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "text": "Welcome! Here are some things you can ask me about.",
  "sender": "CLONE",
  "created_at": "2025-06-15T10:30:00.000Z"
}

Delete a conversation

Soft-delete a conversation. It will no longer appear in list results.

Endpoint: DELETE /v3/conversation/{conversation_id}

Path parameters:

Parameter	Type	Description
conversation_id	string	UUID of the conversation

Example request:

curl -X DELETE "https://api.delphi.ai/v3/conversation/a1b2c3d4" \
  -H "x-api-key: YOUR_API_KEY"

Example response:

{
  "status": "archived"
}

This is a soft delete — the conversation is hidden, not permanently removed.