Threads are an app’s persistent conversation history — created automatically by Chat or managed directly via these endpoints.
List Threads
GET /api/v1/apps/{appId}/memory/threads
Filter by active, archived, or closed.
{
"data": [
{
"id": "thr_a1b2...",
"app_id": "app_123",
"workspace_id": "ws_...",
"session_id": null,
"title": "New Thread",
"status": "active",
"message_count": 4,
"metadata": {},
"created_at": "2026-07-08T09:00:00Z",
"updated_at": "2026-07-08T09:12:00Z"
}
],
"meta": { "limit": 20, "offset": 0, "total": 1 }
}
Create Thread
POST /api/v1/apps/{appId}/memory/threads
title
string
default:"New Thread"
Get Thread
GET /api/v1/apps/{appId}/memory/threads/{threadId}
Update Thread
PATCH /api/v1/apps/{appId}/memory/threads/{threadId}
active, archived, or closed.
Delete (Archive) Thread
DELETE /api/v1/apps/{appId}/memory/threads/{threadId}
Marks the thread archived rather than hard-deleting it.
{ "success": true, "threadId": "thr_a1b2..." }
List Thread Messages
GET /api/v1/apps/{appId}/memory/threads/{threadId}/messages
{
"data": [
{
"id": "msg_1",
"workspace_id": "ws_...",
"app_id": "app_123",
"thread_id": "thr_a1b2...",
"role": "user",
"content": "What's our refund policy?",
"sequence_number": 1,
"request_id": "req_1",
"turn_id": "turn_1",
"provider_status": "success",
"latency_ms": 640,
"input_tokens": 214,
"output_tokens": 18,
"cost_usd": 0.0004,
"rag_sources": [],
"metadata": {},
"created_at": "2026-07-08T09:00:00Z"
}
],
"meta": { "limit": 50, "offset": 0, "total": 1 }
}
Batch Save Messages
POST /api/v1/apps/{appId}/memory/save-messages
Writes messages directly into a thread’s history without triggering a model call — useful for importing conversation history from another system.
curl -X POST https://suite.sundaypyjamas.com/api/v1/apps/app_123/memory/save-messages \
-H "Authorization: Bearer spj_ai_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"threadId": "thr_a1b2...",
"messages": [
{ "role": "user", "content": "Hi there" },
{ "role": "assistant", "content": "Hello! How can I help?" }
]
}'
{ "saved": 2, "threadId": "thr_a1b2..." }
Memory Status
GET /api/v1/apps/{appId}/memory/status
{
"appId": "app_123",
"threadCount": 42,
"activeThreadCount": 9,
"messageCount": 631
}
Errors
| Status | Error | Applies to |
|---|
| 400 | Invalid status. Must be one of: active, archived, closed | Update Thread |
| 400 | threadId is required / messages must be a non-empty array / Maximum 100 messages per request | Save Messages |
| 401 | Unauthorized or app not found | All |
| 404 | Thread not found | Thread-scoped endpoints |