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

# Conversations

> Chat with Addison over the API: start conversations, stream responses, recover dropped streams, and submit feedback.

A conversation is scoped to one project at creation and that binding is fixed, exactly as it is in the app. Everything Addison can see comes from that project's data, files, and knowledge, so [attach what you need](/api/projects-and-files) before you start asking.

Responses stream as server-sent events. Send `Accept: text/event-stream` and set client timeouts to at least 120 seconds.

Product-side docs: [Addison](/features/addison).

<CardGroup cols={2}>
  <Card title="POST /v1/projects/{project_id}/conversations" icon="code" href="/api-reference/conversations/create-conversation-and-stream-response" horizontal>
    Start a conversation and stream the response.
  </Card>

  <Card title="POST /v1/projects/{project_id}/conversations/{chat_id}/messages" icon="code" href="/api-reference/conversations/create-message-and-stream-response" horizontal>
    Send a follow-up and stream the reply.
  </Card>

  <Card title="GET /v1/projects/{project_id}/conversations" icon="code" href="/api-reference/conversations/list-conversations" horizontal>
    List conversations.
  </Card>

  <Card title="GET /v1/projects/{project_id}/conversations/{chat_id}" icon="code" href="/api-reference/conversations/show-conversation" horizontal>
    Fetch a conversation and its messages.
  </Card>

  <Card title="GET /v1/chat-models" icon="code" href="/api-reference/conversations/list-chat-models" horizontal>
    List available models and the effort levels each supports.
  </Card>

  <Card title="POST /v1/projects/{project_id}/files/uploads" icon="code" href="/api-reference/files/create-a-presigned-upload" horizontal>
    Upload a file into the project a conversation reads from.
  </Card>
</CardGroup>

**Recovering a dropped stream.** If the connection drops mid-response, don't re-send the message. Re-stream the events you missed instead:

<Card title="GET /v1/projects/{project_id}/conversations/{chat_id}/messages/{message_id}/events" icon="code" href="/api-reference/conversations/stream-message-events" horizontal>
  Re-stream a message's events after a dropped connection.
</Card>

**Sending while Addison is busy.** A conversation runs one message at a time. If you send while a previous message is still running, `on_busy` decides what happens:

* `on_busy: "queue"` (the default) durably queues your message to run next. The reply stream opens immediately with a `status` event carrying `message: "queued"`, its `queuedMessageId`, and its `position`; heartbeats keep the connection alive; then the reply streams once the turn dispatches. Keep the connection open — a queued reply waits as long as the message ahead of it runs.
* `on_busy: "reject"` returns a `409` with code `conversation_busy` and the `activeMessageId` instead, so you can wait and retry yourself.

These fields apply to follow-up messages; starting a conversation never waits, because a new conversation is never busy. While your message waits, `queue.updated` events report its position, and `held: true` if a Stop paused the queue — it will not run until the queue is resumed.

On follow-up messages, send a stable `idempotency_key` per logical message so a retry resumes the same queued message rather than creating a duplicate. If the connection drops before the queued message has bound an assistant message id, reconnect by re-sending with the same `idempotency_key`, or poll the queued message directly. Starting a conversation is not retry-safe: a retry after a lost response can create a second conversation.

<CardGroup cols={2}>
  <Card title="GET /v1/projects/{project_id}/conversations/{chat_id}/queue" icon="code" href="/api-reference/conversations/list-conversation-queue" horizontal>
    List the messages waiting to run.
  </Card>

  <Card title="GET /v1/projects/{project_id}/conversations/{chat_id}/queue/{queued_message_id}" icon="code" href="/api-reference/conversations/show-queued-message" horizontal>
    Show one queued message and its bound reply once it starts.
  </Card>

  <Card title="POST /v1/projects/{project_id}/conversations/{chat_id}/messages/{message_id}/cancel" icon="code" href="/api-reference/conversations/cancel-analyst-reply" horizontal>
    Stop an in-progress reply (needs `confirm=true`). Pauses the queue if messages are waiting.
  </Card>

  <Card title="POST /v1/projects/{project_id}/conversations/{chat_id}/queue/resume" icon="code" href="/api-reference/conversations/resume-conversation-queue" horizontal>
    Resume a queue that a Stop paused.
  </Card>

  <Card title="DELETE /v1/projects/{project_id}/conversations/{chat_id}/queue/{queued_message_id}" icon="code" href="/api-reference/conversations/withdraw-queued-message" horizontal>
    Withdraw a waiting message before it runs (needs `confirm=true`).
  </Card>
</CardGroup>

`GET /v1/projects/{project_id}/conversations/{chat_id}` also reports `activeTurn`, `queuedTurns`, and `queueHeld` so you can see what is running and waiting.

**Rating a response.** The thumbs-up / thumbs-down controls in the app are this endpoint:

<Card title="POST /v1/projects/{project_id}/conversations/{chat_id}/messages/{message_id}/feedback" icon="code" href="/api-reference/conversations/submit-message-feedback" horizontal>
  Submit feedback on an assistant message.
</Card>

<Note>
  Invoking a `/` [skill](/features/addison#skills) directly from the API is not supported yet. Describe the job in the message instead.
</Note>