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
slug	string	No	Which Mind to start the conversation with. Defaults to the API key's Mind.
user_email	string	No	Email of the user starting the chat
overrides	object	No	Per-conversation experience overrides. See the table below.

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

Overrides object:

Field	Type	Required	Description
purpose	string	No	Overrides the Mind's default purpose/instructions for this conversation only. Max 10,000 characters.
default_language	string	No	BCP-47 language code the Mind should respond in by default (e.g. "es", "fr", "pt-BR").
multiple_languages	boolean	No	When false and default_language is set, the Mind always answers in default_language regardless of the language the user writes in. Defaults to allowing the Mind to match the user's language.

Overrides are per-conversation and merge on top of the Mind's channel-level settings — any key you set here wins; keys you omit fall back to the Mind's defaults.

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]",
    "overrides": {
      "purpose": "You are helping the user with a billing issue. Be concise and direct.",
      "default_language": "es",
      "multiple_languages": false
    }
  }'

Example response:

{
  "conversation_id": "b3d1c0a2-5e4f-4a1b-9c8d-7e6f5a4b3c2d",
  "created_at": "2026-07-22T18:00:00.000Z",
  "initial_message": "Hi, ask me anything."
}

Ask a one-off question

Endpoint: POST /v3/conversation/ask

Generate a single answer without creating or using a conversation. Use this for stateless Q&A. If you pass user_email, the Mind loads that visitor's memory (summary, known facts, cross-conversation context) for the answer.

Request body:

Field	Type	Requires	Descriptions
question	string	Yes	The question to answer. 1–50,000 characters.
slug	string	No	Which Mind to ask. Defaults to the API key's Mind.
user_email	string	No	Loads this visitor's memory into the answer. Omit for a fully anonymous, memory-free answer.
file_urls	array of string	No	Up to 10 file URLs. Indexed the same way as chat uploads before the answer is generated.

Response:

Field	Type	Descriptions
answer	string	The Mind's answer.
citations	array of object	Sources backing the answer (same citation shape as conversation history — see below).

Citation fields (each item in citations)

Field	Type	Description
type	string	Citation type.
text	string	Cited text/snippet.
title	string	Source title (nullable).
url	string	Source URL (nullable).
citation_url	string	Direct link to the cited location (nullable).
page_num	number	Page number for document sources (nullable).
timestamp	number	Timestamp for audio/video sources (nullable).
tweet_id	string	Tweet ID for tweet sources (nullable).
created_at	string	When the source was created (nullable).

Example request:

curl -X POST "https://api.delphi.ai/v3/conversation/ask" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "question": "What is your refund policy?",
    "user_email": "[e-mail]"
  }'

Example response:

{
  "answer": "Refunds are available within 30 days of purchase...",
  "citations": [
    {
      "type": "content",
      "text": "Customers may request a full refund within 30 days.",
      "title": "Refund Policy",
      "url": "https://example.com/refund-policy",
      "citation_url": "https://example.com/refund-policy#section-2",
      "page_num": null,
      "timestamp": null,
      "tweet_id": null,
      "created_at": null
    }
  ]
}

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:

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

Get insights for a conversation

Endpoint: POST /v3/conversation/{conversation_id}/insights

Returns the insight cards generated for a conversation, newest first. Insight cards are surfaced by Delphi's synthesis (e.g. a notable testimonial, or a user worth meeting) and are attached to the conversation they came from.

Path parameters:

Field	Type	Required	Description
conversation_id	string	Yes	The conversation's ID.

Response:

Returns an object with an insights array. Each item:

Field	Type	Description
id	string	Insight ID.
created_at	string	When the insight was created (ISO 8601).
data	object	The insight card. Fields below.

Data (insight card) fields:

Field	Type	Description
type	string	Card type: "testimonial" or "user_worth_meeting".
description	string	Human-readable summary of the insight.
reasoning	array of string	Why this insight was surfaced.
items	array of string	Supporting bullet points (nullable).
ctaType	string	Suggested call-to-action type (e.g. share_socials, reply_to_user, view_conversation).
ctaLabel	string	Display label for the CTA.
ctaData	object	Arbitrary data for the CTA.
evidence	array of object	Supporting evidence. Each has a type of CONVERSATION, USER, or CONTENT plus fields for that type.
compositeScore	number	Confidence/priority score between 0 and 1.
period	string	The time period the insight covers.
createdAt	string	Card creation timestamp (ISO 8601).

Example request:

curl "https://api.delphi.ai/v3/conversation/b3d1c0a2-5e4f-4a1b-9c8d-7e6f5a4b3c2d/insights" \
  -H "x-api-key: YOUR_API_KEY"

Example response:

{
  "insights": [
    {
      "id": "insight_01H...",
      "created_at": "2026-07-22T18:30:00.000Z",
      "data": {
        "type": "testimonial",
        "description": "Customer praised the onboarding experience.",
        "reasoning": ["Strong positive sentiment", "Names a specific outcome"],
        "items": ["Loved the setup flow", "Would recommend to peers"],
        "ctaType": "share_socials",
        "ctaLabel": "Share this testimonial",
        "ctaData": {},
        "evidence": [
          {
            "type": "CONVERSATION",
            "threadId": "b3d1c0a2-5e4f-4a1b-9c8d-7e6f5a4b3c2d",
            "threadSessionId": "sess_123",
            "summary": "User described a smooth onboarding.",
            "sourceMessageId": "msg_456"
          }
        ],
        "compositeScore": 0.82,
        "period": "2026-07",
        "createdAt": "2026-07-22T18:30:00.000Z"
      }
    }
  ]
}

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.