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

```bash
curl -X POST https://api.delphi.ai/v3/conversation \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"user_email": "user@example.com"}'
```

**Example response:**

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

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

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

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

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

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

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

The question should be specific, self-contained, and written in natural language.
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.