REST API

The HTTP API behind the CLI, MCP, and dashboard.

Base URLs & versions

One HTTP API powers the CLI, MCP server, and dashboard. It’s JSON in, JSON out, and authenticated with an API token.

GEThttps://workeros-api.floom.dev

Production API.

Routes are mounted under several prefixes for client convenience — /workers, /api/workers, /v1/workers, and /api/v1/workers all hit the same handler. This reference uses /api. There is no breaking-version split today; /v1 is an alias.

Authentication

Send a personal or workspace token in the x-floom-token header (a Supabase Authorization: Bearer JWT also works). Scope to a workspace with x-workeros-workspace. Full detail on the Authentication page.

curl

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

Conventions

Content type — request and response bodies are JSON (application/json), except uploads (multipart) and downloads (binary/ZIP).
IDs — resources use stable string ids (worker ids are human-readable slugs; runs are run_…).
Timestamps — ISO-8601 UTC strings.
Methods — GET reads, POST creates/acts, PUT/PATCH update, DELETE removes.

Pagination

Most list endpoints accept limit and offset; the default and cap vary by endpoint (for example, /runs defaults to 50 with a max of 200). Runs also support a stable cursor for deep pagination — pass both cursor fields together:

limitnumber

Page size. Endpoint-specific default and maximum.

offsetnumber

Rows to skip. Default: 0.

before_created_atstring

Runs only — return runs created before this ISO timestamp.

before_idstring

Runs only — the id at that timestamp; pass alongside before_created_at as a stable cursor.

curl

curl "https://workeros-api.floom.dev/api/runs?limit=50&before_created_at=2026-06-01T00:00:00Z" \
  -H "x-floom-token: floom_xxx"

Errors & rate limits

Errors use standard HTTP status codes with a JSON body:

error

{ "detail": "Worker not found" }

400Bad Request

Malformed input or validation failure.

401Unauthorized

Missing or invalid credential.

403Forbidden

Not a member of the workspace, or insufficient permission.

404Not Found

No such resource (or not visible to you).

409Conflict

Resource already exists / conflicting state.

429Too Many Requests

Rate limited — honor the Retry-After header.

Rate limits

List endpoints are capped (around 240 requests/min per identity) to prevent scraping; sensitive auth routes are tighter. A 429 includes Retry-After (seconds).

Webhook triggers

A worker with a webhook trigger gets a secret-protected URL. POST any JSON body to start a run — the body becomes the worker’s input payload. The token query parameter must match the worker’s webhook secret.

curl

curl -X POST "https://workeros-api.floom.dev/api/webhooks/<worker_id>?token=<secret>" \
  -H "content-type: application/json" \
  -d '{ "email": "lead@acme.com", "plan": "pro" }'
# → { "status": "queued", "run_id": "run_..." }

Rotate the secret with workers.update (webhook_secret_rotate: true) or in the dashboard. Outbound notifications go the other way — configure worker alerts to POST a webhook or email on run events.

Endpoint reference

Grouped by resource. Paths show the /api prefix; the same routes exist at / and /v1. Many resources also expose share-links, public (token-scoped) variants, and version history beyond what’s listed here.

Workers

Create, read, edit, version, and control workers.

GET/api/workers

List workers. Query: limit, offset, status, starred, q. Use ?shape=list for a trimmed payload.

POST/api/workers

Create a worker from a manifest + files.

GET/api/workers/{id}

Get a worker’s full detail (config, files, contexts, stats).

PUT/api/workers/{id}/files

Replace the worker’s files ({ files: [{ path, content }] }).

POST/api/workers/{id}/pause

Disable the worker (no new runs).

POST/api/workers/{id}/resume

Re-enable the worker.

POST/api/workers/{id}/archive

Archive (soft-hide) the worker.

POST/api/workers/{id}/restore

Restore an archived worker.

DELETE/api/workers/{id}

Delete the worker.

PATCH/api/workers/{id}/visibility

Set visibility: private | shared | public.

GET/api/workers/{id}/versions

List version history (git).

POST/api/workers/{id}/rollback/{sha}

Revert the worker to a previous version.

GET/api/workers/{id}/sample-input

Example input values for the worker.

GET/api/workers/{id}/bundle.zip

Download the worker bundle as a ZIP.

GET/api/workers/{id}/stats

Run stats (counts, error rate, cost, latency).

GET/api/workers/{id}/runs/timeseries

Daily run counts (last 30 days).

GET/api/workers/{id}/logs

Cross-run event logs for the worker.

GET/api/workers/{id}/alerts

List alerts; POST to create, DELETE /{alert_id} to remove.

Runs

Trigger runs, read results, stream live, cancel, and export.

GET/api/runs

List runs. Query: worker_id, status, limit, offset, before_created_at (cursor).

POST/api/workers/{worker_id}/runs

Trigger a run. Body is RunCreate: { inputs, trigger_source? }. Returns { status, run_id }.

GET/api/runs/{run_id}

Get a run’s detail (status, outputs, logs, artifacts, approvals).

POST/api/runs/{run_id}/cancel

Cancel a queued or running run.

GET/api/runs/{run_id}/logs

Run logs as newline-delimited JSON. Query: level, limit.

GET/api/runs/{run_id}/logs/stream

Stream logs via Server-Sent Events. Resume with last_event_id.

GET/api/runs/{run_id}/stream

Stream run parts (queued → running → output) via SSE.

GET/api/runs/{run_id}/events

Stream structured run events via SSE.

GET/api/runs/{run_id}/download

Download the run bundle (ZIP).

GET/api/runs/{run_id}/artifacts/{artifact_id}/download

Download a single run artifact.

GET/api/runs/export.csv

Export runs as CSV. Query: worker_id (optional).

Approvals

Resolve runs paused for a human decision.

GET/api/approvals

List pending approvals. Query: limit, offset, run_id, status.

GET/api/approvals/count

Count pending approvals.

POST/api/runs/{run_id}/approve

Approve a run. Optional body: annotation, edited output.

POST/api/runs/{run_id}/reject

Reject a run. Optional body: reason.

POST/api/approvals/{approval_id}/approve

Approve by approval id (also …/reject).

Contexts (brain)

Manage the file packs workers read at run time.

GET/api/contexts

List context packs.

POST/api/contexts/{name}

Create a context pack.

GET/api/contexts/{name}

Get a context’s files and metadata.

DELETE/api/contexts/{name}

Delete a context.

GET/api/contexts/{name}/files/{path}

Read a file (text or binary).

PUT/api/contexts/{name}/files/{path}

Create or update a file.

DELETE/api/contexts/{name}/files/{path}

Delete a file.

POST/api/contexts/{name}/upload

Bulk-upload files (multipart).

PUT/api/contexts/{name}/visibility

Set visibility: private | workspace | shared | public.

GET/api/contexts/{name}/versions

List a context’s versions.

POST/api/contexts/{name}/rollback/{sha}

Revert the context to a previous version.

Connections

Authorize apps (OAuth) and register MCP servers.

GET/api/connections

List connections.

POST/api/connections

Start an OAuth connection; returns an authorization URL.

POST/api/connections/mcp

GET/api/connections/{id}/status

Poll a connection’s status (pending → active).

POST/api/connections/{id}/test

Test the connection by making a live call.

GET/api/connections/{id}/tools

List the tools a connection exposes.

DELETE/api/connections/{id}

Revoke a connection.

Secrets

Encrypted credentials, referenced by name in worker bundles.

GET/api/secrets

List secret names and status (values are never returned).

POST/api/secrets/{name}

Create or update a secret ({ value }).

POST/api/secrets/{name}/test

Validate the secret against its provider.

DELETE/api/secrets/{name}

Delete a secret.

Integrations & MCP tools

Browse the catalog and register reusable MCP tools.

GET/api/integrations/catalog

Browse apps. Query: page, limit, search, category.

GET/api/integrations/catalog/{slug}/tools

List an app’s tools/actions.

GET/api/mcp-tools

List registered MCP tools (also POST to create, PUT/DELETE /{id}).

Workspaces & members

Tenancy, membership, and workspace API tokens.

GET/api/workspaces

List the workspaces you belong to.

POST/api/workspaces

Create a workspace.

PATCH/api/workspaces/{id}

Update a workspace (name, settings).

DELETE/api/workspaces/{id}

Delete a workspace (owner only).

POST/api/workspaces/{id}/select

Set the active workspace (cookie).

GET/api/workspaces/{id}/members

List workspace members.

POST/api/workspaces/{id}/members/invite

Invite a member by email.

PATCH/api/workspaces/{id}/members/{user_id}/role

Change a member’s role.

GET/api/workspace/tokens

List workspace tokens (POST to create, DELETE /{id} to revoke).

Auth & tokens

Identity, sessions, and personal tokens. See the Authentication page.

GET/auth/me

Current user profile + active workspace (also aliased at /api/auth/me).

GET/auth/tokens

List personal tokens (POST to create, DELETE /{id} to revoke).

POST/auth/refresh

Mint a fresh session JWT from the refresh cookie.

POST/api/cli-auth/devices

Start a CLI device-flow login.

POST/auth/cli-exchange

Exchange an approved device code for tokens (Cloud).

System & health

Health checks, platform info, and workspace overview.

GET/healthz

Liveness check → { status: "ok" }. Unauthenticated.

GET/health

Minimal public health check.

GET/health/details

Detailed dependency health (db, disk, providers). Admin only.

GET/api/system/info

API version and environment.

GET/api/system/overview

Workspace overview: recent runs, active workers, stats.

GET/api/system/platform-config

Supported providers and available secrets.

Chat & conversations

Drive the workspace agent and read its history.

POST/api/chat

Stream a chat completion with the workspace agent (SSE).

GET/api/conversations

List conversations.

GET/api/conversations/{id}

Get a conversation’s messages.

Worked examples

Run a worker and poll for the result

bash

# 1. trigger
RUN=$(curl -s -X POST https://workeros-api.floom.dev/api/workers/inbox-cleaner/runs \
  -H "x-floom-token: floom_xxx" -H "content-type: application/json" \
  -d '{ "inputs": { "limit": 20 } }' | jq -r .run_id)

# 2. poll until it settles
curl -s "https://workeros-api.floom.dev/api/runs/$RUN" \
  -H "x-floom-token: floom_xxx" | jq '{ status, outputs }'

Stream a run live (SSE)

bash

curl -N "https://workeros-api.floom.dev/api/runs/<run_id>/events" \
  -H "x-floom-token: floom_xxx"

Prefer a higher-level surface?

The CLI and MCP server wrap these endpoints with polling, streaming, and auth handled for you.