v1
latestOpenAPI 3.1.0MIT2026-08-0481194343.8 KBSubmit a task and let Coasty handle everything
Scope: runs:write. The high-level submit-and-forget API. Coasty asynchronously provisions an ephemeral managed desktop, runs the screenshot→act→observe→verify loop, refuses human takeover, and never enters awaiting_human. A handoff request is suppressed and the agent is told to carry on with a fresh screen: there is no retry budget and no challenge-specific terminal error, so a verification screen, CAPTCHA or email confirmation is treated as part of the task. max_steps, deadline_seconds and the credit balance are the only hard stops. Credentials, inboxes and codes supplied in the task are the agent's to use — fetching a confirmation code from an inbox you provided is ordinary work, not an escalation. Coasty does not provide or integrate third-party CAPTCHA solvers, stealth/proxy evasion, access-control bypasses, or fabricated authority, and the agent is explicitly prohibited from using them. Per-step model-input frames are retained for every run and readable at GET /v1/runs/{run_id}/screenshots, and the assembled step-by-step trajectory (reasoning, actions, outcomes) at GET /v1/runs/{run_id}/log — which is where you read a finished run's full trajectory or final answer, since result.summary is only the last 2000 characters. It records a terminal succeeded/failed/timed_out outcome, starts idempotent machine cleanup, and sends the optional HMAC-signed webhook. Webhook delivery can precede completed provider termination, so inspect machine.cleanup_status (terminating, retrying, or terminated). The admission response is immediate and uses the normal agent.run resource, so GET /v1/runs/{id}, cancellation, and SSE remain available but are not required when a webhook is supplied. Idempotency-Key deduplicates task admission and machine provisioning. Managed CUA steps and machine runtime are billed normally; BYOK makes LLM execution zero Coasty platform credits but does not make machine runtime free.
Headers
Optional client-supplied key (≤128 chars, [A-Za-z0-9_-:]) for safe retries. Keys are global within one concrete API-key credential plus live/test mode; never reuse one on another endpoint. 'Same request' = a SHA-256 of an explicit operation discriminator plus the canonical (sorted-key) JSON body (session_id is folded in for /sessions/{id}/predict). LLM-capable operations also bind the non-secret effective provider, role models, and one-way provider-key fingerprint; plaintext provider keys never enter the hash or replay record. Replays the response for 24 h when operation, body, and effective execution identity match (X-Coasty-Idempotent-Replay: true and X-Credits-Charged: 0). Action screenshot pixels are response-only and deliberately omitted from replay storage; a replay retains frame_id but returns screenshot=null and observation_available=false. Inference replays also set body usage.credits_charged=0 and usage.billed=false; machine-snapshot bodies retain the original gross charge for auditability. A retry while the original is still running waits up to ~25 s then returns the result, otherwise 409 IDEMPOTENCY_IN_FLIGHT (retry with the SAME key). Returns 422 IDEMPOTENCY_KEY_REUSED if any bound input differs. Rotating the API key starts a new replay namespace. Collect a lost result via GET /v1/idempotency/{key} using the original credential.
BYOK: which provider the X-LLM-Api-Key belongs to (anthropic | openai). Required whenever X-LLM-Api-Key is sent — a key without a provider is a 422 LLM_PROVIDER_UNSUPPORTED. With a live Coasty key, selecting BYOK runs the entire harness on your provider account with no platform fallback and zero Coasty inference credits. Under test auth, predict, ground, and session create require an explicit per-request X-LLM-Api-Key; a body provider without that header fails with 422 LLM_KEY_NOT_CONFIGURED because test auth never reads a stored live provider key. Session create fixes the explicit key for inherited predicts without inference. Managed-mode Tasks, Workflows, and schedules remain deterministic sandbox executions; BYOK intent on them fails before execution with 422 LLM_PROVIDER_UNSUPPORTED. They never decrypt or require a stored provider key and make no provider call.
BYOK provider credential supplied on this request. Lifecycle depends on the operation: predict/ground use it for that call; session create retains a fixed owner-process copy for inherited predicts; Run/Workflow creation snapshots it encrypted until terminal state; schedule create uses it only to validate the current stored key and persists no credential. It requires an effective anthropic/openai provider; combining it with body llm.provider='managed' is 422. Under live auth, immediate operations prefer this header over a stored key. Schedules fire without headers, so the header key must match the stored key and each fire resolves the current stored key. Never logged or echoed. With a test Coasty key, explicit BYOK is provider-direct only for the direct CUA flow: POST /v1/predict, POST /v1/ground, POST /v1/sessions, and POST /v1/sessions/{id}/predict. Predict, ground, and session create require this explicit per-request header plus X-LLM-Provider; body llm.provider without it returns 422 LLM_KEY_NOT_CONFIGURED (Stored provider keys are unavailable for test API keys. Send X-LLM-Api-Key explicitly for direct BYOK.) and test auth never reads or uses a stored live provider key. Session create fixes the explicit key for inherited session predicts but makes no inference call; predict, ground, and session predict can call and bill Anthropic/OpenAI. Managed-mode test Tasks, Workflows, and schedules remain deterministic sandbox. Supplying BYOK headers or provider metadata to them returns 422 LLM_PROVIDER_UNSUPPORTED (BYOK is unavailable for synthetic test runs, workflows, and schedules. Use managed mode or a live Coasty API key.) before execution. They never decrypt or require a stored provider key and do not call or bill Anthropic/OpenAI. Keep provider secrets out of sandbox and CI requests; use a live Coasty key for real asynchronous execution.
BYOK model selection for this operation (equivalent to body llm.model). Sessions retain it for inherited predicts, Runs/Workflows snapshot it, and schedules persist the non-secret selection for later fires. Defaults: claude-sonnet-5 (anthropic), gpt-5.6-sol (openai). The same 1-256-character model-id syntax applies; invalid ids return 422 LLM_MODEL_INVALID. The provider can still reject an unknown or inaccessible model; it must be vision-capable.
Request body
Response
Task accepted (agent.run status "queued").