Eos Developers
Design target — not live yet. This documentation defines the contract Eos will implement. Existing internal application APIs are not part of this contract.

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.

{
  "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.

{
  "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.

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

Returns 202 Accepted with the user message and a Run. 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.