Run

REST API

Every app gets a REST run endpoint at POST /api/apps/:slug/run. Public apps need no auth; private apps require a session cookie or agent token.

Run an app#

Public app

# Public app — no auth needed
curl -X POST https://floom.dev/api/apps/meeting-action-items/run \
  -H 'Content-Type: application/json' \
  -d '{"inputs":{"transcript":"Alice: Let us ship by Friday..."}}'

Private app

# Private app — agent token required
curl -X POST https://floom.dev/api/apps/my-private-app/run \
  -H 'Authorization: Bearer YOUR_AGENT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"inputs":{"text":"Run this securely"}}'

Response envelope:

Response

{
  "execution_id": "exec_abc123",
  "status": "queued",
  "output": null,
  "error": null,
  "view_token": "<view-token>"
}

Sandbox boot failures return HTTP 502 with error: sandbox_unavailable. Install errors and non-zero exits return HTTP 200 with status: failed.

Async runs#

Apps that may run longer than 250 seconds should be called without ?wait=true. The default POST returns 202 with an execution_id immediately; your code then polls until the status is terminal.

POST without ?wait=true: returns 202 { execution_id, status: "queued" } right away.
Poll GET /api/executions/:id every 1-2 s until status is succeeded, failed, timed_out, or cancelled.
Read the result from .output in the final poll response.

Step 1: fire and forget

# Fire-and-forget — returns 202 immediately
curl -X POST https://floom.dev/api/apps/my-app/run \
  -H 'Authorization: Bearer YOUR_AGENT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"inputs":{"text":"process this"}}'
# Response: 202 { "execution_id": "exec_abc123", "status": "queued" }

Step 2: poll for result

# Poll until terminal status
while true; do
  STATUS=$(curl -s https://floom.dev/api/executions/exec_abc123 \
    -H 'Authorization: Bearer YOUR_AGENT_TOKEN' | jq -r '.status')
  echo "Status: $STATUS"
  if [[ "$STATUS" == "succeeded" || "$STATUS" == "failed" || "$STATUS" == "timed_out" || "$STATUS" == "cancelled" ]]; then
    break
  fi
  sleep 1
done

# Read the result
curl -s https://floom.dev/api/executions/exec_abc123 \
  -H 'Authorization: Bearer YOUR_AGENT_TOKEN' | jq '.output'

The floom run CLI does this polling automatically; no extra code needed for command-line use.

Sync runs (?wait=true)#

Pass ?wait=true to wait up to 250 s for completion. Use only when your app reliably finishes within 250 s.

Sync style (up to 250s budget)

# Sync style with up to 250s budget — blocks until done or times out
curl -X POST 'https://floom.dev/api/apps/my-app/run?wait=true' \
  -H 'Authorization: Bearer YOUR_AGENT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"inputs":{"text":"process this"}}'

Async mode (no ?wait=true) is the default for REST calls. Only use sync when you need a single blocking response.

GET /api/executions/:id#

Returns the current status and output of any execution you own.

Status	Meaning
queued	Waiting for a sandbox to become available.
running	Sandbox started, command executing.
succeeded	Command exited 0. Output in .output.
failed	Command exited non-zero. Details in .error.
timed_out	Exceeded 290-second cap.
cancelled	Manually cancelled or auto-failed by cron sweep.