API Reference

API: Runners

Flapjack REST API endpoints for managing runners, their connections, and pipeline execution.

Manage headless, schedulable AI pipelines and their connections to MCP servers, integrations, tools, web tools, plans, and knowledge.

Runner CRUD

List Runners

GET /api/runners

Create Runner

POST /api/runners

Field	Type	Required	Description
`name`	`string`	Yes	Runner name
`description`	`string`	No	Description
`defaultModel`	`string`	No	Default LLM model for steps
`inputSchema`	`object`	No	JSON Schema for runner input

Get / Update / Delete Runner

GET    /api/runners/{runnerId}
PATCH  /api/runners/{runnerId}
DELETE /api/runners/{runnerId}

Runner Connections

Runners can connect directly to the same resources as agents: MCP servers, integrations, tools, web tools, plans, and knowledge.

MCP Servers

GET    /api/runners/{runnerId}/mcps          → List attached MCPs
POST   /api/runners/{runnerId}/mcps          → Attach MCP
DELETE /api/runners/{runnerId}/mcps          → Detach MCP

Attach request body:

Field	Type	Required	Description
`mcpServerId`	`string`	Yes	MCP server UUID
`allowedTools`	`string[]`	No	Per-runner tool filter

Detach request body: { "mcpServerId": "..." }

# Attach an MCP server to a runner
curl -X POST https://api.flapjack.dev/api/runners/{runnerId}/mcps \
  -H "Authorization: Bearer fj_live_..." \
  -H "Content-Type: application/json" \
  -d '{"mcpServerId": "mcp-server-uuid"}'

Integrations

GET    /api/runners/{runnerId}/integrations   → List attached integrations
POST   /api/runners/{runnerId}/integrations   → Attach integration
DELETE /api/runners/{runnerId}/integrations   → Detach integration

Attach request body:

Field	Type	Required	Description
`integrationId`	`string`	Yes	Integration UUID
`allowedTables`	`string[]`	No	Filter to specific tables

Detach request body: { "integrationId": "..." }

Custom Tools

GET    /api/runners/{runnerId}/tools          → List attached tools
POST   /api/runners/{runnerId}/tools          → Attach tool
DELETE /api/runners/{runnerId}/tools          → Detach tool

Attach request body:

Field	Type	Required	Description
`toolId`	`string`	Yes	Tool UUID
`allowed`	`boolean`	No	Enable/disable (default: true)

Detach request body: { "toolId": "..." }

Web Tools Config

GET /api/runners/{runnerId}/web              → Get web tools config
PUT /api/runners/{runnerId}/web              → Update web tools config

PUT request body:

Field	Type	Default	Description
`enabled`	`boolean`	`false`	Enable web tools
`searchEnabled`	`boolean`	`true`	Enable web search
`researchEnabled`	`boolean`	`true`	Enable deep research
`readEnabled`	`boolean`	`true`	Enable web page reading
`crawlEnabled`	`boolean`	`true`	Enable web crawling

Returns defaults (enabled: false, all sub-features true) if no config record exists.

Plan Config

GET /api/runners/{runnerId}/plan             → Get plan config
PUT /api/runners/{runnerId}/plan             → Update plan config

PUT request body:

Field	Type	Default	Description
`enabled`	`boolean`	`false`	Enable plans
`remindOnTurnEnd`	`boolean`	`true`	Remind at end of each turn if active plan exists

Runner-Scoped Knowledge

Upload knowledge docs scoped to a runner via the standard knowledge upload endpoint:

POST /api/knowledge/upload

Use scopeType=runner and scopeId={runnerId} in the form data.

curl -X POST https://api.flapjack.dev/api/knowledge/upload \
  -H "Authorization: Bearer fj_live_..." \
  -F "file=@data.txt" \
  -F "scopeType=runner" \
  -F "scopeId=RUNNER_ID" \
  -F "title=Reference Data"

List runner-scoped docs:

GET /api/knowledge?scopeType=runner&scopeId={runnerId}

Config Merge Strategy

When a runner step references an agent (agent_id), runner-level and agent-level configs are merged:

Resource	Strategy
MCP servers	Combined; deduplicated by slug (agent wins)
Integrations	Combined; agent overrides runner for same ID
Tools	Combined; deduplicated by name (agent wins)
Web config	Agent overrides runner when agent has it enabled

Steps without agent_id use runner-level connections exclusively.

Steps, Triggers, Runs

See the Runners Developer Guide for full documentation on steps, triggers, runs, cron scheduling, webhook inbound, bulk import, action buttons, idempotency, and self-improvement.

Next Steps

Runners Developer Guide — concepts, architecture, SDK examples
API: MCP Servers — managing org-level MCP servers
API: Knowledge — knowledge upload and management