API Reference

API Overview

Flapjack REST API reference. Base URL, authentication, error format, and request conventions.

The Flapjack REST API lets you manage agents, threads, knowledge, MCP servers, and API keys programmatically.

Authentication

Include your API key as a Bearer token:

Authorization: Bearer fj_live_...

API keys are created at flapjack.chat → Keys.

Request Format

Content-Type: application/json for all non-upload endpoints
Uploads: multipart/form-data for file uploads (knowledge)
IDs: All resource IDs are UUIDs

Response Format

Successful responses return JSON:

{
  "id": "abc-123",
  "name": "My Agent",
  "created_at": "2026-03-28T12:00:00Z"
}

List endpoints return JSON arrays:

[
  { "id": "abc-123", "name": "Agent 1" },
  { "id": "def-456", "name": "Agent 2" }
]

Error Format

Error responses return JSON with error and optional detail:

{
  "error": "NOT_FOUND",
  "detail": "Agent not found"
}

HTTP Status Codes

Status	Meaning
`200`	Success
`201`	Created
`204`	Deleted (no content)
`400`	Bad request (invalid body)
`401`	Unauthorized (missing or invalid API key)
`403`	Forbidden (no access to this resource)
`404`	Resource not found
`422`	Validation error
`500`	Internal server error

Streaming Responses

The POST /api/threads/{threadId}/messages endpoint returns Server-Sent Events (SSE) instead of JSON. See Concepts: Streaming for the event format.

Endpoint Reference

Section	Endpoints
Agents	CRUD, configuration, sub-resources
Threads	Create threads, send messages, stop, participants
Knowledge	Upload, list, delete documents
MCP Servers	MCP server management, OAuth
Keys	API key management
Models	Supported models and pricing
Runners	Headless AI pipelines — CRUD, steps, triggers, runs
Analytics	Usage metrics, cost tracking, per-model breakdowns
Logs	Execution traces, span trees, evaluations
Computer	Persistent computer — create from template, exec, status, instances, webhooks
Skills	Skill marketplace — browse, install, sync, attach to agents/runners
Projects	Organizational grouping for agents and runners
Code Agents	Cursor-backed cloud code agents — templates, sessions, events

Logs / Tracing

Endpoint	Description
`GET /api/logs`	Paginated trace list (filter by agent, runner, thread, status)
`GET /api/logs/{traceId}`	Full trace with span tree and evaluations

See Concepts: Tracing for the data model.

Additional Endpoints

These endpoints are also available but don't have dedicated reference pages yet. See the SDK Client Reference for typed wrappers.

Endpoint	Description
`GET/POST /api/integrations`	Database integration CRUD
`GET/DELETE /api/integrations/{id}`	Get or delete integration
`GET/POST /api/tools`	Custom tool definitions
`GET/PATCH/DELETE /api/tools/{id}`	Custom tool CRUD
`GET/POST /api/plans`	Plan CRUD (query by `threadId`)
`GET/PATCH/DELETE /api/plans/{id}`	Individual plan management
`POST /api/plans/{id}/todos`	Add todos to a plan
`PATCH/DELETE /api/plans/{id}/todos/{todoId}`	Update or delete a todo
`GET/POST/DELETE /api/plans/{id}/todos/{todoId}/deps`	Todo dependency edges (blockers)
`GET /api/plans/{id}/ready`	Get unblocked todos ready to work on
`GET /api/analytics`	Usage analytics (period, agentId)
`GET/PUT/DELETE /api/agents/{id}/marketplace`	Marketplace profile
`POST /api/agents/{id}/marketplace/avatar`	Upload agent avatar
`GET/PUT /api/agents/{id}/multiplayer`	Multiplayer configuration
`GET/PUT /api/agents/{id}/delegated`	Delegated tools configuration
`GET/PUT /api/agents/{id}/credentials`	Credential resolver (BYOK) configuration
`GET/POST/PUT /api/agents/{id}/suggestions`	Agent improvement suggestions (PUT to dismiss/undismiss)
`GET/POST /api/agents/{id}/channels`	Channel adapter management — see Tools: Channel Adapters
`PATCH/DELETE /api/agents/{id}/channels/{channelId}`	Update or delete a channel adapter
`GET /api/agents/{id}/channels/{channelId}/contacts`	List contacts for a channel
`GET/PUT /api/agents/{id}/scheduled-tasks`	Enable/disable scheduled tasks — see Tools: Scheduled Tasks
`GET/POST /api/agents/{id}/skills`	Skill attachments — see Skills
`GET/PUT /api/runners/{id}/budget`	Runner budget configuration
`POST /api/runners/{id}/runs/{runId}/resume`	Resume a budget-paused run
`GET/POST /api/skills`	Skill marketplace — see Skills
`GET /api/skills/browse`	Browse the unified skill marketplace
`POST /api/skills/{id}/sync`	Re-sync skill source content
`GET/POST /api/runners/{id}/skills`	Runner skill bindings
`GET/POST /api/projects`	Project CRUD — see Projects
`GET/PATCH/DELETE /api/projects/{id}`	Individual project management
`GET /api/projects/{id}/members`	List agents and runners in a project
`GET /api/marketplace/official`	Official marketplace agent templates
`POST /api/marketplace/official/use`	Create agent from official template
`GET /api/mcp-registry/search`	MCP server registry search
`GET /api/mcp-registry/managed`	Managed OAuth MCP providers
`GET/POST /api/code-agents`	Code agent template CRUD — see Code Agents guide
`GET/PATCH/DELETE /api/code-agents/{id}`	Individual code agent management
`GET/POST /api/code-sessions`	Code session CRUD (start, list)
`GET/PATCH /api/code-sessions/{id}`	Get or update a code session
`POST /api/code-sessions/{id}/messages`	Send follow-up prompt to a session
`GET /api/code-sessions/{id}/events`	Read session event timeline
`POST /api/code-sessions/{id}/cancel`	Cancel a running session
`POST /api/code-sessions/{id}/archive`	Archive and clear stored Cursor key
`GET /api/agents/{id}/computer-instances`	List persistent sandbox instances for an agent

Endpoints under /api/internal/ are called by the Flapjack runtime (Tensorlake/Modal) during agent execution. They are not intended for external use and require internal authentication. Do not call these from your application.