API: Agents

Manage AI agents in your organization.

List Agents

GET /api/agents

Returns all agents in your organization.

curl https://api.flapjack.dev/api/agents \
  -H "Authorization: Bearer fj_live_..."

Response 200:

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

📋 Copy as prompt

Use curl to GET all Flapjack agents from /api/agents with my API key as Bearer auth.

---

Get Agent

GET /api/agents/{agentId}

Returns a single agent by ID.

curl https://api.flapjack.dev/api/agents/abc-123 \
  -H "Authorization: Bearer fj_live_..."

Response 200: Same as individual item in list response.

---

Create Agent

POST /api/agents

Create a new agent.

Request body:

Field	Type	Required	Description
name	string	Yes	Display name
description	string	No	What this agent does
stablePreamble	string	No	System prompt
defaultModel	string	No	Model ID (default: gpt-5.4)

curl -X POST https://api.flapjack.dev/api/agents \
  -H "Authorization: Bearer fj_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "description": "Handles customer questions",
    "stablePreamble": "You are a helpful support agent.",
    "defaultModel": "gpt-5.4"
  }'

Response 201: The created agent object.

📋 Copy as prompt

Create a Flapjack agent via the API with a name, description, system prompt, and model selection. POST to /api/agents.

---

Update Agent

PATCH /api/agents/{agentId}

Update an agent's configuration. Only include fields you want to change.

Request body: Same fields as create (all optional), plus:

Field	Type	Description
toolProfiles	object | null	Named tool profiles for server-side tool gating
defaultProfile	string | null	Default profile key for new threads

curl -X PATCH https://api.flapjack.dev/api/agents/abc-123 \
  -H "Authorization: Bearer fj_live_..." \
  -H "Content-Type: application/json" \
  -d '{"defaultModel": "claude-sonnet-4-6"}'

Response 200: The updated agent object.

---

Delete Agent

DELETE /api/agents/{agentId}

Delete an agent. Threads associated with this agent are not automatically deleted by this endpoint.

curl -X DELETE https://api.flapjack.dev/api/agents/abc-123 \
  -H "Authorization: Bearer fj_live_..."

Response 200:

{ "ok": true }

---

Agent Sub-Resources

Agents have several configurable sub-resources managed via the dashboard or these endpoints:

Endpoint	Method	Description
/api/agents/{id}/mcps	GET	List attached MCP servers
/api/agents/{id}/mcps	POST	Attach an MCP server
/api/agents/{id}/mcps	DELETE	Detach an MCP server
/api/agents/{id}/integrations	GET	List attached integrations
/api/agents/{id}/integrations	POST	Attach an integration
/api/agents/{id}/integrations	DELETE	Detach an integration
/api/agents/{id}/memories	GET	List agent memories
/api/agents/{id}/memory	POST	Recall memories
/api/agents/{id}/web	GET/PUT	Web tool configuration
/api/agents/{id}/plan	GET/PUT	Planning configuration
/api/agents/{id}/computer	GET/PUT	Computer use configuration
/api/agents/{id}/publish	GET/POST/PATCH/DELETE	Publish/unpublish as public chat
/api/agents/{id}/credentials	GET/PUT	Credential resolver (BYOK) configuration
/api/agents/{id}/multiplayer	GET/PUT	Multiplayer chat configuration
/api/agents/{id}/marketplace	GET/PUT/DELETE	Marketplace profile
/api/agents/{id}/marketplace/avatar	POST/DELETE	Agent avatar upload/delete
/api/agents/{id}/marketplace/generate-description	POST	AI-generate marketplace description
/api/agents/{id}/marketplace/detect-capabilities	POST	Auto-detect agent capabilities
/api/agents/{id}/marketplace/capabilities	PUT	Update capabilities list
/api/tools	GET/POST	Custom tool definitions (org-level, not per-agent)

Credential Resolver (BYOK)

Configure a webhook that resolves LLM provider API keys per user. This enables Bring Your Own Key (BYOK) billing where individual users pay for their own API usage.

Get Credential Config

GET /api/agents/{agentId}/credentials

curl https://api.flapjack.dev/api/agents/abc-123/credentials \
  -H "Authorization: Bearer fj_live_..."

Response 200:

{
  "agent_id": "abc-123",
  "org_id": "org-456",
  "enabled": false,
  "resolver_url": "",
  "timeout_ms": 5000
}

Update Credential Config

PUT /api/agents/{agentId}/credentials

Request body:

Field	Type	Required	Description
enabled	boolean	Yes	Enable/disable credential resolution
resolverUrl	string	Yes (if enabled)	HTTPS webhook URL
timeoutMs	number	No	Webhook timeout in ms (default: 5000)

curl -X PUT https://api.flapjack.dev/api/agents/abc-123/credentials \
  -H "Authorization: Bearer fj_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "resolverUrl": "https://app.example.com/api/resolve-credentials",
    "timeoutMs": 5000
  }'

Webhook Contract

When a message is sent, Flapjack calls your resolver URL before making the LLM request:

Request (HMAC-signed):

POST https://app.example.com/api/resolve-credentials
Headers:
  X-Flapjack-Timestamp: 1711929600
  X-Flapjack-Nonce: uuid
  X-Flapjack-Signature: hmac-sha256-hex

Body:
{
  "userId": "user_abc",
  "orgId": "org_xyz",
  "provider": "anthropic",
  "model": "claude-sonnet-4-6"
}

Response:

{
  "apiKey": "sk-ant-...",
  "source": "byok"
}

Return { "apiKey": null } or a non-200 status to fall back to the platform key.

---

Compaction (Context Management)

Automatically manage conversation context by summarizing older messages when approaching token limits. Uses Anthropic native compaction for Claude models and summary-based fallback for OpenAI models.

Get Compaction Config

GET /api/agents/{agentId}/compaction

curl https://api.flapjack.dev/api/agents/abc-123/compaction \
  -H "Authorization: Bearer fj_live_..."

Response 200:

{
  "agent_id": "abc-123",
  "org_id": "org-456",
  "enabled": false,
  "anthropic_trigger_tokens": 150000,
  "anthropic_instructions": null,
  "anthropic_pause_after": false,
  "openai_compact_threshold": 100000
}

Update Compaction Config

PUT /api/agents/{agentId}/compaction

curl -X PUT https://api.flapjack.dev/api/agents/abc-123/compaction \
  -H "Authorization: Bearer fj_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "anthropicTriggerTokens": 100000,
    "openaiCompactThreshold": 75000
  }'

Field	Type	Description
enabled	boolean	Enable/disable compaction
anthropicTriggerTokens	number	Token threshold for Anthropic compaction (min: 50,000)
anthropicInstructions	string	Custom summarization instructions
anthropicPauseAfter	boolean	Pause after compaction for custom injection
openaiCompactThreshold	number	Token threshold for OpenAI summary (min: 1,000)

See Concepts: Compaction for details on how compaction works.

---

Next Steps

• API: Threads — create threads and send messages
• API: MCP Servers — manage MCP connections
• Concepts: Agents — how agents work
• Concepts: Compaction — how compaction works