API: Threads

Create conversation threads and send messages to agents. Message responses are streamed via Server-Sent Events (SSE).

Create Thread

POST /api/threads

Create a new conversation thread for an agent.

Request body:

Field	Type	Required	Description
agentId	string	Yes	The agent's UUID
title	string	No	Thread title
kind	string	No	single (default) or multiplayer
resourceBindings	array	No	Attach external resource context
activeProfile	string	No	Set the initial tool profile
systemPromptOverlay	string | string[]	No	Text appended to the agent's system prompt for this thread. Arrays are joined with \n\n.

curl -X POST https://api.flapjack.dev/api/threads \
  -H "Authorization: Bearer fj_live_..." \
  -H "Content-Type: application/json" \
  -d '{"agentId": "abc-123"}'

Response 200:

{
  "id": "thread-456",
  "org_id": "org-789",
  "agent_id": "abc-123",
  "title": null,
  "created_at": "2026-03-28T12:00:00Z"
}

📋 Copy as prompt

Create a Flapjack thread by POSTing to /api/threads with an agentId in the body. Save the returned thread ID.

---

Update Thread

PATCH /api/threads/{threadId}

Update a thread's configuration.

Request body:

Field	Type	Required	Description
activeProfile	string | null	No	Set or clear the active tool profile
title	string	No	Update thread title
systemPromptOverlay	string | string[] | null	No	Update or clear the thread-level system prompt overlay

curl -X PATCH https://api.flapjack.dev/api/threads/thread-456 \
  -H "Authorization: Bearer fj_live_..." \
  -H "Content-Type: application/json" \
  -d '{"activeProfile": "triage"}'

Response 200:

{
  "id": "thread-456",
  "org_id": "org-789",
  "agent_id": "abc-123",
  "title": null,
  "active_profile": "triage",
  "created_at": "2026-03-28T12:00:00Z"
}

---

Send Message (Streaming)

POST /api/threads/{threadId}/messages

Send a user message and receive the agent's response as an SSE stream.

Request body:

Field	Type	Required	Description
content	string	Yes	The user's message text
tools	array	No	Custom tool definitions for client-side execution
toolResults	array	No	Results for a previous requires_action event
modelOverride	string	No	Override agent's default model for this message
senderName	string	No	Display name (multiplayer threads)
senderId	string	No	Sender user ID (multiplayer threads)
toolProfile	string	No	Use a specific tool profile for this message
systemPromptOverlay	string | string[]	No	Text appended to the system prompt for this message only. Does not persist.

curl -N -X POST https://api.flapjack.dev/api/threads/thread-456/messages \
  -H "Authorization: Bearer fj_live_..." \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello, what can you help me with?"}'

Response 200 (SSE stream):

event: meta
data: {"startedAt":"2026-03-28T12:00:01Z"}

event: token
data: {"delta":"I"}

event: token
data: {"delta":" can"}

event: token
data: {"delta":" help"}

event: token
data: {"delta":" you with..."}

event: done
data: {"ok":true,"messageId":"msg-001","content":"I can help you with..."}

SSE Event Types

Event	Fields	Description
meta	startedAt	Stream metadata
token	delta	Text chunk from the LLM
tool_call	tool: { id, name, arguments }	Agent calling a tool
tool_executing	tool_name	Tool execution started
tool_result	tool_name, tool_call_id, result	Tool execution result
auth_challenge	toolName, challenge: { provider, redirectUrl, description? }	Tool requires user to complete an OAuth flow. See Auth Challenges.
requires_action	toolCalls	Agent requests client-side tool execution
profile_switch_proposal	target, reason	Agent proposes switching tool profile
done	ok, messageId?, content, usage?, stopped?	Full final response. messageId is absent when stopped early. usage contains token counts. stopped is present when interrupted.
error	code, detail?	Error occurred

See Concepts: Streaming for detailed event documentation.

📋 Copy as prompt

Send a message to a Flapjack thread using curl with the -N flag for streaming. POST to /api/threads/{threadId}/messages with a JSON body containing content.

---

Stop Response

POST /api/threads/{threadId}/stop

Stop an active streaming response.

curl -X POST https://api.flapjack.dev/api/threads/thread-456/stop \
  -H "Authorization: Bearer fj_live_..."

Response 200:

{ "ok": true }

---

Participants (Multiplayer)

Manage participants in multiplayer threads.

GET /api/threads/{threadId}/participants

Returns all participants in a multiplayer thread.

---

POST /api/threads/{threadId}/participants

Add a participant.

Field	Type	Required	Description
userId	string	Yes	User ID to add
displayName	string	No	Display name
role	string	No	owner or member (default)

---

DELETE /api/threads/{threadId}/participants

Remove a participant. Body: { "userId": "..." }.

---

Conversation History

Flapjack automatically maintains the full conversation history for each thread. Each call to sendMessage includes all prior messages as context. You do not need to send history manually.

You can also retrieve conversation history via the API:

---

List Threads

GET /api/threads?agentId={agentId}

List conversation threads for an agent. For JWT auth, results are scoped to the current user's threads. For API key auth, all org threads are returned.

Query parameters:

Parameter	Type	Required	Description
agentId	string	Yes	Filter threads by agent UUID
cursor	string	No	ISO 8601 timestamp for cursor pagination (fetch threads older than this)
limit	number	No	Max threads to return (default 50, max 100)
orgId	string	No	Target org (multi-org only)

curl https://api.flapjack.dev/api/threads?agentId=abc-123 \
  -H "Authorization: Bearer fj_live_..."

Response 200:

{
  "threads": [
    {
      "id": "thread-456",
      "org_id": "org-789",
      "agent_id": "abc-123",
      "title": null,
      "kind": "single",
      "status": "active",
      "created_at": "2026-04-01T12:00:00Z",
      "updated_at": "2026-04-01T12:05:00Z"
    }
  ],
  "nextCursor": "2026-03-31T10:00:00Z"
}

When nextCursor is null, there are no more pages. Pass it as the cursor parameter to fetch the next page.

Copy as prompt

List my Flapjack threads for an agent using GET /api/threads?agentId={id}. The response includes a nextCursor for pagination.

---

Get Messages

GET /api/threads/{threadId}/messages

Retrieve the message history for a thread. Only user and assistant role messages are returned.

Query parameters:

Parameter	Type	Required	Description
limit	number	No	Max messages to return (default 100, max 200)
offset	number	No	Number of messages to skip (default 0)

curl https://api.flapjack.dev/api/threads/thread-456/messages \
  -H "Authorization: Bearer fj_live_..."

Response 200:

{
  "messages": [
    {
      "id": "msg-001",
      "role": "user",
      "content": "Hello!",
      "sender_name": null,
      "created_at": "2026-04-01T12:00:01Z"
    },
    {
      "id": "msg-002",
      "role": "assistant",
      "content": "Hi! How can I help you today?",
      "sender_name": null,
      "created_at": "2026-04-01T12:00:03Z"
    }
  ],
  "total": 2
}

Copy as prompt

Fetch message history for a Flapjack thread using GET /api/threads/{threadId}/messages. Supports limit and offset for pagination.

---

Next Steps

• Concepts: Streaming — SSE event types in detail
• API: Agents — manage agents
• SDK: Client — use the SDK instead of raw API calls