> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations

> Group related messages into conversations to maintain context and history across chat sessions. Create, update, and query conversations via the API.

Conversations provide a way to group related messages and interactions within your application. Each conversation acts as a container that maintains context and history for a specific chat session.

## Use Cases

* **Customer support chats**: Track individual support sessions
* **Multi-turn agent interactions**: Maintain context across agent executions
* **User chat history**: Organize conversations by user or session

## Quick Start

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from '@orq-ai/node';

  const orq = new Orq({ apiKey: process.env.ORQ_API_KEY });

  // Create a conversation
  const conversation = await orq.conversations.create({
    displayName: 'Support Chat #1234',
  });

  // List all conversations
  const { data } = await orq.conversations.list({ limit: 10 });

  // Retrieve a specific conversation
  const retrieved = await orq.conversations.retrieve(conversation._id);

  // Update the display name
  await orq.conversations.update(conversation._id, {
    displayName: 'Resolved: Support Chat #1234',
  });

  // Delete when no longer needed
  await orq.conversations.delete(conversation._id);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

  # Create a conversation
  conversation = orq.conversations.create(display_name="Support Chat #1234")

  # List all conversations
  conversations = orq.conversations.list(limit=10)

  # Retrieve a specific conversation
  retrieved = orq.conversations.retrieve(conversation.id)

  # Update the display name
  orq.conversations.update(
      conversation.id,
      display_name="Resolved: Support Chat #1234"
  )

  # Delete when no longer needed
  orq.conversations.delete(conversation.id)
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  # Create
  curl -X POST https://api.orq.ai/v2/conversations \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"displayName": "Support Chat #1234"}'

  # List
  curl https://api.orq.ai/v2/conversations?limit=10 \
    -H "Authorization: Bearer $ORQ_API_KEY"

  # Retrieve
  curl https://api.orq.ai/v2/conversations/conv_01jj1hdhn79xas7a01wb3hysdb \
    -H "Authorization: Bearer $ORQ_API_KEY"

  # Update
  curl -X PATCH https://api.orq.ai/v2/conversations/conv_01jj1hdhn79xas7a01wb3hysdb \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"displayName": "Resolved: Support Chat #1234"}'

  # Delete
  curl -X DELETE https://api.orq.ai/v2/conversations/conv_01jj1hdhn79xas7a01wb3hysdb \
    -H "Authorization: Bearer $ORQ_API_KEY"
  ```
</CodeGroup>

## Conversation Object

| Field         | Type   | Description                               |
| ------------- | ------ | ----------------------------------------- |
| `_id`         | string | Unique identifier (prefixed with `conv_`) |
| `kind`        | string | Always `"conversation"`                   |
| `displayName` | string | Human-readable name (1-100 chars)         |
| `createdAt`   | number | Unix timestamp (ms)                       |
| `updatedAt`   | number | Unix timestamp (ms)                       |
| `createdById` | string | Creator identifier (optional)             |
| `updatedById` | string | Last updater identifier (optional)        |

## Pagination

List endpoints support cursor-based pagination:

| Parameter        | Description                            |
| ---------------- | -------------------------------------- |
| `limit`          | Number of results (1-100, default: 10) |
| `starting_after` | Cursor for forward pagination          |
| `ending_before`  | Cursor for backward pagination         |

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Get next page
const page1 = await orq.conversations.list({ limit: 10 });
const page2 = await orq.conversations.list({
  limit: 10,
  starting_after: page1.data[page1.data.length - 1]._id,
});
```

## API Reference

<CardGroup cols={2}>
  <Card title="List Conversations" href="/reference/conversations/list-conversations">
    Retrieve paginated list of conversations
  </Card>

  <Card title="Create Conversation" href="/reference/conversations/create-conversation">
    Create a new conversation
  </Card>

  <Card title="Retrieve Conversation" href="/reference/conversations/retrieve-conversation">
    Get a specific conversation by ID
  </Card>

  <Card title="Update Conversation" href="/reference/conversations/update-conversation">
    Modify conversation properties
  </Card>

  <Card title="Delete Conversation" href="/reference/conversations/delete-conversation">
    Permanently remove a conversation
  </Card>
</CardGroup>