Conversation Threads

Recommended Approach: Conversation threads are the preferred way to build multi-turn conversations with the Cura’s AI Model. They handle context automatically and provide a seamless experience.

Overview

Conversation threads enable stateful, context-aware conversations with the Cura AI without requiring you to manually manage message history. The server automatically:

Stores all messages in the conversation
Injects the last 20 messages as context on every request
Auto-deletes inactive threads after 30 minutes
Isolates conversations for privacy and clarity
Links threads to patient profiles (optional)
Note: All cURL requests are case sensetive.

How It Works

Create a Thread

Make a POST /api/cura/threads request to get a unique 5-digit thread ID.

curl -X POST "https://app.mycura.org/api/cura/threads" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "5551234567"}'

Response:

{
  "success": true,
  "threadId": "82451",
  "expiresAt": "2025-10-22T19:30:00.000Z",
  "message": "Thread created successfully. Use this threadId in your chat requests."
}

Send Messages

Include the threadId in your chat requests. The AI automatically receives the conversation history.

curl -X POST "https://app.mycura.org/api/cura/chat" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "82451",
    "message": "I have been experiencing headaches"
  }'

The server automatically:

Loads the last 20 messages from this thread
Sends them to the AI as context
Appends the new message and response to the thread
Updates the expiration time

Continue the Conversation

Just keep using the same threadId. No need to send conversationHistory manually!

curl -X POST "https://app.mycura.org/api/cura/chat" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "82451",
    "message": "What did we discuss about my symptoms?"
  }'

The AI will remember everything from the thread automatically.

End the Thread (Optional)

Threads auto-delete after 30 minutes of inactivity, or you can manually delete them:

curl -X DELETE "https://app.mycura.org/api/cura/threads/82451" \
  -H "X-API-Key: YOUR_API_KEY"

Key Features

5-Digit Thread IDs

Each thread gets a unique 5-digit identifier (e.g., 82451, 19234) that you use to reference the conversation.

{
  "threadId": "82451",
  "expiresAt": "2025-10-22T19:30:00.000Z"
}

Automatic Context Injection

The server automatically loads and sends the last 20 messages from your thread to the AI on every request. You don’t need to:

Store messages on your end
Send conversationHistory arrays
Manage context windows

The AI just remembers!

30-Minute Auto-Expiration

Threads automatically delete themselves after 30 minutes of inactivity to:

Protect patient privacy
Manage server resources
Encourage focused conversations

The expiration timer resets every time a message is sent.

Patient Linking (Optional)

Link a thread to a patient profile by providing their patientId or phone when creating the thread:

{
  "phone": "5551234567",
  "metadata": {
    "name": "Medication Questions",
    "source": "mobile_app"
  }
}

The AI will have access to the patient’s medical information (medications, conditions, allergies) throughout the conversation.

Thread Independence

Each thread is completely isolated. You can have multiple concurrent threads for different:

Patients
Topics (e.g., one for medications, one for symptoms)
Sessions

Threads don’t interfere with each other.

When to Use Threads

Use Threads When

Building multi-turn conversations
Creating chatbot interfaces
Handling patient consultations
Needing automatic context management
Managing multiple conversations simultaneously

Don't Use Threads When

Sending single, one-off questions
Building stateless APIs
You want full control over context
Testing or debugging individual requests

Thread vs. Manual Context

With Threads (Recommended)
Without Threads (Manual)

// Create thread once
const { threadId } = await createThread({ phone: "5551234567" });

// Message 1
await chat({ threadId, message: "I have headaches" });

// Message 2 - AI remembers message 1 automatically
await chat({ threadId, message: "What causes them?" });

// Message 3 - AI remembers messages 1 & 2 automatically
await chat({ threadId, message: "Summarize our discussion" });

Clean, simple, automatic

// Message 1
const history1 = [];
const resp1 = await chat({ 
  message: "I have headaches",
  conversationHistory: history1 
});
history1.push({ role: "user", content: "I have headaches" });
history1.push({ role: "assistant", content: resp1.response });

// Message 2 - Must manually send history
const resp2 = await chat({ 
  message: "What causes them?",
  conversationHistory: history1 
});
history1.push({ role: "user", content: "What causes them?" });
history1.push({ role: "assistant", content: resp2.response });

// Message 3 - Must manually send growing history
const resp3 = await chat({ 
  message: "Summarize our discussion",
  conversationHistory: history1 
});

Complex, error-prone, manual management

Code Examples

Creating a Thread

const axios = require('axios');

async function createThread(phone) {
  const response = await axios.post(
    'https://app.mycura.org/api/cura/threads',
    { 
      phone: phone,
      metadata: { source: 'mobile_app' }
    },
    {
      headers: {
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
  // { threadId: "82451", expiresAt: "...", ... }
}

Using a Thread in Conversation

async function chatWithThread(threadId, message) {
  const response = await axios.post(
    'https://app.mycura.org/api/cura/chat',
    { 
      threadId: threadId,
      message: message 
    },
    {
      headers: {
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}

// Usage
const thread = await createThread('5551234567');
const msg1 = await chatWithThread(thread.threadId, 'I have a headache');
const msg2 = await chatWithThread(thread.threadId, 'What could cause it?');
const msg3 = await chatWithThread(thread.threadId, 'Summarize our chat');
// msg3.response will include summary of headache discussion!

Best Practices

Create threads at the start of a conversation session

When a user opens your app or starts a new chat, create a thread immediately. This ensures context is preserved throughout their session.

// App initialization
if (!sessionStorage.threadId) {
  const thread = await createThread();
  sessionStorage.threadId = thread.threadId;
}

Display expiration times to users

Show users when their thread will expire so they know how long they have for the conversation.

const minutesLeft = Math.floor(
  (new Date(expiresAt) - new Date()) / 1000 / 60
);
console.log(`Thread expires in ${minutesLeft} minutes`);

Link threads to patients when possible

If you have patient information, link the thread to provide better context to the AI.

// Preferred
await createThread({ 
  phone: "5551234567",
  metadata: { sessionId: "abc123" }
});

// Also works without patient
await createThread({ 
  metadata: { anonymous: true }
});

Clean up threads when users log out

Manually delete threads when a user logs out or closes the app for privacy.

window.addEventListener('beforeunload', async () => {
  if (sessionStorage.threadId) {
    await deleteThread(sessionStorage.threadId);
  }
});

Store threadId on your side for analytics

Keep track of thread IDs in your database to analyze conversation patterns and usage.

await db.sessions.create({
  userId: currentUser.id,
  threadId: thread.threadId,
  createdAt: new Date()
});

Create Thread

POST /api/cura/threads

Get Thread Info

GET /api/cura/threads/{id}

Delete Thread

DELETE /api/cura/threads/{id}

Chat with Thread

POST /api/cura/chat

Next Steps

Quick Start

Build your first conversation in 5 minutes

API Reference

Detailed endpoint documentation

Best Practices

Tips for production applications

Client Examples

Code examples in multiple languages

Getting Started

Core Concepts

Best Practices

Overview

How It Works

Key Features

5-Digit Thread IDs

Automatic Context Injection

30-Minute Auto-Expiration

Patient Linking (Optional)

Thread Independence

When to Use Threads

Use Threads When

Don't Use Threads When

Thread vs. Manual Context

Code Examples

Creating a Thread

Using a Thread in Conversation

Best Practices

Create Thread

Get Thread Info

Delete Thread

Chat with Thread

Next Steps

Quick Start

API Reference

Best Practices

Client Examples

Getting Started

Core Concepts

Best Practices

​Overview

​How It Works

​Key Features

​5-Digit Thread IDs

​Automatic Context Injection

​30-Minute Auto-Expiration

​Patient Linking (Optional)

​Thread Independence

​When to Use Threads

Use Threads When

Don't Use Threads When

​Thread vs. Manual Context

​Code Examples

​Creating a Thread

​Using a Thread in Conversation

​Best Practices

​Related Endpoints

Create Thread

Get Thread Info

Delete Thread

Chat with Thread

​Next Steps

Quick Start

API Reference

Best Practices

Client Examples

Overview

How It Works

Key Features

5-Digit Thread IDs

Automatic Context Injection

30-Minute Auto-Expiration

Patient Linking (Optional)

Thread Independence

When to Use Threads

Thread vs. Manual Context

Code Examples

Creating a Thread

Using a Thread in Conversation

Best Practices

Related Endpoints

Next Steps