Chat API

Send messages and receive AI-generated responses grounded in your content. The Chat API enables conversational interactions with automatic context retrieval and source citations.

Send message

Sends a user message and receives an AI-generated response with relevant resources from your content library.

POST/widget/chat

Request body

messagestringrequired

The user's question or message.

session_tokenstring

Token from a previous response for conversation continuity.

page_contextstring

Current page URL for context-aware responses.

Response

answerstring

AI-generated response grounded in your content.

resourcesarray

Content items used to generate the response.

session_tokenstring

Token for maintaining conversation context.

query_typestring

Classified query type.

dosingside_effectspatient_supportstorageinsurancegeneral

Request

curl -X POST https://api.isomera.ai/api/v1/widget/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wk_your_api_key" \
  -d '{
    "message": "What are the side effects?",
    "session_token": "sess_abc123def456"
  }'

Response

{
  "answer": "The most common side effects include nausea, diarrhea, and decreased appetite. These are usually mild and improve over time.",
  "resources": [
    {
      "type": "webpage",
      "title": "Common Side Effects",
      "url": "https://example.com/side-effects",
      "section_type": "side_effects"
    },
    {
      "type": "youtube",
      "title": "Managing Side Effects",
      "video_id": "abc123",
      "timestamp_seconds": 134,
      "timestamp_display": "2:14"
    }
  ],
  "session_token": "sess_abc123def456",
  "query_type": "side_effects"
}

Create session

Creates a new chat session and returns widget configuration.

POST/widget/session

Query parameters

page_contextstring

Page URL where session started.

Request

curl -X POST https://api.isomera.ai/api/v1/widget/session \
  -H "X-API-Key: wk_your_api_key"

Response

{
  "session_token": "sess_abc123def456ghi789",
  "client_name": "Acme Therapeutics",
  "welcome_message": "Hi! How can I help you today?",
  "placeholder_text": "Ask a question...",
  "primary_color": "#0284c7"
}

Get conversation history

Retrieves the full conversation history for a session.

GET/widget/history/{session_token}

Path parameters

session_tokenstringrequired

The session token.

Request

curl https://api.isomera.ai/api/v1/widget/history/sess_abc123 \
  -H "X-API-Key: wk_your_api_key"

Response

{
  "messages": [
    {
      "role": "user",
      "content": "What are the side effects?",
      "timestamp": "2024-12-18T10:30:00Z"
    },
    {
      "role": "assistant",
      "content": "The most common side effects include...",
      "timestamp": "2024-12-18T10:30:02Z",
      "resources": [...]
    }
  ]
}

Stream response

Stream chat responses using Server-Sent Events for real-time typing effect.

POST/widget/chat/stream

Event types

token

Individual tokens as generated.

resources

Retrieved resources (sent before tokens).

done

Stream completion with metadata.

Request

curl -X POST https://api.isomera.ai/api/v1/widget/chat/stream \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wk_your_api_key" \
  -H "Accept: text/event-stream" \
  -d '{"message": "What is the dosing schedule?"}'

Response stream

event: resources
data: {"resources": [...]}

event: token
data: {"token": "The"}

event: token
data: {"token": " recommended"}

event: done
data: {"session_token": "sess_abc123"}