HTTP API

Base URL https://api.froogcorp.com/v1. Authenticate with an API key from the dashboard as a bearer token. Keys expire after 90 days by default (choose up to a year, or never, when you create one), and an expired key gets 401 api_key_expired. Keys can be scoped to actions and sandboxes. Requests and responses are JSON, and errors look like {"error": {"code": "...", "message": "...", "request_id": "req_..."}}. Every response has an X-Request-Id header with the same id. Quote it when you report a problem.

Rate limit. Each account can send 10,000 requests per 60 seconds, to any endpoint: all its API keys, in-sandbox keys and dashboard sessions together, from any address. Requests without a valid key count per IP address instead (each /64 over IPv6), 10,000 per 60 seconds. Sandboxes on one froog host share its IPv4 address, so their requests without a key aren't counted together, and over IPv6 each sandbox counts by its own address. A request counts once when it arrives, so a long-running one counts once. Every response carries RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (seconds until the window ends) and RateLimit-Policy (10000;w=60). Past the limit you get 429 account_rate_limited (or 429 ip_rate_limited without a key) with Retry-After in seconds.

$ curl -s https://api.froogcorp.com/v1/sandboxes \
    -H "Authorization: Bearer $FROOG_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name": "ci-1", "size": "small"}'

$ curl -s https://api.froogcorp.com/v1/sandboxes/ci-1/exec \
    -H "Authorization: Bearer $FROOG_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"command": "uname -a", "timeout_secs": 60}'
{"exit_code":0,"stdout":"Linux froog-… 6.8.0 …\n","stderr":""}

Creating, starting, forking and restoring fail with 402 subscription_required without a plan, 402 insufficient_funds when this period's plan usage and the wallet are used up, and 429 trial_compute_limit_reached past the free trial's 25 hours. During the trial, no auto-stop or a timer over 2 hours fails with 403 trial_auto_stop_required, and an account whose card already had a trial elsewhere gets 402 trial_blocked. xlarge below the $100 plan fails with 403 plan_required, a paused plan with 402 plan_paused, and a closed account with 403 account_closed. In an organization, a member past their caps gets 429 member_limit_reached or 402 team_member_cap_reached. Past a start limit (per minute, hour or day, see GET /v1/limits) without extra starts they fail with 429 limit_reached and the headers Retry-After (seconds until a start is free again), RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy (e.g. 10;w=60). Creating, stopping, starting, forking and restoring return 202 Accepted and continue in the background. Poll GET /v1/sandboxes/{name} until state is running or stopped.

Retries. Send an Idempotency-Key header (any unique string up to 255 characters) with POST /sandboxes and POST /sandboxes/{name}/fork to make them safe to retry after a timeout or a dropped connection. A retry with the same key within 24 hours returns the first response, with the same sandboxes and status and an Idempotent-Replayed: true header, instead of creating more. The same key with a different request gets 422 idempotency_key_reused, and a retry while the first request is still running gets 409 idempotency_key_in_use. Errors aren't kept, so a retry after one runs again. Keys belong to the account. froog new and froog fork send one and retry with it when the connection drops.

Streamed exec. With "stream": true (or Accept: application/x-ndjson), POST /sandboxes/{name}/exec answers application/x-ndjson: one JSON object per line, as the output arrives. First {"type":"started","command_id":…}, then {"type":"stdout","data":…} and {"type":"stderr","data":…} chunks (UTF-8 text), then exactly one {"type":"exit","exit_code":0,"timed_out":false}, or {"type":"error","code":…,"message":…} if the connection to the sandbox broke. Errors before the command starts (not running, bad request) are ordinary JSON errors. Hanging up stops the command. It's in the history with mode stream. froog exec streams this way, and the SDKs have execStream (exec_stream in Python).

Watching files and ports. Two more NDJSON streams stay open while you listen (up to timeout_secs, 1-3600, default 3600, then reconnect). GET /sandboxes/{name}/files/watch?path=src&recursive=true sends {"type":"ready","method":"inotify"}, then {"type":"change","event":"create"|"modify"|"delete","path":…,"dir":…} for each change under the path (a file written and closed is modify, a move is a delete and a create), then {"type":"end","reason":"timeout"}. Paths come back as given: relative to ~ or absolute. It uses inotify where the image has inotify-tools, and otherwise scans every second ("method":"poll"), which sees changes up to a second late. A path that doesn't exist sends {"type":"error"}. GET /sandboxes/{name}/ports/watch sends ready, then {"type":"open"|"close","port":3000,"protocol":"tcp"} as TCP ports start or stop listening on any address (the ones already listening come first as open), read every second. Both need a running sandbox (or start an auto-start one), file.read and sandbox.read respectively, and each holds one of the sandbox's 8 command slots while open. SDKs: sb.files.watch(path) yields the changes. The flat watchFiles and watchPorts yield every event.

$ curl -sN https://api.froogcorp.com/v1/sandboxes/ci-1/exec \
    -H "Authorization: Bearer $FROOG_API_KEY" -H "Content-Type: application/json" \
    -d '{"command": "make test", "stream": true}'
{"type":"started","command_id":"cmd_…"}
{"type":"stdout","data":"ok  build\n"}
{"type":"exit","exit_code":0,"timed_out":false}

$ KEY=$(uuidgen)   # reuse it for every retry of this request
$ curl -s --retry 3 https://api.froogcorp.com/v1/sandboxes \
    -H "Authorization: Bearer $FROOG_API_KEY" \
    -H "Idempotency-Key: $KEY" \
    -H "Content-Type: application/json" \
    -d '{"name": "ci-2"}'