Chat API.
Integrate AI-powered chat into your apps.
The Chat API enables you to integrate Clear Tangle’s RAG-powered AI chat into your applications. Send messages, receive contextual responses with source citations, and manage conversation history programmatically.
RAG-POWERED RESPONSES
All responses use Retrieval-Augmented Generation, meaning the AI retrieves relevant information from your knowledge base before responding.
Endpoints
METHODENDPOINTDESCRIPTION
POST/chat/messagesSend a message
POST/chat/messages/streamSend message with streaming
GET/chat/conversationsList conversations
GET/chat/conversations/:idGet conversation
DELETE/chat/conversations/:idDelete conversation
GET/chat/conversations/:id/messagesGet conversation messages
Send a message
Send a message and receive an AI response with source citations from your knowledge base.
Send message · bash
curl -X POST "https://api.cleartangle.com/chat/messages" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "What did I capture about the Q1 roadmap last week?",
"conversationId": "conv_optional123",
"context": {
"projectIds": ["proj_123"],
"tags": ["planning"],
"dateRange": {
"start": "2024-01-08",
"end": "2024-01-15"
}
},
"options": {
"model": "default",
"temperature": 0.7,
"maxTokens": 1000,
"includeSourceCitations": true
}
}'
Request body
FIELDTYPEREQUIREDDESCRIPTION
messagestringYesThe user message to sendconversationIdstringNoContinue existing conversationcontextobjectNoFilter context for RAG retrievaloptionsobjectNoModel and response optionsResponse
Response · json
{
"success": true,
"data": {
"id": "msg_xyz789",
"conversationId": "conv_abc123",
"role": "assistant",
"content": "Based on your captures from last week, here's what you recorded about the Q1 roadmap:\n\n1. **Product priorities** were finalized in a meeting on January 10th, focusing on three main initiatives...\n\n2. **Timeline** was set with key milestones...",
"sources": [
{
"id": "cap_111",
"type": "capture",
"title": "Q1 Planning Meeting Notes",
"relevance": 0.94,
"excerpt": "Discussed main initiatives for Q1..."
},
{
"id": "cap_222",
"type": "capture",
"title": "Roadmap Discussion",
"relevance": 0.89,
"excerpt": "Timeline finalized with following milestones..."
}
],
"usage": {
"promptTokens": 2341,
"completionTokens": 512,
"totalTokens": 2853
},
"createdAt": "2024-01-15T10:30:00Z"
}
}
Context control
Control what information the AI has access to when generating responses. This is equivalent to using @mentions in the UI.
Context object · json
{
"context": {
// Filter by specific projects
"projectIds": ["proj_123", "proj_456"],
// Filter by tags
"tags": ["important", "work"],
// Filter by date range
"dateRange": {
"start": "2024-01-01",
"end": "2024-01-15"
},
// Include specific captures
"captureIds": ["cap_specific123"],
// Include specific pages
"pageIds": ["page_abc"],
// Enable semantic search scope
"semanticScope": "all" // "all", "recent", "relevant"
}
}
CONTEXT SCOPE
If no context is specified, the API searches your entire knowledge base for relevant information.
Streaming responses
Use the streaming endpoint for real-time responses. This is ideal for building interactive chat interfaces.
Streaming client · javascript
const response = await fetch("https://api.cleartangle.com/chat/messages/stream", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
message: "Summarize my notes from today",
options: { stream: true }
})
});
const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunk = decoder.decode(value);
const lines = chunk.split('\n').filter(line => line.startsWith('data: '));
for (const line of lines) {
const data = JSON.parse(line.slice(6));
if (data.type === 'content') {
process.stdout.write(data.content);
} else if (data.type === 'sources') {
console.log('\nSources:', data.sources);
} else if (data.type === 'done') {
console.log('\nStream complete');
}
}
}
Stream event types
contentPartial response content to appendsourcesSource citations for the responseusageToken usage statisticsdoneStream complete signalerrorError occurred during streamingModel options
Customize the AI model behavior with these options:
OPTIONTYPEDEFAULTDESCRIPTION
modelstringdefaultModel to use (default uses optimal model for task)temperaturenumber0.7Response creativity (0–1)maxTokensinteger1000Maximum response lengthincludeSourceCitationsbooleantrueInclude source citationsmaxSourcesinteger5Maximum sources to includestreambooleanfalseEnable streaming (use /stream endpoint)Conversation management
Conversations are automatically created when you send a message without a conversationId. To continue a conversation, include the conversationId in subsequent requests.
List conversations
List conversations · bash
curl -X GET "https://api.cleartangle.com/chat/conversations?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
Get conversation messages
Get messages · bash
curl -X GET "https://api.cleartangle.com/chat/conversations/conv_abc123/messages" \
-H "Authorization: Bearer YOUR_API_KEY"
Rate limits
CHAT API LIMITS
Chat API has separate rate limits due to LLM costs. Check the
X-RateLimit-Chat-Remaining header.PLANMESSAGES / MINMESSAGES / DAY
Free10100
Pro601,000
EnterpriseCustomCustom