--- title: "Submit a task and let Coasty handle everything" method: POST path: "/v1/tasks" tags: ["runs"] --- # Submit a task and let Coasty handle everything `POST /v1/tasks` 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 - `Idempotency-Key` string - `X-LLM-Provider` 'anthropic' | 'openai' - `X-LLM-Api-Key` string - `X-LLM-Model` string ## Request body - AutonomousTaskRequest - `task` string, required - `cua_version` 'v1' | 'v3' | 'v4' | 'v5' - `instructions` string, nullable - `system_prompt` string, nullable - `model` string, nullable - `max_steps` integer - `action_policy` ActionPolicy — Opt-in, fail-closed post-model action enforcement. The complete normalized batch is checked atomically before actions are returned or dispatched. allowed_actions and blocked_actions cannot overlap. Prediction, Session, and Parse surfaces use prediction action names such as type_text; direct Machine routes use command names such as type. Task, Workflow, and Schedule policies are create-time controls inherited across execution and recovery. - `allowed_actions` string[], nullable — Optional action allowlist. Values are trimmed and lowercased before validation; duplicates after normalization are rejected. Terminal done/fail/awaiting_human signals remain allowed. - `blocked_actions` string[] — Action denylist. Values are trimmed and lowercased before validation; duplicates after normalization are rejected. - `blocked_keys` string[] — Keys forbidden in key_press, key_combo, and modifier-bearing actions. Values are trimmed and lowercased; duplicates after normalization are rejected; esc aliases escape. - `block_window_close` boolean — Block explicit close commands and common Alt+F4, Ctrl/Cmd+W, and Cmd+Q shortcuts. - `max_actions` integer, nullable — Maximum number of actions admitted in one prediction/session step, parsed action batch, or direct Machine batch. - `coordinate_bounds` CoordinateBounds — Inclusive coordinate rectangle in the request screenshot's pixel space. - `min_x` integer - `min_y` integer - `max_x` integer, required - `max_y` integer, required - `deadline_seconds` integer, nullable - `webhook_url` string, nullable - `metadata` object, nullable - `llm` LlmConfig — Opt-in BYOK model selection. provider 'managed' (or omitting llm) keeps the platform default. There is deliberately no api_key field (422 if attempted): keys ride the X-LLM-Api-Key header or the encrypted /v1/llm/keys store only. Once BYOK is requested there is NO silent fallback to Coasty's platform LLM keys. - `provider` 'managed' | 'anthropic' | 'openai' — Whose LLM account runs the harness. Anything else is 422 LLM_PROVIDER_UNSUPPORTED. - `model` string, nullable — Main worker model. Defaults: claude-sonnet-5 (anthropic), gpt-5.6-sol (openai). Model ids are 1-256 characters, begin with a letter or number, and then use only letters, numbers, dot, underscore, colon, slash, plus, at-sign, or hyphen; invalid ids return 422 LLM_MODEL_INVALID. The selected provider can still reject an unknown or inaccessible model. It must be vision-capable. - `grounding_model` string, nullable — Override for pixel-coordinate grounding. Defaults to model. Grounding quality is tuned on the platform model; expect best results with the defaults. - `compaction_model` string, nullable — Override for trajectory compaction. Defaults to model. A cheaper model here is the classic cost tune. - `code_agent_model` string, nullable — Override for the code agent. Defaults to model. - `machine` AutonomousMachineRequest — Optional workload preferences. Coasty creates the machine, assigns a fail-safe TTL, and destroys it after any terminal outcome. Leave `provider` unset to let Coasty choose the backend, or pin one. - `provider` 'auto' | 'aws' | 'daytona' | 'azure' — Which backend runs this task's machine. 'auto' (default) lets Coasty choose: a desktop or Windows task goes to Daytona, falling back to AWS when Daytona is disabled; a headless task goes to Azure. Pin 'aws' or 'daytona' to force one. The choice is part of the run's idempotency identity, so a replay lands on the same backend rather than silently migrating. - `os_type` 'linux' | 'windows' - `desktop_enabled` boolean - `cpu_cores` integer - `memory_gb` integer - `storage_gb` integer - `restore_from_snapshot` boolean - `proxy` ProxyRequest — Route a machine's outbound traffic through a proxy. 'managed' uses Coasty's residential upstream and takes no other fields; 'custom' requires host and port. Omit the object entirely for no proxy. - `mode` 'none' | 'managed' | 'custom' - `session` 'sticky' | 'rotating', nullable — Managed mode only. 'sticky' (default) holds one exit IP for the machine's lifetime. - `scheme` 'http' | 'https' | 'socks5', nullable — Custom mode only. How to reach YOUR PROXY, not what it can carry: an http proxy serves HTTPS sites fine through CONNECT. Use https only when the proxy itself terminates TLS. Defaults to http. - `host` string, nullable — Custom mode only. Must be a public address; loopback, link-local and private ranges are refused. - `port` integer, nullable - `username` string, nullable - `password` string, nullable — Write-only. Encrypted at rest and never returned by any endpoint. ## Response `200` Task accepted (agent.run status "queued"). - RunResponse - `id` string, required - `object` 'agent.run', required - `status` 'queued' | 'running' | 'awaiting_human' | 'succeeded' | 'failed' | 'cancelled' | 'timed_out', required - `machine_id` string, nullable - `machine` object, nullable - `mode` 'automatic' - `status` 'provisioning' | 'starting' | 'reconciling' | 'ready' | 'terminated' | 'cleanup_failed' — Lifecycle of the ephemeral machine Coasty created for this run. `starting` means the provider handle and billing record are durable but the desktop may still be booting; execution readiness is verified separately before the agent is allowed to start. `reconciling` means a provisioning outcome is being recovered from the provider journal, and the run keeps its lease while that resolves. `cleanup_failed` means the run reached a terminal outcome but teardown did not confirm. - `id` string, nullable - `cleanup` 'always' - `cleanup_status` 'pending' | 'terminating' | 'retrying' | 'terminated' - `error` object - `task` string - `cua_version` string - `instructions` string, nullable - `max_steps` integer - `deadline_seconds` integer — EFFECTIVE wall-clock budget after the server applied its ceiling. Echoed back so a clamp is never silent: request 86400 against a lower server ceiling and you see the value the run is actually held to, instead of discovering it as a surprise DEADLINE_EXCEEDED. - `awaiting_human_timeout_seconds` integer — EFFECTIVE awaiting-human timeout after the server applied its ceiling, echoed back for the same reason as deadline_seconds. - `on_awaiting_human` string - `steps_completed` integer - `credits_charged` integer - `cost_cents` integer - `result` object, nullable — Terminal outcome envelope: `passed` (boolean), `status`, `summary`, `usage`, and `verdict` only when a verifier pass ran. `summary` is the LAST 2000 characters of the trajectory, so it carries the agent's final answer; it is not the full trajectory and there is no `output` field. To read a complete trajectory, or a final answer you intend to parse, use GET /v1/runs/{run_id}/log. - `error` object, nullable - `awaiting_human_reason` string, nullable - `metadata` object, nullable - `llm` RunLlmInfo — Credential-free BYOK attribution returned by agent runs and workflow runs. Only these allowlisted fields are public. - `provider` 'anthropic' | 'openai', required - `model` string, required - `key_fingerprint` string, required - `key_source` 'header' | 'stored', required - `key_scrubbed` boolean, required - `webhook_url` string, nullable — Lifecycle callback destination. Agent Run terminal callbacks are transactionally queued in a durable outbox and delivered at least once, with at most 3 durably recorded delivery attempts. A crash after HTTP send but before durable acknowledgement can add duplicate physical sends. Stable Coasty-Delivery equals body id and logical delivered_at survives retries; receivers must deduplicate it. The non-terminal awaiting-human callback is best-effort in-process, can be missed on a worker failure, and uses (run.id, event, run.awaiting_human_since) for deduplication. GET the run for authoritative state. - `webhook_secret` string, nullable — Returned by create and its exact bounded Idempotency-Key replay; null on get/list. The pinned per-run secret is encrypted at rest through delivery/replay recovery and later scrubbed. Verify raw-body deliveries with HMAC-SHA256 before accepting the Coasty-Delivery deduplication key. - `created_at` string, nullable - `started_at` string, nullable - `awaiting_human_since` string, nullable - `finished_at` string, nullable - `request_id` string, nullable ## Other responses - `400` — Invalid request body or parameters. - `401` — Missing, invalid, or revoked API key. Pass `X-API-Key: sk-coasty-live-...` (or test). - `402` — Insufficient balance for this operation. Direct metered API calls and managed-machine runtime use the prepaid Developer API wallet; scheduled execution is the documented consumer subscription-credit exception. Follow the operation's billing fields and top up the matching balance in the dashboard. - `403` — API key lacks the required scope or tier-feature is unavailable on the caller's plan. - `404` — Resource not found in this key's namespace. - `409` — The resource state conflicts with this operation. - `413` — The request body exceeds the endpoint limit. - `422` — The JSON shape is valid but one or more values violate the endpoint contract. - `429` — Rate or concurrency limit exceeded. - `500` — Unexpected server error. Retry with exponential backoff. - `502` — An upstream dependency returned an invalid response. - `503` — A required service is temporarily unavailable. - `504` — An upstream dependency timed out. --- [API](https://skmtc.net/coasty/apis/coasty-public-api.md) · [All operations](https://skmtc.net/coasty/apis/coasty-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/coasty/coasty-public-api/revisions/f50d93b0d8a1/schema)