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.

Base URL

https://api.flapjack.dev

All endpoints are prefixed with /api/.

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
Computer	Persistent computer — create from template, exec, status, webhooks
Skills	Skill marketplace — browse, install, sync, attach to agents/runners
Projects	Organizational grouping for agents and runners

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 /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
`GET/PUT /api/agents/{id}/scheduled-tasks`	Scheduled tasks configuration
`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