Launch HN: Coasty (YC S26) – An API for computer-use agents

YC-backed startup Coasty launched an API that lets developers run autonomous computer-use agents on managed machines, compose them into workflows, and drop to lower-level prediction primitives when needed. The API supports task runs, workflows, stateful sessions, and stateless prediction steps, with test keys available for development.

API reference Run autonomous tasks on managed machines, compose them into workflows, and drop to prediction primitives only when you need direct control. llms.txt /docs/llms.txt Introduction Start with a task run runs : give Coasty a goal and a machine, then let the agent drive to completion. Use workflows workflows when an automation needs many tasks, branches, loops, approvals, or shared outputs. Machines machines provide the managed computer those tasks operate. The prediction endpoints are lower-level primitives for teams that need to own the control loop themselves. Use sessions sessions for a stateful screenshot loop, predict predict for a stateless step, grounding for coordinates, and parse for structured actions. Everything is normal HTTPS to https://coasty.ai/v1 , so you can choose the highest-level surface that fits the job and drop down only when you need finer control. Authentication Every API-key-authenticated request must include your secret key. The four health probes are public, and webhook ingress uses its documented Coasty-Signature HMAC credential instead. For API-key operations, the canonical form is the X-API-Key header, but Authorization: Bearer <key works too: a blank X-API-Key falls through to the Bearer header. Pick one form and send the raw key. Do not paste the literal text Bearer inside X-API-Key ; that is the single most common first-day mistake and it returns 401 INVALID API KEY . Keys are created and revoked from the API keys /developers/keys page. Treat a key like a password: keep it server-side, store it in an environment variable, and never commit it or ship it in client-side code. X-API-Key: sk-coasty-live-your key here sk-coasty-test- key never bills and runs against mock VMs, yet exercises the exact same request and response shapes its X-Credits-Charged and usage.cost cents are always 0 , so you can build and run CI confidently before flipping to a live key. Run your first task Your first autonomous task needs an API key and a machine. Grab a test key from the API keys /developers/keys page it never bills , then use an existing machine or provision one machines . Set the key in your shell: export COASTY API KEY="sk-coasty-test-your key here" Start the task with POST /v1/runs . Replace the example machine id , describe the outcome in task , and send an Idempotency-Key so a retried create cannot start a duplicate run. The complete example starts the run and follows it to a terminal state: python import os, time, requests BASE = "https://coasty.ai/v1" HEADERS = {"X-API-Key": os.environ "COASTY API KEY" } TERMINAL = {"succeeded", "failed", "cancelled", "timed out"} 1. Start a run. Idempotency-Key makes a retried create safe. run = requests.post f"{BASE}/runs", headers={ HEADERS, "Idempotency-Key": "order-4821"}, json={ "machine id": "mch test 0123456789abcdef", "task": "Open the billing page and download the latest invoice as PDF", "cua version": "v5", any of v1/v3/v4/v5, all tiers; omit to use the v5 default "max steps": 40, "on awaiting human": "pause", }, timeout=30, .json run id = run "id" print run "status" "queued" webhook secret = run.get "webhook secret" shown once; store it now 2. Poll until terminal. while True: run = requests.get f"{BASE}/runs/{run id}", headers=HEADERS, timeout=30 .json print run "status" , run "steps completed" , "steps" if run "status" in TERMINAL: break time.sleep 2 print run "result" {"passed": ..., "status": ..., "summary": ...} The create response begins at queued . Coasty then drives the machine, records each step, and finishes as succeeded , failed , cancelled , or timed out . Your application can poll, subscribe to the event stream, or receive signed webhooks; it does not need to execute each prediction itself. Task runs A run hands the agent a task and a machine, then drives it to completion on our side. The agent loops autonomously, verifies its own work pass or fail , can pause for a human when it hits a wall, bills $0.05 per completed step from your dollar API wallet $0.08/step on the legacy v1 engine , and streams every event live. You start one call and watch, instead of running the predict loop yourself. Create a run with POST /v1/runs . The two required fields are machine id and task . The response is an agent.run object with status of queued , plus a one-time webhook secret you store to verify webhooks run-webhooks . Send an Idempotency-Key header to make a retried create safe. python import os, time, requests BASE = "https://coasty.ai/v1" HEADERS = {"X-API-Key": os.environ "COASTY API KEY" } TERMINAL = {"succeeded", "failed", "cancelled", "timed out"} 1. Start a run. Idempotency-Key makes a retried create safe. run = requests.post f"{BASE}/runs", headers={ HEADERS, "Idempotency-Key": "order-4821"}, json={ "machine id": "mch test 0123456789abcdef", "task": "Open the billing page and download the latest invoice as PDF", "cua version": "v5", any of v1/v3/v4/v5, all tiers; omit to use the v5 default "max steps": 40, "on awaiting human": "pause", }, timeout=30, .json run id = run "id" print run "status" "queued" webhook secret = run.get "webhook secret" shown once; store it now 2. Poll until terminal. while True: run = requests.get f"{BASE}/runs/{run id}", headers=HEADERS, timeout=30 .json print run "status" , run "steps completed" , "steps" if run "status" in TERMINAL: break time.sleep 2 print run "result" {"passed": ..., "status": ..., "summary": ...} { "id": "run 7a1b2c3d", "object": "agent.run", "status": "queued", "machine id": "mch test 0123456789abcdef", "task": "Open the billing page and download the latest invoice as PDF", "cua version": "v5", "instructions": null, "max steps": 40, "on awaiting human": "pause", "steps completed": 0, "credits charged": 0, "cost cents": 0, "result": null, "error": null, "awaiting human reason": null, "metadata": { "team": "finance" }, "webhook url": "https://example.com/hooks/coasty", "created at": "2026-06-01T12:00:00Z", "started at": null, "awaiting human since": null, "finished at": null, "request id": "req 4f9a2b1c", "webhook secret": "whsec one time value shown here" } queued to running , can bounce between running and awaiting human , and ends in one of succeeded , failed , cancelled , or timed out . Terminal states are immutable, so it is always safe to stop polling once you reach one. Runs need the runs:read and runs:write scopes, granted to new keys by default. Streaming events GET /v1/runs/{id}/events returns a Server-Sent Events stream so you can follow a run as it happens, instead of polling. Each event has a type and a numeric id the sequence number . If your connection drops, reconnect and replay everything you missed by sending the last sequence you saw as a Last-Event-ID header, or as the ?after= query parameter. The stream closes after the done event. python import os, httpx BASE = "https://coasty.ai/v1" HEADERS = {"X-API-Key": os.environ "COASTY API KEY" } run id = "run 7a1b" last seq = 0 persist this so a reconnect can replay httpx streams the SSE body line by line. Reconnect with Last-Event-ID. with httpx.stream "GET", f"{BASE}/runs/{run id}/events", headers={ HEADERS, "Last-Event-ID": str last seq }, timeout=None, as resp: event type = "message" for line in resp.iter lines : if line.startswith "id:" : last seq = int line 3: .strip elif line.startswith "event:" : event type = line 6: .strip elif line.startswith "data:" : data = line 5: .strip print event type, data if event type == "done": break Human takeover Some steps need a person: a captcha, a one-time code, a judgment call. When the agent reaches one and on awaiting human is pause , the run moves to awaiting human and emits an awaiting human event with a reason. A human completes the blocking step in the same machine session , then you hand control back with POST /v1/runs/{id}/resume and an optional note . Resume is only valid while the status is awaiting human . python import os, requests BASE = "https://coasty.ai/v1" HEADERS = {"X-API-Key": os.environ "COASTY API KEY" } run id = "run 7a1b" run = requests.get f"{BASE}/runs/{run id}", headers=HEADERS, timeout=30 .json resume is only valid while status == "awaiting human". if run "status" == "awaiting human": print "paused:", run "awaiting human reason" ... a human completes the blocking step out of band ... resumed = requests.post f"{BASE}/runs/{run id}/resume", headers=HEADERS, json={"note": "Solved the captcha; continue"}, timeout=30, .json print resumed "status" back to "running" status == awaiting human with awaiting human reason set , the SSE awaiting human event, or the run.awaiting human webhook. After resume, the run returns to running and emits a resumed event. Set on awaiting human to fail or cancel at create time if you would rather the run stop than wait for a human. Webhooks Pass a webhook url https only when you create a run and we POST a signed callback at each lifecycle transition. The response to your create call includes a webhook secret exactly once: store it, because every callback is signed with it. Each request carries a Coasty-Signature header of the form t=<unix ts ,v1=<hex . To verify, build the signed payload as "<t ." + raw request body , compute HMAC-SHA256 over it keyed by the webhook secret , and compare against v1 with a constant-time check. Always hash the raw body bytes, before any JSON re-serialisation. python import hashlib, hmac, os, requests BASE = "https://coasty.ai/v1" HEADERS = {"X-API-Key": os.environ "COASTY API KEY" } 1. Create a run with a webhook url. webhook secret is returned exactly once. run = requests.post f"{BASE}/runs", headers=HEADERS, json={ "machine id": "mch test 0123456789abcdef", "task": "Reconcile the invoice against the order", "webhook url": "https://example.com/hooks/coasty", }, timeout=30, .json webhook secret = run "webhook secret" persist this securely 2. In your webhook handler, verify the Coasty-Signature header. def verify raw body: bytes, signature header: str, secret: str - bool: parts = dict p.split "=", 1 for p in signature header.split "," signed = f"{parts 't' }.".encode + raw body expected = hmac.new secret.encode , signed, hashlib.sha256 .hexdigest return hmac.compare digest expected, parts "v1" Example your framework supplies the raw body + header : ok = verify request.body, request.headers "Coasty-Signature" , webhook secret Bring your own model By default every LLM call in the computer-use harness runs on Coasty's managed models. BYOK bring your own key flips that: opt in and the entire harness the worker, grounding, the code agent, and compaction; every LLM call runs on your own Anthropic or OpenAI account instead. Opt-in is always explicit, per request or per stored key. provider: "managed" or omitting llm entirely keeps the platform default, unchanged. There are two ways to hand over a key. Store it once with PUT /v1/llm/keys/{provider} encrypted with AES-256-GCM at rest; only a sha256-prefix fingerprint is ever echoed back , or send it per request in headers. A header key takes precedence over the stored key. Sending a key without a provider returns 422 . X-LLM-Provider: anthropic X-LLM-Api-Key: sk-ant-your key here X-LLM-Model: claude-sonnet-4-6 The headers work on POST /v1/predict , POST /v1/runs , POST /v1/workflows/{id}/runs , POST /v1/sessions , and POST /v1/schedules . Stored keys are managed through three endpoints, gated by the llm keys scope granted to new live keys by default . These endpoints require a live key; sandbox keys cannot read, overwrite, or delete the production credential store: python import os, requests BASE = "https://coasty.ai/v1" HEADERS = {"X-API-Key": os.environ "COASTY API KEY" } Store upsert your own Anthropic key. Encrypted at rest; never echoed back. stored = requests.put f"{BASE}/llm/keys/anthropic", headers=HEADERS, json={"api key": os.environ "ANTHROPIC API KEY" }, timeout=30, .json print stored {"provider": "anthropic", "key fingerprint": "a1b2c3d4", "stored": true} List stored keys: provider, fingerprint, timestamps. Never the key itself. keys = requests.get f"{BASE}/llm/keys", headers=HEADERS, timeout=30 .json for k in keys "keys" : print k "provider" , k "key fingerprint" Delete when you rotate away 404 LLM KEY NOT FOUND when none is stored requests.delete f"{BASE}/llm/keys/anthropic", headers=HEADERS, timeout=30 On the request body, the same endpoints accept an llm object that selects the provider and, optionally, a model per harness role. It deliberately has no api key field a 422 if you attempt one : keys ride headers or the encrypted store only, so they can never be echoed in run objects, webhooks, or idempotency replays. python import os, requests BASE = "https://coasty.ai/v1" HEADERS = {"X-API-Key": os.environ "COASTY API KEY" } Start a run on YOUR Anthropic key stored earlier via PUT /llm/keys/anthropic . The llm block deliberately has NO api key field 422 if you try : keys ride headers or the encrypted store only, never request bodies. run = requests.post f"{BASE}/runs", headers=HEADERS, json={ "machine id": "mch test 0123456789abcdef", "task": "Open the billing page and download the latest invoice as PDF", "llm": { "provider": "anthropic", or "openai"; "managed" = platform default "model": "claude-sonnet-4-6", any model on your account vision-capable "compaction model": "claude-haiku-4-5", optional per-role override }, }, timeout=30, .json Per-request variant: send the key in headers instead of storing it. A header key takes precedence over the stored key for this request only. byok headers = { HEADERS, "X-LLM-Provider": "anthropic", "X-LLM-Api-Key": os.environ "ANTHROPIC API KEY" , "X-LLM-Model": "claude-sonnet-4-6", } The run echoes a non-secret llm block; the key itself is never returned. run = requests.get f"{BASE}/runs/{run 'id' }", headers=HEADERS, timeout=30 .json print run "llm" {"provider": ..., "model": ..., "key fingerprint": ..., "key source": ..., "key scrubbed": ...} Per-role overrides exist for tuning cost against quality: run compaction on a cheaper model while the worker stays on the default, for example. For runs, workflows, and schedules the key is snapshotted encrypted into the run, so crash-recovery on another replica keeps using your key; it is scrubbed the moment the run reaches a terminal state. GET /v1/runs/{id} echoes a non-secret llm block: { provider, model, key fingerprint, key source, key scrubbed }. Schedules store only the non-secret preference; at fire time the current stored key is used. Delete the stored key and future firings fail loudly with LLM KEY NOT CONFIGURED ; they never silently run on platform keys. grounding model to experiment before committing a cheaper or different model to that role. LLM KEY NOT CONFIGURED , LLM KEY INVALID , LLM PROVIDER AUTH FAILED , LLM PROVIDER RATE LIMITED , LLM PROVIDER QUOTA EXCEEDED , and LLM PROVIDER ERROR .Billing: Coasty's per-call and per-step platform charges are unchanged with BYOK. The model tokens are billed by your provider account directly. Workflows A workflow composes many runs into one versioned program, with branching, loops, and guards expressed as a JSON DSL. Each task step is itself an agent run, so a workflow is the way to chain tasks, gate them on conditions, and pass results between them. Workflows are versioned: re-creating the same slug bumps the version, and a PUT does too. Create one with POST /v1/workflows . The slug must match a-z0-9 - . The response is a Workflow carrying an id , a version , and the current dsl version 2026-06-01 . python import os, requests BASE = "https://coasty.ai/v1" HEADERS = {"X-API-Key": os.environ "COASTY API KEY" } definition = { "steps": { "id": "fetch", "type": "task", "task": "Open order {{inputs.order id}} and read the invoice total", "save as": "invoice", }, { "id": "check", "type": "assert", "condition": {"op": "truthy", "value": "{{invoice.passed}}"}, "message": "Agent failed to read the invoice", }, { "id": "branch", "type": "if", "condition": {"op": "contains", "left": "{{invoice.result}}", "right": "PAID"}, "then": {"id": "ok", "type": "succeed", "output": {"state": "paid"}} , "else": {"id": "no", "type": "fail", "message": "Invoice not marked paid"} , }, , } 1. Create the workflow. Re-using the same slug bumps its version. wf = requests.post f"{BASE}/workflows", headers=HEADERS, json={ "name": "Invoice reconciliation", "slug": "invoice-reconcile", "inputs schema": {"type": "object", "properties": {"order id": {"type": "string"}}}, "definition": definition, }, timeout=30, .json print wf "id" , "v", wf "version" , wf "dsl version" 2. Start a run of the saved workflow. run = requests.post f"{BASE}/workflows/{wf 'id' }/runs", headers=HEADERS, json={"inputs": {"order id": "ord 4821"}, "machine id": "mch test 0123456789abcdef", "budget cents": 500}, timeout=30, .json print run "id" , run "status" workflows:read and workflows:write scopes, granted to new keys by default. See the Workflow DSL workflow-dsl for the full step and condition catalogue. Workflow DSL The DSL dsl version 2026-06-01 is a JSON object with a steps array and an optional output . Each step has an id and a type . A task step runs the agent and binds its result { status, passed, result, run id, steps, error } under both its save as name and its step id, so later steps can read it. { "dsl version": "2026-06-01", "definition": { "steps": { "id": "fetch", "type": "task", "task": "Open order {{inputs.order id}} and read the invoice total", "save as": "invoice" }, { "id": "check", "type": "assert", "condition": { "op": "truthy", "value": "{{invoice.passed}}" }, "message": "Agent failed to read the invoice" }, { "id": "branch", "type": "if", "condition": { "op": "contains", "left": "{{invoice.result}}", "right": "PAID" }, "then": { "id": "ok", "type": "succeed", "output": { "state": "paid" } } , "else": { "id": "no", "type": "fail", "message": "Invoice not marked paid" } } , "output": { "paid": "{{invoice.result}}" } } } Conditions are structured rather than expression strings, which keeps them injection-safe. Each left , right , or value is either a literal or a {{path}} reference. Paths are dotted lookups into inputs. , vars. , and any step id or save as name. budget cents spend cap in USD cents; 0 means unlimited , max iterations loop cap , and deadline seconds wall-clock . A breach ends the run as failed or timed out .A definition is validated before it is accepted. The limits below are enforced at create and ad-hoc time, so an invalid definition is rejected with 422 VALIDATION ERROR rather than failing mid-run. definition is snapshotted into that run, so editing or replacing the workflow which bumps its version never changes runs already in flight. Each run records the workflow version it executed. Running workflows Start a saved workflow with POST /v1/workflows/{id}/runs , or run a definition inline without saving with POST /v1/workflows/runs by adding a definition and optional inputs schema to the same body. Both return a workflow.run . The body accepts inputs , a default machine id for task steps, and the budget cents , max iterations , and deadline seconds guards. An Idempotency-Key header is honoured here too. python import os, requests BASE = "https://coasty.ai/v1" HEADERS = {"X-API-Key": os.environ "COASTY API KEY" } POST /v1/workflows/runs runs a definition inline, without saving a workflow. run = requests.post f"{BASE}/workflows/runs", headers=HEADERS, json={ "machine id": "mch test 0123456789abcdef", "inputs": {"url": "https://status.example.com"}, "max iterations": 5, "definition": { "steps": { "id": "open", "type": "task", "save as": "page", "task": "Open {{inputs.url}} and report whether all systems are operational", }, { "id": "gate", "type": "assert", "condition": {"op": "truthy", "value": "{{page.passed}}"}, }, , }, }, timeout=30, .json print run "id" , run "status" object == "workflow.run" { "id": "wfr 5e6f7a8b", "object": "workflow.run", "status": "running", "workflow id": "wf 1a2b3c", "workflow version": 3, "machine id": "mch test 0123456789abcdef", "inputs": { "order id": "ord 4821" }, "output": null, "error": null, "awaiting human reason": null, "awaiting step id": null, "iterations used": 0, "spent cents": 0, "budget cents": 500, "created at": "2026-06-01T12:00:00Z", "started at": "2026-06-01T12:00:01Z", "finished at": null, "request id": "req 9c8b7a6d" } Provisioning A machine is a Coasty-managed cloud VM that an agent can see and control. You provision one, poll until it is running , then either hand it to a task run runs the agent drives it to done or drive it yourself with the action endpoints machine-connect . Machines are optional: /predict , /sessions , and /ground run against your screen. You only need a Coasty machine when you want the agent to execute on a VM Coasty hosts. Provision with POST /v1/machines . Only display name is required; everything else has a sensible default. The body rejects unknown fields, so a typo returns 422 VALIDATION ERROR rather than being silently ignored. curl -X POST https://coasty.ai/v1/machines \ -H "X-API-Key: $COASTY API KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $ uuidgen " \ -d '{"display name": "agent-box", "os type": "linux", "desktop enabled": true, "ttl minutes": 120}' Provisioning is asynchronous. The response returns immediately with the machine in creating status and a connection object whose secrets are redacted. The VM is not drivable yet — poll GET /v1/machines/{id} until status is running before you send actions or start a run. { "machine": { "id": "9f2c1e7a-3b6d-4c81-9a0e-2d5f8b1c4e90", "display name": "agent-box", "status": "creating", "os type": "linux", "desktop enabled": true, "cpu cores": 2, "memory gb": 4, "storage gb": 16, "public ip": null, "auto destroy at": "2026-06-17T14:30:00Z", "ttl minutes": 120, "is test": false, "created at": "2026-06-17T12:30:00Z" }, "connection": { "public ip": null, "ssh port": 22, "ssh username": "ubuntu", "has ssh key": true, "has vnc password": true }, "request id": "req 2f9c1a7b3e4d" } The machine object — returned by provision, list, and get: List your machines with GET /v1/machines newest first, ?limit= 1–200, default 50 — it returns { data, has more, request id } . Fetch one with GET /v1/machines/{id} . Both read straight from the registry, so they keep working even when provisioning is busy. machines:write scope, a wallet balance of at least 20 credits Unlimited-tier keys skip this , and room under your plan's concurrent-machine cap. Building? An sk-coasty-test- key returns a fully-shaped mock VM id mch test … , is test: true with zero billing — up to 5 at a time. Lifecycle & TTL A machine moves through a small set of statuses. status is the field you poll: drive the machine only while it is running . The runtime rate that applies in each status is shown below; exact per-hour USD numbers are in the Pricing pricing section. Start, stop, restart are POST /v1/machines/{id}/start and /stop , /restart . They are asynchronous: the call returns a transitional status starting / stopping and you poll until it settles. They are state-checked — starting a machine that is already running, or stopping one that is not running, returns 409 INVALID STATE with current state and allowed from in the body, so you can react without guessing. start is allowed from stopped or error ; stop only from running . Terminate with DELETE /v1/machines/{id} . This is permanent — the VM and its disk are destroyed and a later GET returns 404 MACHINE NOT FOUND . Delete is idempotent: deleting an already-gone machine still succeeds, so retries are safe. curl -X POST https://coasty.ai/v1/machines/$MACHINE ID/stop -H "X-API-Key: $COASTY API KEY" curl -X DELETE https://coasty.ai/v1/machines/$MACHINE ID -H "X-API-Key: $COASTY API KEY" Auto-destroy TTL . A machine left running bills until you destroy it, so set ttl minutes as a safety net. A background sweep every ~60s terminates a machine once its auto destroy at passes. Adjust it any time with PATCH /v1/machines/{id} : ttl minutes is measured from now so it doubles as a lease extension , accepts 5 – 10080 5 min to 7 days , and 0 clears auto-destroy entirely. Anything else is 400 INVALID TTL . Provisioning without a TTL works but adds a Warning response header nudging you to set one. curl -X PATCH https://coasty.ai/v1/machines/$MACHINE ID \ -H "X-API-Key: $COASTY API KEY" \ -H "Content-Type: application/json" \ -d '{"ttl minutes": 30}' Runtime billing. Machines bill the developer API wallet separate from any subscription credits by the minute, rounded down to whole credits in your favour. Running Linux is $0.05/hr , running Windows $0.09/hr , and a stopped or suspended machine the keep-alive rate of $0.01/hr ; creating , error , and terminated are free. Transitional states starting/stopping/restarting bill at the running rate. The per-call control endpoints actions, terminal, files, browser, screenshot, connection are never billed — you pay for runtime only. suspended rather than destroying it — your disk and snapshots are preserved. Top up the wallet and POST /start to resume. You can watch live accrual for every metered machine at GET /v1/billing/active . Connect & control Once a machine is running you can reach it three ways: connect directly over SSH/VNC, drive it through Coasty's control endpoints, or hand it to an agent run. Normal machine responses redact secrets and only expose has ssh key / has vnc password booleans plus ports. Connection secrets. GET /v1/machines/{id}/connection returns the full ssh private key pem , vnc password , public IP, and ports. It is gated by the opt-in connection:read scope not granted by default — request it when you mint the key , and the response is sent Cache-Control: no-store . Treat that payload like a password: never log it. SSH usernames are ubuntu on Linux and Administrator on Windows; VNC details exist only on desktop enabled machines. curl https://coasty.ai/v1/machines/$MACHINE ID/connection \ -H "X-API-Key: $COASTY API KEY" Screenshots & snapshots. GET /v1/machines/{id}/screenshot returns the current screen of a desktop machine a still-booting VM returns 502 SCREENSHOT FAILED — poll for running first . POST /v1/machines/{id}/snapshot captures a restorable image Linux , needs the snapshots:write scope, and is the one machine op with a flat fee $0.01 per snapshot . A conclusive pre-creation failure is refunded, confirmed by X-Credits-Refunded . A timeout, an upstream 5xx, or malformed post-dispatch result may already have created the image and instead returns terminal 503 SNAPSHOT OUTCOME UNKNOWN without a blind refund or re-execution. Boot a future machine from a confirmed snapshot with restore from snapshot: true . The control surface. Drive the VM directly with these endpoints. Each enforces a specific scope, and the high-risk ones — browser execute arbitrary JS and anything under connection:read — are opt-in. /actions/batch runs up to 50 steps and stops on the first error by default stop on error: false to continue ; /terminal truncates output to 5000 chars. curl -X POST https://coasty.ai/v1/machines/$MACHINE ID/terminal \ -H "X-API-Key: $COASTY API KEY" \ -H "Content-Type: application/json" \ -d '{"command": "ls -la /home/ubuntu"}' Idempotency & safety. The machine operations in the exact reserve-and-replay set — provision, snapshot, actions, action batches, browser, terminal, and file operations — accept an Idempotency-Key ≤128 chars . Lifecycle start/stop/restart, TTL updates, and termination do not. For supported operations, a duplicate key replays the original result without re-executing; a duplicate that arrives while the first is still running waits up to ~25s, then returns 409 IDEMPOTENCY IN FLIGHT . One nuance worth knowing: a command that never reached the VM a dispatch failure is not cached, so retrying the same key runs it fresh; a command the VM actually ran even if it errored is cached. Every machine lookup is ownership-scoped, so a wrong or someone-else's id returns 404 — never a leak. Full code list in Errors errors . Predict POST /v1/predict is the low-level, stateless prediction primitive. Each call is independent: you provide the full context, execute the returned actions, capture the next screenshot, and decide when to call again. Use it when your application must own that loop. For an autonomous goal, start a task run runs . When a manually driven loop needs server-side trajectory memory, reach for sessions sessions instead. The response is the standard prediction shape, covered in Response format responses . Sessions A session keeps the trajectory — the running history of screenshots and actions — on our side, so each step only needs the latest screenshot and instruction. This produces better multi-step behaviour on long tasks and keeps your request bodies small. Create a session once, step through the task, then delete it to release your concurrency quota. python import base64, os, requests BASE = "https://coasty.ai/v1" HEADERS = {"X-API-Key": os.environ "COASTY API KEY" } def screenshot - str: with open "screen.png", "rb" as f: return base64.b64encode f.read .decode 1. Open a session — it remembers the trajectory across steps session = requests.post f"{BASE}/sessions", headers=HEADERS, json={ "screen width": 1920, "screen height": 1080, }, timeout=60 .json session id = session "session id" 2. Drive the task one step at a time try: for in range 20 : safety cap res = requests.post f"{BASE}/sessions/{session id}/predict", headers=HEADERS, json={ "screenshot": screenshot , "instruction": "Book a meeting tomorrow at 3pm", }, timeout=60, .json for action in res "actions" : perform action your action executor if res "status" = "continue": break finally: 3. Always release the session to free your concurrency quota requests.delete f"{BASE}/sessions/{session id}", headers=HEADERS, timeout=30 finally block. Sessions count against your tier's concurrent-session limit. The 2-hour 7200-second idle TTL is reset on each predict and reset; deleting the session releases the slot immediately. Grounding Grounding answers a narrower question than predict: “where is this element?” Give it a screenshot and a description and it returns the exact x , y coordinate to target. It is faster and cheaper than a full prediction $0.03 instead of $0.05 , which makes it ideal when you already know what to do and only need a pixel to click. python import os, requests res = requests.post "https://coasty.ai/v1/ground", headers={"X-API-Key": os.environ "COASTY API KEY" }, json={ "screenshot": screenshot, base64 PNG see Predict "element": "the blue Submit button below the form", }, timeout=60, .json print res "x" , res "y" exact click coordinates The response is { x, y, usage, request id } . Coordinates are in the same pixel space as the screenshot you sent. Parse Parse converts a block of pyautogui code into the same structured action objects the model returns. It is deterministic, runs no model, and is free. Use it to migrate existing automation scripts onto Coasty's executor, or to normalise hand-written steps into the canonical action schema. python import os, requests res = requests.post "https://coasty.ai/v1/parse", headers={"X-API-Key": os.environ "COASTY API KEY" }, json={"code": "pyautogui.click 100, 200 \npyautogui.typewrite 'hello' "}, timeout=30, .json for action in res "actions" : print action "action type" , action "params" Action types Every action the model can return uses an action type from the table below, paired with a params object. Your executor switches on the type and applies the parameters. The terminal types — done and fail — set the response status and signal you to stop looping. Response format Predict and session-predict return the same shape. actions is the ordered list to execute; status tells you whether to keep going continue , stop successfully done , or stop because the task is impossible fail . usage reports tokens and the dollar cost of the call cost cents . Billed success responses also carry two headers you can read without parsing the body: X-Credits-Charged what this call cost and X-Credits-Remaining your wallet balance after it . In the body, the same numbers appear as usage.credits charged and usage.cost cents . On an sk-coasty-test- key both are always 0 . Every response success or error additionally carries an X-Coasty-Request-Id header that mirrors request id ; quote it when contacting support. On a failed billed request, X-Credits-Refunded is the authoritative confirmation that credits were returned, and X-Credits-Charged is then 0 . If settlement cannot be confirmed, the API returns 503 BILLING UNAVAILABLE without the refund header. Follow the error's retry with same idempotency key field rather than retrying by status alone. { "request id": "req 8f2c1e9a", "status": "continue", "reasoning": "The login form is visible. I'll click the email field, then type the address.", "actions": { "action type": "click", "params": { "x": 512, "y": 340 }, "description": "Click the email field" }, { "action type": "type text", "params": { "text": " email protected " }, "description": "Type the email address" } , "raw code": "pyautogui.click 512, 340 ", "pyautogui.typewrite ' email protected ' " , "usage": { "input tokens": 1523, "output tokens": 245, "credits charged": 5, "cost cents": 5 } } Errors Errors return a non-2xx status and a JSON envelope under an error key. The code is stable and safe to branch on; message is human-readable and may change. Every error also carries an error.request id mirrored in the X-Coasty-Request-Id response header , plus error.suggestion and error.docs url for self-service. A Link: <url ; rel="help" header mirrors docs url . Always log the request id: it is the fastest way for us to trace a failed call. Some codes attach machine-readable context to the body. A 402 INSUFFICIENT CREDITS reports required and balance ; a 403 reports required scope and current scopes ; a 422 VALIDATION ERROR lists the offending field path under error.details ; and a 409 state conflict carries current state with allowed from or required state . { "error": { "code": "INSUFFICIENT CREDITS", "message": "Your API wallet does not have enough funds to complete this request.", "type": "billing error", "suggestion": "Add funds in the dashboard, or use an sk-coasty-test- key while building test keys never bill .", "docs url": "https://coasty.ai/docs errors", "required": 5, "balance": 2, "request id": "req 8f2c1e9a", "retryable": false, "retry with same idempotency key": false } } 429 , 503 UPSTREAM UNAVAILABLE , and 504 UPSTREAM TIMEOUT as retryable: honor Retry-After on a 429, and use an Idempotency-Key with exponential backoff on the upstream codes only when the response's retryable and retry with same idempotency key fields permit it. A 500 model failure PREDICTION FAILED or GROUNDING FAILED is refunded only when X-Credits-Refunded is present; after a confirmed refund, use a new idempotency key for a new execution. Troubleshooting Five mistakes account for almost every first-week support ticket. Each maps to one status and one fix: Pricing Requests are billed in US dollars from your prepaid API wallet. The charge is taken before the model runs. On a conclusive server-side failure, the API submits a refund; treat it as complete only when X-Credits-Refunded is present. Ambiguous provider mutations may retain the debit until reconciliation. Internally each request unit is $0.01 the granularity behind every price below , but everything you pay and see is dollars. Every price on this page is exact; test keys sk-coasty-test- always bill $0.00 . Surcharges Four fixed surcharges can apply on top of a base price, all on the vision endpoints predict, session steps, ground . Each is an exact USD amount: Machines Machines bill for runtime only, metered per minute and rounded down: $0.05/hr for a running Linux machine, $0.09/hr for a running Windows machine, and $0.01/hr while stopped or suspended. The starting, stopping, and restarting transitions bill at the running rate; the creating, error, and terminated states bill nothing, and TTL auto-destroy is free. Snapshots are a one-time $0.01 each, and every per-call operation actions, batch, browser, terminal, files, screenshot, connection is free. Provisioning requires a $0.20 wallet minimum, which is a gate, not a charge. If the wallet empties mid-flight the machine is automatically stopped, never destroyed, and resumes after you top up. The live rate card is always at GET /v1/machines/pricing . Schedules Schedules have no per-fire fee: webhook fires are free limited to 60/min , and create, run-now, and webhook fires only require the same $0.20 wallet minimum as a gate. The execution itself is billed differently from everything else on this page: scheduled agent runtime is charged to your subscription credit balance at 10 credits per minute $0.10 of subscription value per minute, at 1 credit = $0.01 , not to this USD API wallet. Keep both balances funded if you rely on schedules. Cookbook Curated open-source repositories for building on the Coasty API. Clone a repo, mint a key, and ship. coasty-ai/computer-use-cookbookExamplesPythonNodecURLView on GitHub https://github.com/coasty-ai/computer-use-cookbook Computer Use Cookbook Runnable, copy-paste examples for every part of the Coasty API: predict, sessions, task runs, workflows, and driving machines. Start here. coasty-ai/open-coworkOpen sourceAgentsReference appView on GitHub https://github.com/coasty-ai/open-cowork Open Cowork The open-source Coasty project for computer-use agents that work alongside you. Build on it, fork it, or contribute.