Developer docs

Build on Floom.

What Floom gives developers and how to make your first call.

What is Floom

Floom lets you hire AI workers — small, autonomous programs that do a real job (clean an inbox, draft follow-ups, screen candidates) on a schedule, on a trigger, or on demand. Every worker runs in an isolated sandbox, draws on your company brain, calls your connected tools, and holds anything outward-facing for approval.

This is the developer reference for Floom Cloud. Everything you can do in the dashboard you can also do programmatically — through the CLI, any MCP client, or the REST API. All three speak to the same backend and the same workspace data, so you can mix them freely.

Three ways to build

Pick the surface that fits where you work. They cover the same core operations and share one backend — they mainly differ in ergonomics and how much they wrap for you (polling, streaming, auth).

CLI

floom in your terminal

Scripts, CI, and humans who live in a shell.

MCP

58 tools for any agent

Claude Code, Cursor, Codex — drive Floom from your assistant.

REST API

HTTP for everything else

Backends, webhooks, and custom integrations.

Quickstart

The fastest path is the CLI. It pairs with your account over a one-time device code and stores a token locally — no dashboard required.

$ npm install -g @floomhq/floom$ floom login --cloud$ floom workers list$ floom run inbox-cleaner --input limit=20

Prefer raw HTTP? Mint a personal access token in the dashboard (Settings → API tokens) or with floom, then call the API directly. The token carries your workspace, so most requests need nothing else.

curl

curl https://workeros-api.floom.dev/api/workers \
  -H "x-floom-token: floom_xxx"

Workspaces

Every worker, run, secret, and connection belongs to a workspace. Your token resolves to one workspace by default; pass x-workeros-workspace: <id> to target another you belong to.

Base URLs

GEThttps://workeros-api.floom.dev

REST API (and the engine routes, mounted at /, /api, /v1).

POSThttps://workeros-api.floom.dev/mcp/{workspace_id}

MCP endpoint (HTTP JSON-RPC) for a specific workspace.

GEThttps://floom.dev/app

Dashboard (the hosted UI).

The REST surface is the engine API mounted under several prefixes for client convenience — /workers, /api/workers, and /v1/workers are the same endpoint. This reference uses the /api prefix throughout.

Core concepts

Worker — a hired job. A bundle of worker.yml (the contract: trigger, inputs, tools, approval rules) plus run.py / SKILL.md code. Versioned in git.
Run — one execution of a worker. Has a status, logs, outputs, artifacts, and a transcript; may pause for an approval.
Context (brain) — a pack of files (SOPs, pricing, datasets) a worker reads at run time. Large data lives here, not in the worker bundle.
Connection — an authorized third-party account (Gmail, Slack, GitHub via Composio) or a custom MCP server a worker can call.
Secret — an encrypted credential (API key, token) injected into a worker’s sandbox by name.
Approval — a hold placed on an outward-facing action until a human approves or rejects it.
Workspace — the tenant boundary. Members share workers, brain, connections, and the run record.

Start with Authentication to get a token, then jump to the surface you want: CLI, MCP, or REST API.