> For the complete documentation index, see [llms.txt](https://docs.delphi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.delphi.ai/advanced/actions/api-immortal-only/conversations.md).

# 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:**

<table><thead><tr><th width="199.74609375">Field</th><th width="110.4453125">Type</th><th width="110.48046875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>slug</code></td><td>string</td><td>No</td><td>Which Mind to start the conversation with. Defaults to the API key's Mind.</td></tr><tr><td><code>user_email</code></td><td>string</td><td>No</td><td>Email of the user starting the chat</td></tr><tr><td><code>overrides</code></td><td>object</td><td>No</td><td>Per-conversation experience overrides. See the table below.</td></tr></tbody></table>

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

**`Overrides` object:**

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

> 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:**

<pre class="language-bash"><code class="lang-bash">curl -X POST "https://api.delphi.ai/v3/conversation" \
<strong>  -H "Content-Type: application/json" \
</strong>  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "user_email": "customer@example.com",
    "overrides": {
      "purpose": "You are helping the user with a billing issue. Be concise and direct.",
      "default_language": "es",
      "multiple_languages": false
    }
  }'
</code></pre>

**Example response:**

```json
{
  "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:**&#x20;

<table><thead><tr><th width="200.05078125">Field</th><th width="109.56640625">Type</th><th width="110.46484375">Requires</th><th>Descriptions</th></tr></thead><tbody><tr><td><code>question</code></td><td>string</td><td><strong>Yes</strong></td><td>The question to answer. 1–50,000 characters.</td></tr><tr><td><code>slug</code></td><td>string</td><td>No</td><td>Which Mind to ask. Defaults to the API key's Mind.</td></tr><tr><td><code>user_email</code></td><td>string</td><td>No</td><td>Loads this visitor's memory into the answer. Omit for a fully anonymous, memory-free answer.</td></tr><tr><td><code>file_urls</code></td><td>array of string</td><td>No</td><td>Up to 10 file URLs. Indexed the same way as chat uploads before the answer is generated.</td></tr></tbody></table>

**Response:**

<table><thead><tr><th width="200.49609375">Field</th><th width="109.99609375">Type</th><th>Descriptions</th></tr></thead><tbody><tr><td><code>answer</code></td><td>string</td><td>The Mind's answer. </td></tr><tr><td><code>citations</code></td><td>array of object</td><td>Sources backing the answer (same citation shape as conversation history — see below).</td></tr></tbody></table>

**Citation fields** (each item in `citations`)

<table><thead><tr><th width="199.98046875">Field</th><th width="109.9765625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Citation type.</td></tr><tr><td><code>text</code></td><td>string</td><td>Cited text/snippet.</td></tr><tr><td><code>title</code></td><td>string</td><td>Source title (nullable).</td></tr><tr><td><code>url</code></td><td>string</td><td>Source URL (nullable).</td></tr><tr><td><code>citation_url</code></td><td>string</td><td>Direct link to the cited location (nullable).</td></tr><tr><td><code>page_num</code></td><td>number</td><td>Page number for document sources (nullable).</td></tr><tr><td><code>timestamp</code></td><td>number</td><td>Timestamp for audio/video sources (nullable).</td></tr><tr><td><code>tweet_id</code></td><td>string</td><td>Tweet ID for tweet sources (nullable).</td></tr><tr><td><code>created_at</code></td><td>string</td><td>When the source was created (nullable).</td></tr></tbody></table>

**Example request:**

```bash
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": "customer@example.com"
  }'
```

**Example response:**

```json
{
  "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:**

<table><thead><tr><th width="199.7890625">Field</th><th width="110.10546875">Type</th><th width="109.72265625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>conversation_id</code></td><td>string</td><td>Yes</td><td>UUID of the conversation</td></tr><tr><td><code>message</code></td><td>string</td><td>Yes</td><td>The user's message</td></tr><tr><td><code>file_urls</code></td><td>string[]</td><td>No</td><td>URLs of user-uploaded files for context</td></tr><tr><td><code>slug</code></td><td>string</td><td>No</td><td>Your clone's slug</td></tr></tbody></table>

**Example request:**

```bash
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:**

```bash
curl "https://api.delphi.ai/v3/conversation/list?email=user@example.com" \
  -H "x-api-key: YOUR_API_KEY"
```

**Example response:**

```json
{
  "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 <a href="#get-conversation-history" id="get-conversation-history"></a>

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

| Parameter         | Type   | Description              |
| ----------------- | ------ | ------------------------ |
| `conversation_id` | string | UUID of the conversation |

**Query parameters:**

<table data-header-hidden><thead><tr><th>Parameter</th><th>Type</th><th width="110.46484375">Required</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><code>include_citations</code></td><td>boolean</td><td>No</td><td>false</td><td>Include source citations</td></tr></tbody></table>

**Example request:**

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

**Example response:**

```json
{
  "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`):

<table><thead><tr><th width="199.62890625">Field</th><th width="110.48046875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>url</code></td><td>string</td><td>Source URL</td></tr><tr><td><code>text</code></td><td>string</td><td>Relevant excerpt</td></tr><tr><td><code>type</code></td><td>string</td><td>Source type: <code>WEB</code>, <code>PDF</code>, <code>TWITTER</code></td></tr><tr><td><code>title</code></td><td>string</td><td>Source title (nullable)</td></tr><tr><td><code>page_num</code></td><td>number</td><td>PDF page number (nullable)</td></tr><tr><td><code>timestamp</code></td><td>number</td><td>Video/audio timestamp (nullable)</td></tr><tr><td><code>tweet_id</code></td><td>string</td><td>Tweet ID (nullable)</td></tr><tr><td><code>citation_url</code></td><td>string</td><td>Direct citation link (nullable)</td></tr></tbody></table>

> 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:**

<table><thead><tr><th width="200.3671875">Field</th><th width="108.828125">Type</th><th width="109.94140625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>conversation_id</code></td><td>string</td><td><strong>Yes</strong></td><td>The conversation's ID.</td></tr></tbody></table>

**Response:**&#x20;

Returns an object with an `insights` array. Each item:

<table><thead><tr><th width="200.3671875">Field</th><th width="109.62109375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>string</td><td>Insight ID.</td></tr><tr><td><code>created_at</code></td><td>string</td><td>When the insight was created (ISO 8601).</td></tr><tr><td><code>data</code></td><td>object</td><td>The insight card. Fields below.</td></tr></tbody></table>

**`Data` (insight card) fields:**&#x20;

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

**Example request:**

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

**Example response:**

```json
{
  "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:**

```bash
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:**

```json
{
  "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.&#x20;

**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:**

```bash
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:**

```json
{
  "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:**

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

**Example response:**

```json
{
  "status": "archived"
}
```

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.delphi.ai/advanced/actions/api-immortal-only/conversations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.