# Conversations API

The Conversations API provides Eos Chat for an API Client. A conversation preserves bounded, thread-scoped context across messages and uses the same skills, Roles, license rules, and Run authorization as Agents.

## Actor and optional member subject

The API Client is always the actor. A conversation may optionally be created with one member subject for skills that support “my” semantics, such as “show my open tasks.” The subject is fixed for the conversation.

```json
{
  "subject": {"member_id": "alice@example.com"}
}
```

The `member_id` is the member's normalized email address. Eos requires an exact active member match inside the API Client's organization and does not treat possession of an email address as authorization. The subject contributes no Roles, project access, personal connections, or delegated identity.

## Create a conversation

`POST /v1/conversations`

Operation ID: `createConversation`. Required header: `Idempotency-Key`.

```json
{
  "title": "Weekly project review",
  "subject": {"member_id": "alice@example.com"},
  "metadata": {"external_thread_id": "slack-18291"}
}
```

## List and get conversations

- `GET /v1/conversations` — `listConversations`
- `GET /v1/conversations/{conversation_id}` — `getConversation`

Filters: `status`, `subject_member_id`, `updated_after`, `limit`, and `after`. A client sees only its own conversations.

## List messages

`GET /v1/conversations/{conversation_id}/messages`

Operation ID: `listConversationMessages`. Messages are cursor-paginated in chronological order and contain structured content blocks such as `text`, `data`, `file_reference`, `citation`, and `error`.

## Send a message

`POST /v1/conversations/{conversation_id}/messages`

Operation ID: `createConversationMessage`. Required header: `Idempotency-Key`.

```json
{
  "content": [
    {"type": "text", "text": "Summarize overdue tasks and draft follow-up notes."}
  ]
}
```

Returns `202 Accepted` with the user message and a [Run](runs.html). The assistant response becomes a message when the Run completes. Clients may poll, stream Run events, or subscribe to `conversation.message.created` and `run.completed` webhooks.

## Context behavior

Context is conversation-scoped and bounded. Working context expires after 30 days without conversation activity and may contain compact projections of prior messages and tool results, not an unlimited transcript. Message and audit retention follows the organization's Eos retention policy. Clients must not assume that every prior token remains available. Starting a new conversation creates a clean context boundary.

## Archive and clear context

- `POST /v1/conversations/{conversation_id}/archive` — `archiveConversation`
- `POST /v1/conversations/{conversation_id}/clear-context` — `clearConversationContext`

Both require `Idempotency-Key`. Clearing context preserves the auditable message history but prevents earlier messages from being supplied as working context to later Runs. Neither operation deletes audit records.

## Safety boundaries

Eos Chat cannot exceed the API Client's effective permissions, use members' personal provider connections, or perform a formal approval. Tool operations retain the API Client as actor and identify the originating conversation and Run in the audit trail.

## Common errors

`CONVERSATION_NOT_FOUND`, `CONVERSATION_ARCHIVED`, `SUBJECT_NOT_FOUND`, `SUBJECT_AMBIGUOUS`, `SUBJECT_NOT_SUPPORTED`, `MESSAGE_CONTENT_INVALID`, and `CONTEXT_LIMIT_EXCEEDED`.

Next: [Custom Fields API](custom-fields.html).