Skip to main content
POST
/
api
/
cura
/
threads
Create Thread
curl --request POST \
  --url https://api.mycura.org/api/cura/threads \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "patientId": {},
  "phone": "<string>",
  "metadata": {}
}
'
{
  "error": "Unauthorized - Invalid API key"
}
Recommended: This is the preferred way to start a conversation with the Cura AI. Threads handle context automatically.

​
Overview

Creates a new conversation thread with a unique 5-digit ID. Once created, you can send multiple messages to this thread and the AI will automatically remember the conversation history (last 20 messages).

​
Authentication

​
X-API-Key
string
required
Your Cura API key

​
Body Parameters

All parameters are optional. You can send an empty body {} for general conversations without patient context.
​
patientId
string (UUID)
Optional patient UUID to link this thread to a patient profile. The AI will have access to patient data.
​
phone
string
Optional patient phone number (any format: 5551234567, +15551234567, (555) 123-4567).The system will automatically find the patient and link the thread.
​
metadata
object
Optional metadata to store with the thread (e.g., session info, source, tags).
{
  "source": "mobile_app",
  "sessionId": "abc123",
  "name": "Medication Questions"
}

​
Examples:

  • {} - General conversation (no patient lookup) Recommended
  • {"phone": "5551234567"} - With patient lookup
  • {"patientId": "uuid-123"} - With patient ID

​
Request Example

# General conversation (recommended)
curl -X POST "https://api.mycura.org/api/cura/threads" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# With patient lookup
curl -X POST "https://api.mycura.org/api/cura/threads" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5551234567",
    "metadata": {
      "source": "mobile_app"
    }
  }'

​
Response

​
success
boolean
Whether the thread was created successfully
​
threadId
string
Unique 5-digit thread identifier (e.g., "82451")
​
initialMessage
string (optional)
An initial question from the AI to start the conversation (e.g., demographic questions like gender). Display this message to the user immediately after thread creation to begin the conversation flow.
​
expiresAt
string (ISO 8601)
ISO 8601 timestamp when the thread will auto-delete (30 minutes from creation)
​
messageCount
number
Initial message count (typically 0 for new threads, or 2 if initialMessage is present)
​
message
string
Success message with usage instructions

​
Success Response (201)

{
  "success": true,
  "threadId": "82451",
  "initialMessage": "Are you male or female?",
  "expiresAt": "2025-11-10T15:30:00Z",
  "messageCount": 2,
  "message": "Thread created successfully. Use this threadId in your chat requests."
}
The initialMessage field may or may not be present depending on whether the AI has an initial question. Always check for its presence and display it to the user if available.

​
Error Responses

{
  "error": "Unauthorized - Invalid API key"
}

​
Thread Features

Unique 5-Digit ID

Each thread gets a unique identifier that’s easy to reference and share

Auto-Expires in 30 Min

Threads automatically delete after 30 minutes of inactivity for privacy

Automatic Context

Last 20 messages auto-loaded on every request - no manual history management

Patient Linking

Optional patient linking gives AI access to medical information

​
Usage Flow

1

Create Thread

Make this request to get a threadId
2

Save Thread ID

Store the threadId on your client (localStorage, state, session, etc.)
3

Send Messages

Use the threadId in your chat requests
4

Continue Conversation

Keep using the same threadId - context is automatic!

​
Best Practices

When a user opens your app or starts a new conversation, create a thread immediately:
// On app load
useEffect(() => {
  if (!sessionStorage.threadId) {
    createThread().then(thread => {
      sessionStorage.threadId = thread.threadId;
    });
  }
}, []);
Store useful information in metadata for analytics:
await createThread({
  phone: user.phone,
  metadata: {
    platform: 'iOS',
    version: '2.1.0',
    sessionId: generateSessionId()
  }
});
Monitor expiresAt and create new threads when needed:
if (new Date(thread.expiresAt) < new Date()) {
  // Thread expired, create new one
  const newThread = await createThread({ phone: user.phone });
  sessionStorage.threadId = newThread.threadId;
}

Chat

Send messages to the thread

Get Thread

Retrieve thread information

Delete Thread

Manually end a conversation

​
Next Steps

Learn About Conversation Threads

Comprehensive guide to using threads effectively