Session Management
Learn how to manage conversation sessions and maintain context across requests.
What are Sessions?
Sessions allow the AI to remember conversation context across multiple requests. Each session maintains its own conversation history, enabling natural, contextual interactions.
✅ With Sessions
User: "My name is Alice"
AI: "Nice to meet you, Alice!"
User: "What's my name?"
AI: "Your name is Alice."
❌ Without Sessions
User: "My name is Alice"
AI: "Nice to meet you, Alice!"
User: "What's my name?"
AI: "I don't have that information."
How to Use Sessions
Pass a session ID using the sessionId header in your API requests. The session ID can be any unique string identifier.
Session ID Format: Use any unique string (UUID, user ID, or custom identifier). We recommend UUIDs for better uniqueness and security.
Supported Header Names
For maximum compatibility, we support multiple header name formats:
sessionId(recommended)session-idx-session-idsession_id
Python Examples
Using OpenAI SDK
The OpenAI SDK requires headers to be passed via default_headers:
from openai import OpenAI
import uuid
# Initialize client with session header
client = OpenAI(
api_key="your-api-key",
base_url="https://yourdomain.com/api/publicLLM",
default_headers={
"sessionId": str(uuid.uuid4()) # Generate unique session ID
}
)
# First message
response = client.chat.completions.create(
model="gpt-4",
messages=[
{"role": "user", "content": "My name is Alice"}
]
)
print(response.choices[0].message.content)
# Second message - AI remembers context
response = client.chat.completions.create(
model="gpt-4",
messages=[
{"role": "user", "content": "What's my name?"}
]
)
print(response.choices[0].message.content) # "Your name is Alice"Using Requests Library
With the requests library, you can pass headers directly:
import requests
import uuid
session_id = str(uuid.uuid4())
api_key = "your-api-key"
base_url = "https://yourdomain.com/api/publicLLM"
headers = {
"Authorization": f"Bearer {api_key}",
"sessionId": session_id,
"Content-Type": "application/json"
}
# First request
response = requests.post(
base_url,
headers=headers,
json={
"model": "gpt-4",
"messages": [
{"role": "user", "content": "My name is Alice"}
]
}
)
print(response.json()["choices"][0]["message"]["content"])
# Second request - same session
response = requests.post(
base_url,
headers=headers,
json={
"model": "gpt-4",
"messages": [
{"role": "user", "content": "What's my name?"}
]
}
)
print(response.json()["choices"][0]["message"]["content"])JavaScript/TypeScript Examples
Using OpenAI SDK
import OpenAI from 'openai';
import { v4 as uuidv4 } from 'uuid';
const client = new OpenAI({
apiKey: 'your-api-key',
baseURL: 'https://yourdomain.com/api/publicLLM',
defaultHeaders: {
'sessionId': uuidv4()
}
});
// First message
const response1 = await client.chat.completions.create({
model: 'gpt-4',
messages: [
{ role: 'user', content: 'My name is Alice' }
]
});
console.log(response1.choices[0].message.content);
// Second message - AI remembers context
const response2 = await client.chat.completions.create({
model: 'gpt-4',
messages: [
{ role: 'user', content: "What's my name?" }
]
});
console.log(response2.choices[0].message.content);Using Fetch API
const sessionId = crypto.randomUUID();
const apiKey = 'your-api-key';
const baseUrl = 'https://yourdomain.com/api/publicLLM';
const headers = {
'Authorization': `Bearer ${apiKey}`,
'sessionId': sessionId,
'Content-Type': 'application/json'
};
// First request
const response1 = await fetch(baseUrl, {
method: 'POST',
headers,
body: JSON.stringify({
model: 'gpt-4',
messages: [
{ role: 'user', content: 'My name is Alice' }
]
})
});
const data1 = await response1.json();
console.log(data1.choices[0].message.content);
// Second request - same session
const response2 = await fetch(baseUrl, {
method: 'POST',
headers,
body: JSON.stringify({
model: 'gpt-4',
messages: [
{ role: 'user', content: "What's my name?" }
]
})
});
const data2 = await response2.json();
console.log(data2.choices[0].message.content);cURL Examples
# Generate a session ID (or use any unique string)
SESSION_ID=$(uuidgen)
# First request
curl -X POST https://yourdomain.com/api/publicLLM \
-H "Authorization: Bearer your-api-key" \
-H "sessionId: $SESSION_ID" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4",
"messages": [
{"role": "user", "content": "My name is Alice"}
]
}'
# Second request - same session
curl -X POST https://yourdomain.com/api/publicLLM \
-H "Authorization: Bearer your-api-key" \
-H "sessionId: $SESSION_ID" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4",
"messages": [
{"role": "user", "content": "What is my name?"}
]
}'Best Practices
🔑 Use Unique Session IDs
Generate a new UUID for each conversation or user. This prevents context mixing between different users or conversations.
💾 Store Session IDs
Save the session ID on the client side (localStorage, cookies, or database) to maintain conversation continuity across page reloads or app restarts.
🔄 Reuse for Continuity
Use the same session ID for all requests in a conversation. Create a new session ID when starting a new conversation topic.
🧹 Clean Up Old Sessions
Sessions are automatically cleaned up after inactivity. Consider creating new sessions for new conversation topics to keep context relevant.
Session Lifecycle
Creation
Sessions are created automatically when you make your first request with a new session ID. No explicit creation endpoint is needed.
Active Usage
Each request with the same session ID adds to the conversation history. The AI uses this history to provide contextual responses.
Expiration
Sessions expire after a period of inactivity (typically 24 hours). After expiration, the conversation history is cleared.
Troubleshooting
AI doesn't remember previous messages?
- Verify you're using the same session ID for all requests
- Check that the header name is correct (sessionId, session-id, etc.)
- Ensure the session hasn't expired due to inactivity
Getting "Unexpected keyword argument" error?
If using the OpenAI SDK, make sure to pass the session ID via default_headers, not as a parameter in the request body. See the Python examples above.
Need to start a fresh conversation?
Simply generate and use a new session ID. The old session will remain available until it expires.