Stateless action prediction

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.