Skip to main content
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
limit
number
default:"20"
Capped at 100.
offset
number
default:"0"
status
string
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"
metadata
object
default:"{}"

Get Thread

GET /api/v1/apps/{appId}/memory/threads/{threadId}

Update Thread

PATCH /api/v1/apps/{appId}/memory/threads/{threadId}
title
string
status
string
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
limit
number
default:"50"
Capped at 200.
offset
number
default:"0"
{
  "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.
threadId
string
required
messages
object[]
required
1–100 items.
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

StatusErrorApplies to
400Invalid status. Must be one of: active, archived, closedUpdate Thread
400threadId is required / messages must be a non-empty array / Maximum 100 messages per requestSave Messages
401Unauthorized or app not foundAll
404Thread not foundThread-scoped endpoints