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