logo
Casey AIConversations

Conversations

Manage conversation history — list, create, and retrieve conversations with messages.

Casey persists conversations so users can resume chats across page navigations and sessions.

GET /api/conversations

List the current user's conversations, ordered by most recent activity.

Response

{
  "conversations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Portfolio questions",
      "page_context": "portfolio",
      "deal_name": null,
      "created_at": "2026-02-12T14:30:00Z",
      "updated_at": "2026-02-12T15:45:00Z",
      "message_count": 8
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "title": "Acme Corp due diligence",
      "page_context": "deal",
      "deal_name": "Acme Corp",
      "created_at": "2026-02-11T10:00:00Z",
      "updated_at": "2026-02-11T10:15:00Z",
      "message_count": 4
    }
  ]
}

POST /api/conversations

Create a new empty conversation. Usually you don't need this — sending a chat message without a conversation_id will auto-create one. Use this only if you need to pre-create a conversation for UI purposes.

Request Body

{
  "title": "New chat",
  "context": {
    "page": "deal",
    "deal_id": 123,
    "deal_name": "Acme Corp"
  }
}

Response

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "title": "New chat",
  "page_context": "deal",
  "deal_name": "Acme Corp",
  "created_at": "2026-02-12T16:00:00Z",
  "updated_at": "2026-02-12T16:00:00Z",
  "message_count": 0
}

GET /api/conversations/{id}

Get a single conversation including its full message history.

Response

{
  "conversation": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Portfolio questions",
    "page_context": "portfolio",
    "deal_name": null,
    "created_at": "2026-02-12T14:30:00Z",
    "updated_at": "2026-02-12T15:45:00Z",
    "messages": [
      {
        "role": "user",
        "content": "How many investments do I have?",
        "created_at": "2026-02-12T14:30:00Z"
      },
      {
        "role": "assistant",
        "content": "You have **3 active investments** totaling $45,000...",
        "created_at": "2026-02-12T14:30:05Z",
        "widgets": [{ "type": "portfolio_overview" }],
        "citations": null
      }
    ]
  }
}

Message Object

FieldTypeDescription
role"user" | "assistant"Who sent the message
contentstringThe message text (Markdown for assistant). May contain [N] citation markers
created_atstringISO 8601 timestamp
widgetsarray | nullWidget hints that were emitted during this response (assistant only)
citationsarray | nullSource citations for [N] markers in the message (assistant only). See below

Citations

When an assistant message includes information from web search or platform documentation, the citations array maps [N] markers in the message text to their sources.

[
  {
    "index": 1,
    "title": "Play Money Fees",
    "url": "https://docs.playmoney.com/fees",
    "source_type": "platform_docs"
  },
  {
    "index": 2,
    "title": "TechCrunch Article",
    "url": "https://techcrunch.com/...",
    "source_type": "web"
  }
]
FieldTypeDescription
indexnumberMatches [N] in the message text
titlestringHuman-readable source title
urlstringLink to the source
source_type"web" | "platform_docs"Where the source came from

Frontend: Parse [N] markers in the message Markdown and render them as small clickable links/badges using the matching citation entry.

Casey includes [deal:ID] markers next to every deal name mentioned in a response. The frontend should parse these and render the deal name as a clickable link to the deal page.

Example message content:

**Bold Reuse** [deal:42] is a sustainable packaging company...

Frontend: Use a regex like /\[deal:(\d+)\]/g to find deal markers, strip them from the visible text, and wrap the preceding deal name in a link to /deals/{id} (or your deal page route).

Conversation Lifecycle

The conversation_id returned in the metadata SSE event is the source of truth. Always store it after the first message and send it with subsequent messages.

Context Updates

If a user navigates to a different page mid-conversation and sends a message, the new context in the request body will update the conversation's stored context. Casey will adjust its awareness accordingly.

Starting Fresh

To start a new conversation, either:

  • Omit conversation_id from the request
  • Set create_new_conversation: true (ignores any provided conversation_id)
Was this page helpful?

Last updated Mar 26, 2026

Built with Documentation.AI