Threads and messages
Create threads, manage their metadata, read history, and stream a turn.
Threads live inside a workspace project. Thread responses use snake_case fields. The chat stream follows the AI SDK UI message stream protocol.
Agent-backed threads use an Agent configuration, and each accepted turn creates a run.
List threads
/v1/threadsReturns ordinary threads ordered by recent activity.
curl "$FLUSO_API/v1/threads?page=1&limit=20" \
-H "Authorization: Bearer $FLUSO_TOKEN"{
"threads": [
{
"thread_id": "thread_release",
"project_id": "Release Review",
"name": "Release review",
"title": "Release review",
"created_at": "2026-08-31T09:00:00Z",
"updated_at": "2026-08-31T09:02:00Z",
"last_active_at": "2026-08-31T09:02:00Z",
"status": "ready"
}
],
"pagination": { "page": 1, "limit": 20, "total": 1, "pages": 1 }
}Agent-owned chats are omitted from this general list and remain attached to their Agent.
Create a thread
/v1/threadsCreates a thread in the named project, creating the project when needed.
curl "$FLUSO_API/v1/threads" \
-X POST \
-H "Authorization: Bearer $FLUSO_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"project_id":"Release Review","title":"Release review"}'{
"thread_id": "thread_release",
"project_id": "Release Review"
}You can supply your own thread_id for an idempotent integration boundary.
Update a thread
/v1/threads/{threadId}Updates the title, metadata, pin, archive state, or label membership.
curl "$FLUSO_API/v1/threads/thread_release?project_id=Release%20Review" \
-X PATCH \
-H "Authorization: Bearer $FLUSO_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"title":"RC decision","pinned":true}'{
"thread_id": "thread_release",
"project_id": "Release Review",
"name": "RC decision",
"title": "RC decision",
"pinned_at": "2026-08-31T09:03:00Z",
"status": "ready"
}Read message history
/v1/threads/{threadId}/messagesReturns the thread's persisted messages and projected tool-status records.
curl "$FLUSO_API/v1/threads/thread_release/messages?project_id=Release%20Review" \
-H "Authorization: Bearer $FLUSO_TOKEN"{
"messages": [
{
"message_id": "user-1",
"thread_id": "thread_release",
"type": "user",
"is_llm_message": false,
"content": "{\"content\":\"Review this release candidate\"}",
"metadata": "{\"request_id\":\"req_review_01\"}",
"created_at": "2026-08-31T09:00:00Z",
"updated_at": "2026-08-31T09:00:00Z"
}
]
}Send a message
/v1/chatStarts or queues a turn and streams UI message events until the request settles.
Use a new thread ID for the first Agent-backed turn. The accepted send creates and binds that thread; an ordinary thread cannot later be converted.
curl -N "$FLUSO_API/v1/chat" \
-H "Authorization: Bearer $FLUSO_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"threadId": "thread_agent_release",
"projectName": "Release Review",
"agentId": "agt_0123456789ab4def8123456789abcdef",
"requestId": "req_review_01",
"message": "Review this release candidate"
}'data: {"type":"start","messageId":"assistant-req_review_01"}
data: {"type":"text-start","id":"final-text-req_review_01"}
data: {"type":"text-delta","id":"final-text-req_review_01","delta":"Go, with one follow-up."}
data: {"type":"text-end","id":"final-text-req_review_01"}
data: {"type":"finish"}
data: [DONE]Use one unique requestId per intended turn. Retrying the same accepted request does not create a second turn.
Delete a thread
/v1/threads/{threadId}Deletes the thread and removes schedules that target it.
curl "$FLUSO_API/v1/threads/thread_release?project_id=Release%20Review" \
-X DELETE \
-H "Authorization: Bearer $FLUSO_TOKEN"{ "deleted": true }Next
Bind new threads to Agents and versions, or follow accepted turns in Runs.