Quickstart: REST API

Use the Flapjack REST API directly with curl or any HTTP client. No SDK required.

Time: 5 minutes Prerequisites: A Flapjack account with an API key and agent

Base URL

https://api.flapjack.dev

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer fj_live_...

Step 1: List Your Agents

curl -s https://api.flapjack.dev/api/agents \
  -H "Authorization: Bearer fj_live_..." \
  | python3 -m json.tool

Response:

[
  {
    "id": "abc-123",
    "name": "My Support Agent",
    "description": "Handles customer questions",
    "default_model": "gpt-5.4",
    "temperature": 0.7,
    "created_at": "2026-03-01T00:00:00Z"
  }
]

📋 Copy as prompt

Use curl to list my Flapjack agents at https://api.flapjack.dev/api/agents with my API key as a Bearer token.

Step 2: Create a Thread

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

Response:

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

📋 Copy as prompt

Use curl to create a new Flapjack thread for agent ID abc-123 by POSTing to https://api.flapjack.dev/api/threads.

Step 3: Send a Message (Streaming)

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?"}'

The response is a Server-Sent Events (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"}

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

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

📋 Copy as prompt

Use curl with the -N flag (no buffering) to POST a message to my Flapjack thread and display the SSE stream. The endpoint is https://api.flapjack.dev/api/threads/{threadId}/messages with a JSON body containing content.

SSE Event Types

Event	Key Fields	Description
meta	startedAt	Stream metadata, sent first
token	delta	Incremental text chunk from the LLM
tool_call	tool.id, tool.name, tool.arguments	Agent is calling a tool
tool_executing	tool_name	Tool execution started
tool_result	tool_name, tool_call_id, result	Tool execution completed
done	ok, messageId, content	Full final response
error	code, detail	Error occurred

Error Responses

Non-streaming endpoints return JSON errors:

{
  "error": "UNAUTHORIZED",
  "detail": "Invalid or expired API key"
}

HTTP Status	Meaning
401	Invalid or missing API key
403	Key valid but no access to this resource
404	Agent, thread, or resource not found
422	Invalid request body
500	Internal server error

Next Steps

• API Reference — full endpoint documentation
• Concepts: Streaming — SSE protocol in depth
• Concepts: Authentication — API key security model