# Flapjack Developer Documentation

> Flapjack is a hosted platform for deploying AI agents. Create agents via the dashboard, embed them in any product using the TypeScript SDK or REST API, and extend them with MCP tool servers, knowledge bases, memory, and more.

## Quick Start

The fastest way to get started is installing the Flapjack skill in your AI editor:

```
/plugin add maatskappy/flapjack
```

Then set your API key (`fj_live_*` format from https://flapjack.chat → Keys) and ask your AI assistant to scaffold the integration.

## Documentation Map

- [Overview](index.md): Platform overview, architecture, and navigation
- [Quickstart: Skill](getting-started/quickstart-skill.md): Install the Flapjack plugin in Claude Code or Cursor (30 seconds)
- [Quickstart: SDK](getting-started/quickstart-sdk.md): Install @flapjack/sdk, stream your first message (5 minutes)
- [Quickstart: API](getting-started/quickstart-api.md): Call the REST API directly with curl
- [Concepts: Agents](concepts/agents.md): AI agents with system prompts, model selection, temperature
- [Concepts: Threads and Messages](concepts/threads-and-messages.md): Conversation sessions and message lifecycle
- [Concepts: Streaming](concepts/streaming.md): SSE protocol, event types, ChatEvent type definition
- [Concepts: Tools](concepts/tools.md): Webhooks, MCP servers, integrations, web tools, memory, computer use
- [Concepts: Knowledge](concepts/knowledge.md): RAG with document upload and vector search
- [Concepts: Memory](concepts/memory.md): Scoped recall and store across conversations
- [Concepts: Skills](concepts/skills.md): Reusable skill_md / openapi_action / mcp_registry bundles attached to agents and runners
- [Concepts: Authentication](concepts/authentication.md): API keys, demo key, Supabase JWT, security model
- [Concepts: Tracing](concepts/tracing.md): Span-tree traces for agent turns and runner runs, log viewing API
- [SDK: Overview](sdk/overview.md): Installation, configuration, error handling
- [SDK: Client](sdk/client.md): FlapjackClient method reference
- [SDK: React](sdk/react.md): FlapjackProvider and useChat hook
- [SDK: Server Proxy](sdk/server-proxy.md): Production pattern for secure API key handling
- [SDK: Examples](sdk/examples.md): End-to-end examples for common use cases
- [API: Overview](api/overview.md): Base URL, authentication, error format
- [API: Agents](api/agents.md): Agent CRUD endpoints
- [API: Threads](api/threads.md): Thread creation and message streaming endpoints
- [API: Knowledge](api/knowledge.md): Document upload, list, delete endpoints
- [API: MCP Servers](api/mcps.md): MCP server management endpoints
- [API: Keys](api/keys.md): API key management endpoints
- [API: Models](api/models.md): Supported LLM models and pricing
- [API: Skills](api/skills.md): Skill marketplace — install, browse, sync, attach to agents and runners
- [MCP: Overview](mcp/overview.md): What MCP is and how Flapjack uses it
- [MCP: Connecting Servers](mcp/connecting.md): Adding MCP servers via dashboard or API
- [MCP: OAuth](mcp/oauth.md): OAuth 2.1 flow for authenticated MCP servers
- [MCP: Building Tools](mcp/building-tools.md): Creating custom MCP tools for your agent
- [Guide: Publish an Agent](guides/publish-agent.md): Public shareable agent links
- [Guide: Postgres Integration](guides/postgres-integration.md): Connect Postgres or Supabase as a data source
- [Guide: Web Tools](guides/web-tools.md): Search, research, read, and crawl the web
- [Guide: Google Workspace](guides/google-workspace.md): Connect Gmail, Calendar, Drive, Sheets, Contacts, Tasks via managed MCP
- [API: Projects](api/projects.md): Organizational grouping for agents and runners

## Key Concepts

- **Agent**: An AI agent with a system prompt, model, and attached tools. Created via the dashboard at flapjack.chat.
- **Thread**: A conversation session between a user and an agent. Contains messages.
- **Message**: A single turn in a thread. Streamed via SSE with event types: meta, token, tool_call, tool_executing, tool_result, done, error.
- **Tool**: An external capability attached to an agent. Types: webhook, MCP server, database integration, web tool, memory, computer use.
- **Knowledge**: Documents uploaded for RAG (retrieval-augmented generation). Chunked and embedded with pgvector.
- **Memory**: Persistent agent memory scoped to agent, thread, or resource. Auto-collected or explicitly stored.
- **API Key**: Authentication token with `fj_live_*` prefix. Created at flapjack.chat → Keys. Used as Bearer token.
- **MCP Server**: A Model Context Protocol server that provides tools to agents. Supports HTTP, SSE, and stdio transports.
- **Published Chat**: A public link to an agent that anyone can interact with. Configurable visibility.
- **Project**: Organizational container for grouping agents and runners. Aesthetic only — no runtime effect.
- **Trace**: Structured execution record (span tree) for an agent turn or runner run. Viewable via `/api/logs`.
- **Demo Key**: Public `fj_demo_*` API key for SDK evaluation without signup. Read-only, returns mock data.
- **System Prompt Overlay**: Text appended to the agent's system prompt at thread or per-message scope. Set via `systemPromptOverlay` in thread creation, update, or sendMessage.

## SDK Quick Reference

```typescript
import { FlapjackClient } from '@flapjack/sdk';

const client = new FlapjackClient({ apiKey: 'fj_live_...' });
const agents = await client.listAgents();
const thread = await client.createThread(agents[0].id);

for await (const event of client.sendMessage(thread.id, 'Hello!')) {
  if (event.type === 'token') process.stdout.write(event.delta);
  if (event.type === 'done') console.log('\nDone:', event.content);
}
```

## Architecture

```
Client (SDK) → Flapjack API (Next.js + Supabase) → Tensorlake Runtime (Python)
                    [control plane]                    [execution plane]
```

## Base URLs

- Production API: https://api.flapjack.dev
- Dashboard: https://flapjack.chat
- SDK package: @flapjack/sdk (npm)
- Last updated: 2026-05-11