openapi: 3.1.0 info: title: Coasty Public keys schedules API version: 1.0.0 summary: Computer Use Agents, scheduled automation, and managed VMs. description: "# Coasty Public API\n\nCoasty is a Computer Use Agent (CUA) platform: predict actions from screenshots,\nprovision managed VMs, and run scheduled automation against them.\n\n## Authentication\n\nAll endpoints (except `/v1/triggers/webhook/{webhook_id}` and health checks) require an API key.\nPass it as either:\n\n- `X-API-Key: sk-coasty-live-...` (or `sk-coasty-test-...` for sandbox)\n- `Authorization: Bearer sk-coasty-live-...`\n\nThe external webhook endpoint does not use an API key, but it is authenticated:\nsend the HMAC-SHA256 `Coasty-Signature` credential documented on that operation.\n\nTest-mode keys (`sk-coasty-test-*`) hit the same validation paths as live keys but\nreturn mock VMs / mock action results and never bill credits — ideal for CI.\n\n## Pricing & budgeting\n\nPer-call rates (subject to change — see `lib/pricing/tiers.ts METERED_RATES`):\n\n| Endpoint | Credits |\n|---|---|\n| `POST /v1/predict` | ~5 |\n| `POST /v1/sessions` | 10 |\n| `POST /v1/sessions/{id}/predict` | ~4 |\n| `POST /v1/ground` | ~3 |\n| `POST /v1/parse` | 0 (free) |\n\nLong-running CUA jobs orchestrated through the dashboard (not this API) bill at\n10 credits/minute with a 20-credit minimum. Subscription tiers (`free | starter |\nprofessional | enterprise`) gate feature availability (e.g. custom system prompts),\nschedule counts, and the maximum trajectory length.\n\n## Errors\n\nEvery error response uses the same envelope:\n\n```json\n{\n \"error\": {\n \"code\": \"INSUFFICIENT_CREDITS\",\n \"message\": \"Need 5, have 2.\",\n \"type\": \"billing_error\",\n \"request_id\": \"req_a1b2c3d4e5f6\",\n \"retryable\": false,\n \"retry_with_same_idempotency_key\": false\n }\n}\n```\n\nInclude the `request_id` in support requests.\n\n## Idempotency\n\nOperations marked `x-idempotency: reserve-and-replay` accept `Idempotency-Key:\n<≤128 chars of [A-Za-z0-9_-:]>`. Replays\nof the same key + identical body return the original response (with\n`X-Coasty-Idempotent-Replay: true`) for 24 h. Reusing the key with a different body\nis a 422 `IDEMPOTENCY_KEY_REUSED`.\nOperations marked `x-idempotency: webhook-payload-dedup` instead deduplicate the\nsame webhook id + identical raw body for 60 seconds; they do not accept an\nIdempotency-Key.\n\n## Clients & MCP\n\nUse the HTTP API directly from any language. Official TypeScript and Python SDKs\nare not currently published; generate a client from this OpenAPI document if needed.\n- MCP server: `npx -y @coasty/mcp` (see `x-mcp-server`)\n\n## Reference\n\nComplete (machine-readable) spec is hosted at `/.well-known/openapi.json` and\n`/openapi.json` (Stripe / Vercel conventions)." contact: name: Coasty Developer Support url: https://coasty.ai/support email: founders@coasty.ai license: name: MIT identifier: MIT termsOfService: https://coasty.ai/terms servers: - url: https://coasty.ai description: Production - url: https://coasty.ai description: Sandbox — use sk-coasty-test-* keys against the same host. No billing, mock VMs. security: - apiKey: [] - bearerAuth: [] tags: - name: schedules description: Cron and one-shot scheduled CUA jobs. paths: /v1/schedules: post: tags: - schedules operationId: createSchedule summary: Create a schedule description: 'Cron-based or one-shot (run_at) scheduled task. Schedule-count limits are tier- and deployment-configured; clients must handle the structured limit response rather than hardcoding plan values. BYOK: schedules store only the non-secret llm preference; at fire time the CURRENT stored key is used — if it was deleted, firings fail loudly with LLM_KEY_NOT_CONFIGURED instead of silently running on platform keys.' security: - apiKey: [] - bearerAuth: [] parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/XLLMProvider' - $ref: '#/components/parameters/XLLMApiKey' - $ref: '#/components/parameters/XLLMModel' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScheduleCreateRequest' responses: '200': description: Schedule created. content: application/json: schema: $ref: '#/components/schemas/ScheduleResponse' headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' X-Coasty-Key-Kind: $ref: '#/components/headers/KeyKind' X-Coasty-Test-Mode: $ref: '#/components/headers/TestMode' X-Coasty-Idempotent-Replay: $ref: '#/components/headers/IdempotentReplay' Idempotency-Status: $ref: '#/components/headers/IdempotencyStatus' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' x-auth-mode: api_key x-required-scope: schedules:write x-required-scopes: - schedules:write x-scope-policy: required x-billing-code: null x-offering: schedules x-feature-flag: PUBLIC_SCHEDULES_API_ENABLED x-idempotency: reserve-and-replay get: tags: - schedules operationId: listSchedules summary: List schedules security: - apiKey: [] - bearerAuth: [] parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 200 default: 50 responses: '200': description: Schedules. content: application/json: schema: $ref: '#/components/schemas/ListSchedulesResponse' headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' X-Coasty-Key-Kind: $ref: '#/components/headers/KeyKind' X-Coasty-Test-Mode: $ref: '#/components/headers/TestMode' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' x-auth-mode: api_key x-required-scope: schedules:read x-required-scopes: - schedules:read x-scope-policy: required x-billing-code: null x-offering: schedules x-feature-flag: PUBLIC_SCHEDULES_API_ENABLED x-idempotency: none /v1/schedules/health: get: tags: - schedules operationId: schedulesHealth summary: Schedules API health check security: [] responses: '200': description: OK. content: application/json: schema: $ref: '#/components/schemas/HealthResponse' x-auth-mode: public x-required-scope: null x-required-scopes: [] x-scope-policy: none x-billing-code: null x-offering: schedules x-feature-flag: null x-idempotency: none /v1/schedules/{schedule_id}: parameters: - $ref: '#/components/parameters/ScheduleId' get: tags: - schedules operationId: getSchedule summary: Get schedule details security: - apiKey: [] - bearerAuth: [] responses: '200': description: Schedule. content: application/json: schema: $ref: '#/components/schemas/ScheduleResponse' headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' X-Coasty-Key-Kind: $ref: '#/components/headers/KeyKind' X-Coasty-Test-Mode: $ref: '#/components/headers/TestMode' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' x-auth-mode: api_key x-required-scope: schedules:read x-required-scopes: - schedules:read x-scope-policy: required x-billing-code: null x-offering: schedules x-feature-flag: PUBLIC_SCHEDULES_API_ENABLED x-idempotency: none patch: tags: - schedules operationId: updateSchedule summary: Update a schedule security: - apiKey: [] - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ScheduleUpdateRequest' responses: '200': description: Updated. content: application/json: schema: $ref: '#/components/schemas/ScheduleResponse' headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' X-Coasty-Key-Kind: $ref: '#/components/headers/KeyKind' X-Coasty-Test-Mode: $ref: '#/components/headers/TestMode' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' x-auth-mode: api_key x-required-scope: schedules:write x-required-scopes: - schedules:write x-scope-policy: required x-billing-code: null x-offering: schedules x-feature-flag: PUBLIC_SCHEDULES_API_ENABLED x-idempotency: none delete: tags: - schedules operationId: deleteSchedule summary: Delete a schedule security: - apiKey: [] - bearerAuth: [] responses: '200': description: Deleted. content: application/json: schema: $ref: '#/components/schemas/DeleteScheduleResponse' headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' X-Coasty-Key-Kind: $ref: '#/components/headers/KeyKind' X-Coasty-Test-Mode: $ref: '#/components/headers/TestMode' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' x-auth-mode: api_key x-required-scope: schedules:write x-required-scopes: - schedules:write x-scope-policy: required x-billing-code: null x-offering: schedules x-feature-flag: PUBLIC_SCHEDULES_API_ENABLED x-idempotency: none /v1/schedules/{schedule_id}/pause: parameters: - $ref: '#/components/parameters/ScheduleId' post: tags: - schedules operationId: pauseSchedule summary: Pause a schedule security: - apiKey: [] - bearerAuth: [] responses: '200': description: Paused. content: application/json: schema: $ref: '#/components/schemas/ScheduleResponse' headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' X-Coasty-Key-Kind: $ref: '#/components/headers/KeyKind' X-Coasty-Test-Mode: $ref: '#/components/headers/TestMode' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' x-auth-mode: api_key x-required-scope: schedules:write x-required-scopes: - schedules:write x-scope-policy: required x-billing-code: null x-offering: schedules x-feature-flag: PUBLIC_SCHEDULES_API_ENABLED x-idempotency: none /v1/schedules/{schedule_id}/resume: parameters: - $ref: '#/components/parameters/ScheduleId' post: tags: - schedules operationId: resumeSchedule summary: Resume a paused schedule security: - apiKey: [] - bearerAuth: [] responses: '200': description: Resumed. content: application/json: schema: $ref: '#/components/schemas/ScheduleResponse' headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' X-Coasty-Key-Kind: $ref: '#/components/headers/KeyKind' X-Coasty-Test-Mode: $ref: '#/components/headers/TestMode' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' x-auth-mode: api_key x-required-scope: schedules:write x-required-scopes: - schedules:write x-scope-policy: required x-billing-code: null x-offering: schedules x-feature-flag: PUBLIC_SCHEDULES_API_ENABLED x-idempotency: none /v1/schedules/{schedule_id}/run: parameters: - $ref: '#/components/parameters/ScheduleId' post: tags: - schedules operationId: runScheduleNow summary: Trigger a schedule run immediately security: - apiKey: [] - bearerAuth: [] parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunScheduleRequest' responses: '200': description: Run queued. content: application/json: schema: $ref: '#/components/schemas/RunScheduleResponse' headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' X-Coasty-Key-Kind: $ref: '#/components/headers/KeyKind' X-Coasty-Test-Mode: $ref: '#/components/headers/TestMode' X-Coasty-Idempotent-Replay: $ref: '#/components/headers/IdempotentReplay' Idempotency-Status: $ref: '#/components/headers/IdempotencyStatus' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' x-auth-mode: api_key x-required-scope: schedules:write x-required-scopes: - schedules:write x-scope-policy: required x-billing-code: null x-offering: schedules x-feature-flag: PUBLIC_SCHEDULES_API_ENABLED x-idempotency: reserve-and-replay /v1/schedules/{schedule_id}/runs: parameters: - $ref: '#/components/parameters/ScheduleId' get: tags: - schedules operationId: listScheduleRuns summary: List historical runs of a schedule security: - apiKey: [] - bearerAuth: [] parameters: - name: cursor in: query required: false schema: type: string - name: status in: query required: false schema: type: string enum: - running - completed - failed - skipped - cancelled - insufficient_credits - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 200 default: 50 responses: '200': description: Runs. content: application/json: schema: $ref: '#/components/schemas/ListScheduleRunsResponse' headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' X-Coasty-Key-Kind: $ref: '#/components/headers/KeyKind' X-Coasty-Test-Mode: $ref: '#/components/headers/TestMode' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' x-auth-mode: api_key x-required-scope: schedules:read x-required-scopes: - schedules:read x-scope-policy: required x-billing-code: null x-offering: schedules x-feature-flag: PUBLIC_SCHEDULES_API_ENABLED x-idempotency: none /v1/schedules/{schedule_id}/runs/{run_id}: parameters: - $ref: '#/components/parameters/ScheduleId' - name: run_id in: path required: true schema: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z0-9_\-]+$ get: tags: - schedules operationId: getScheduleRun summary: Get a single run security: - apiKey: [] - bearerAuth: [] responses: '200': description: Run. content: application/json: schema: $ref: '#/components/schemas/ScheduleRunRecord' headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' X-Coasty-Key-Kind: $ref: '#/components/headers/KeyKind' X-Coasty-Test-Mode: $ref: '#/components/headers/TestMode' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' x-auth-mode: api_key x-required-scope: schedules:read x-required-scopes: - schedules:read x-scope-policy: required x-billing-code: null x-offering: schedules x-feature-flag: PUBLIC_SCHEDULES_API_ENABLED x-idempotency: none components: headers: CreditsCharged: description: Credits charged by this response (zero for sandbox keys and stored replays). schema: type: integer minimum: 0 RetryAfter: description: Seconds to wait before retrying. Present on retryable back-pressure and transient failures. schema: type: integer minimum: 0 IdempotencyStatus: description: Lifecycle status of the canonical idempotent attempt when applicable. schema: type: string enum: - processing - completed CoastyRequestId: description: Coasty correlation identifier for this request. schema: type: string IdempotentReplay: description: true when this is a stored response replay rather than a new execution. schema: type: boolean TestMode: description: true when the request executed against the sandbox namespace. schema: type: boolean KeyKind: description: Whether the authenticated key is live or test. schema: type: string enum: - live - test - legacy CreditsRefunded: description: Credits durably returned to the wallet after a failed billed operation. schema: type: integer minimum: 1 responses: RateLimited: description: Rate or concurrency limit exceeded. headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Refunded: $ref: '#/components/headers/CreditsRefunded' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: RATE_LIMIT_EXCEEDED message: An error occurred. See `code` for details. type: validation_error request_id: req_a1b2c3d4e5f6 retryable: false retry_with_same_idempotency_key: false BadRequest: description: Invalid request body or parameters. headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Refunded: $ref: '#/components/headers/CreditsRefunded' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: VALIDATION_ERROR message: An error occurred. See `code` for details. type: validation_error request_id: req_a1b2c3d4e5f6 retryable: false retry_with_same_idempotency_key: false GatewayTimeout: description: An upstream dependency timed out. headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Refunded: $ref: '#/components/headers/CreditsRefunded' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: UPSTREAM_TIMEOUT message: An error occurred. See `code` for details. type: validation_error request_id: req_a1b2c3d4e5f6 retryable: false retry_with_same_idempotency_key: false PayloadTooLarge: description: The request body exceeds the endpoint limit. headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Refunded: $ref: '#/components/headers/CreditsRefunded' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: PAYLOAD_TOO_LARGE message: An error occurred. See `code` for details. type: validation_error request_id: req_a1b2c3d4e5f6 retryable: false retry_with_same_idempotency_key: false NotFound: description: Resource not found in this key's namespace. headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Refunded: $ref: '#/components/headers/CreditsRefunded' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: NOT_FOUND message: An error occurred. See `code` for details. type: validation_error request_id: req_a1b2c3d4e5f6 retryable: false retry_with_same_idempotency_key: false ServiceUnavailable: description: A required service is temporarily unavailable. headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Refunded: $ref: '#/components/headers/CreditsRefunded' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: SERVICE_UNAVAILABLE message: An error occurred. See `code` for details. type: validation_error request_id: req_a1b2c3d4e5f6 retryable: false retry_with_same_idempotency_key: false BadGateway: description: An upstream dependency returned an invalid response. headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Refunded: $ref: '#/components/headers/CreditsRefunded' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: UPSTREAM_ERROR message: An error occurred. See `code` for details. type: validation_error request_id: req_a1b2c3d4e5f6 retryable: false retry_with_same_idempotency_key: false Forbidden: description: API key lacks the required scope or tier-feature is unavailable on the caller's plan. headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Refunded: $ref: '#/components/headers/CreditsRefunded' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: INSUFFICIENT_SCOPE message: An error occurred. See `code` for details. type: validation_error request_id: req_a1b2c3d4e5f6 retryable: false retry_with_same_idempotency_key: false UnprocessableEntity: description: The JSON shape is valid but one or more values violate the endpoint contract. headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Refunded: $ref: '#/components/headers/CreditsRefunded' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: VALIDATION_ERROR message: An error occurred. See `code` for details. type: validation_error request_id: req_a1b2c3d4e5f6 retryable: false retry_with_same_idempotency_key: false Conflict: description: The resource state conflicts with this operation. headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Refunded: $ref: '#/components/headers/CreditsRefunded' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: CONFLICT message: An error occurred. See `code` for details. type: validation_error request_id: req_a1b2c3d4e5f6 retryable: false retry_with_same_idempotency_key: false Unauthorized: description: 'Missing, invalid, or revoked API key. Pass `X-API-Key: sk-coasty-live-...` (or test).' headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Refunded: $ref: '#/components/headers/CreditsRefunded' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: INVALID_API_KEY message: An error occurred. See `code` for details. type: validation_error request_id: req_a1b2c3d4e5f6 retryable: false retry_with_same_idempotency_key: false PaymentRequired: description: Insufficient credits to perform the operation. Top up via /credits or upgrade subscription. headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Refunded: $ref: '#/components/headers/CreditsRefunded' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: INSUFFICIENT_CREDITS message: An error occurred. See `code` for details. type: validation_error request_id: req_a1b2c3d4e5f6 retryable: false retry_with_same_idempotency_key: false ServerError: description: Unexpected server error. Retry with exponential backoff. headers: X-Coasty-Request-Id: $ref: '#/components/headers/CoastyRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' X-Credits-Charged: $ref: '#/components/headers/CreditsCharged' X-Credits-Refunded: $ref: '#/components/headers/CreditsRefunded' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: code: INTERNAL_ERROR message: An error occurred. See `code` for details. type: validation_error request_id: req_a1b2c3d4e5f6 retryable: false retry_with_same_idempotency_key: false parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: 'Optional client-supplied key (≤128 chars, [A-Za-z0-9_-:]) for safe retries. ''Same request'' = a SHA-256 of the canonical (sorted-key) JSON body (session_id is folded in for /sessions/{id}/predict). Replays the original response for 24 h when the body hash matches (X-Coasty-Idempotent-Replay: true and X-Credits-Charged: 0). 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 the body differs. Collect a lost result via GET /v1/idempotency/{key}.' schema: type: string maxLength: 128 pattern: ^[A-Za-z0-9_\-:]+$ examples: uuid: value: 550e8400-e29b-41d4-a716-446655440000 XLLMProvider: name: X-LLM-Provider in: header required: false description: '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. Selecting a BYOK provider (here or via the body llm.provider) runs the ENTIRE harness on your own account with no silent fallback to Coasty''s platform LLM keys.' schema: type: string enum: - anthropic - openai XLLMModel: name: X-LLM-Model in: header required: false description: 'BYOK: model override for this request (equivalent to body llm.model). Defaults: claude-sonnet-4-6 (anthropic), gpt-4o (openai). Any model string your account can access; must be vision-capable.' schema: type: string minLength: 1 maxLength: 512 XLLMApiKey: name: X-LLM-Api-Key in: header required: false description: 'BYOK: your own provider API key, used for this request only. Takes precedence over the key stored via PUT /v1/llm/keys/{provider}. Never logged, never echoed in any response, webhook, or idempotency replay.' schema: type: string minLength: 16 maxLength: 512 ScheduleId: name: schedule_id in: path required: true description: Schedule UUID, or `sch_test_<8-32 lowercase hex>` for sandbox keys. schema: type: string pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|sch_test_[0-9a-f]{8,32})$ schemas: ScheduleResponse: type: object required: - id - name - machine_id - task_prompt - enabled - frequency - cron - timezone - request_id properties: id: type: string name: type: string machine_id: type: string task_prompt: type: string enabled: type: boolean frequency: type: string cron: type: string timezone: type: string next_run_at: type: - string - 'null' format: date-time last_run_at: type: - string - 'null' format: date-time run_count: type: integer default: 0 consecutive_failures: type: integer default: 0 paused_reason: type: - string - 'null' is_test: type: boolean default: false created_at: type: - string - 'null' format: date-time metadata: type: object additionalProperties: type: string request_id: type: string ApiError: type: object required: - error properties: error: type: object required: - code - message - type - retryable - retry_with_same_idempotency_key - request_id properties: code: type: string description: Stable machine-readable error code (e.g. INVALID_API_KEY, INSUFFICIENT_CREDITS). examples: - INVALID_API_KEY message: type: string description: Human-readable explanation. May include suggestions or examples. type: type: string enum: - auth_error - validation_error - rate_limit_error - billing_error - not_found_error - state_error - server_error - client_error request_id: type: string description: Server-assigned correlation ID. Include in support requests. examples: - req_a1b2c3d4e5f6 suggestion: type: string description: A concrete next step, auto-filled per code. LLM agents can act on it to self-recover. retryable: type: boolean description: 'true when retrying the same call may succeed (transient server failures + back-pressure: INTERNAL_ERROR, DB_UNAVAILABLE, SERVICE_UNAVAILABLE, UPSTREAM_*, PREDICTION_FAILED, *_FAILED, RATE_LIMITED, TOO_MANY_RUNS, IDEMPOTENCY_IN_FLIGHT, ...). false for deterministic client errors. A CUA BILLING_UNAVAILABLE caused by refund uncertainty is false unless the server confirmed a shared recovery checkpoint. Present on EVERY error envelope, including gateway/5xx/timeout paths.' retry_with_same_idempotency_key: type: boolean description: 'true only when the concrete response permits replay, the original operation is one of the exact 18 reserve-and-replay operations, and that original request already carried the key. Reuse that SAME key and identical body. A retryable error alone does not make an operation idempotent, and a key cannot be added retroactively. For CUA refund uncertainty this is true only after an exact shared checkpoint was confirmed; unkeyed or uncheckpointed responses are false and must not be retried automatically. A confirmed refunded failure sets this false even when retryable remains true: use a new key, because the old debit is compensated and wallet-guarded by IDEMPOTENCY_ALREADY_REFUNDED. false for deterministic errors.' retry_after: type: - integer - 'null' description: Seconds to wait before retrying (accompanies retryable:true back-pressure codes; mirrors the Retry-After header). examples: type: object additionalProperties: true description: 'Machine-readable limits for self-correction. On PAYLOAD_TOO_LARGE / INVALID_SCREENSHOT: { max_base64_bytes: 10485760, max_mb: 10, min_base64_chars: 100, formats: ["png","jpeg"] }.' HealthResponse: type: object required: - status properties: status: type: string enum: - ok api_version: type: string service: type: string RunScheduleRequest: type: object additionalProperties: false properties: task_prompt_override: type: - string - 'null' maxLength: 8000 triggered_context: type: - object - 'null' additionalProperties: true description: Free-form context injected into the agent's prompt. Max 1 MB serialized. ListScheduleRunsResponse: type: object required: - data - request_id properties: data: type: array items: $ref: '#/components/schemas/ScheduleRunRecord' next_cursor: type: - string - 'null' has_more: type: boolean default: false request_id: type: string ScheduleUpdateRequest: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 128 task_prompt: type: string minLength: 1 maxLength: 8000 frequency: type: string cron: type: string maxLength: 128 timezone: type: string maxLength: 64 time: type: string maxLength: 5 day_of_week: type: integer minimum: 0 maximum: 6 day_of_month: type: integer minimum: 1 maximum: 28 max_consecutive_failures: type: integer minimum: 1 maximum: 50 enabled: type: boolean metadata: type: object additionalProperties: type: string LlmConfig: type: object additionalProperties: false description: '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.' properties: provider: type: string enum: - managed - anthropic - openai default: managed description: Whose LLM account runs the harness. Anything else is 422 LLM_PROVIDER_UNSUPPORTED. model: type: - string - 'null' minLength: 1 maxLength: 512 description: 'Main worker model. Defaults: claude-sonnet-4-6 (anthropic), gpt-4o (openai). Any model string your account can access; must be vision-capable.' grounding_model: type: - string - 'null' minLength: 1 maxLength: 512 description: Override for pixel-coordinate grounding. Defaults to model. Grounding quality is tuned on the platform model; expect best results with the defaults. compaction_model: type: - string - 'null' minLength: 1 maxLength: 512 description: Override for trajectory compaction. Defaults to model. A cheaper model here is the classic cost tune. code_agent_model: type: - string - 'null' minLength: 1 maxLength: 512 description: Override for the code agent. Defaults to model. DeleteScheduleResponse: type: object required: - deleted - schedule_id - request_id properties: deleted: type: boolean schedule_id: type: string request_id: type: string ListSchedulesResponse: type: object required: - data - request_id properties: data: type: array items: $ref: '#/components/schemas/ScheduleResponse' has_more: type: boolean default: false request_id: type: string RunScheduleResponse: type: object required: - schedule_id - run_id - status - message - request_id properties: schedule_id: type: string run_id: type: string status: type: string enum: - running - queued - skipped - completed message: type: string request_id: type: string ScheduleRunRecord: type: object required: - id - schedule_id - status - trigger - executed_at properties: id: type: string schedule_id: type: string status: type: string enum: - queued - running - completed - failed - skipped - cancelled - insufficient_credits trigger: type: string enum: - cron - manual - triggered - webhook - email - run_at duration_seconds: type: - integer - 'null' credits_charged: type: - integer - 'null' error: type: - string - 'null' executed_at: type: string format: date-time ScheduleCreateRequest: type: object required: - name - machine_id - task_prompt additionalProperties: false properties: name: type: string minLength: 1 maxLength: 128 machine_id: type: string minLength: 1 maxLength: 64 task_prompt: type: string minLength: 1 maxLength: 8000 frequency: type: - string - 'null' enum: - every_15_minutes - every_30_minutes - hourly - every_6_hours - every_12_hours - daily - weekly - monthly - custom cron: type: - string - 'null' maxLength: 128 description: Required when frequency='custom'. 5- or 6-field cron expression. timezone: type: string maxLength: 64 default: UTC time: type: - string - 'null' maxLength: 5 description: HH:MM 24-hour. Used by daily/weekly/monthly presets. day_of_week: type: - integer - 'null' minimum: 0 maximum: 6 day_of_month: type: - integer - 'null' minimum: 1 maximum: 28 run_at: type: - string - 'null' format: date-time description: ISO 8601 UTC timestamp for a one-shot schedule. Mutually exclusive with frequency. max_consecutive_failures: type: integer minimum: 1 maximum: 50 default: 5 metadata: type: object additionalProperties: type: string llm: $ref: '#/components/schemas/LlmConfig' securitySchemes: apiKey: type: apiKey name: X-API-Key in: header description: 'Coasty API key. Live: `sk-coasty-live-...`. Sandbox: `sk-coasty-test-...`.' bearerAuth: type: http scheme: bearer bearerFormat: Coasty API key (sk-coasty-{live,test}-...) description: Equivalent to X-API-Key. Use whichever your client supports. webhookHmac: type: apiKey name: Coasty-Signature in: header description: 'HMAC-SHA256 credential for external schedule webhooks: t=,v1=.' webhookHmacLegacy: type: apiKey name: X-Coasty-Signature in: header description: Compatibility alias for the Coasty-Signature HMAC credential. x-logo: url: https://coasty.ai/logo_dark.svg altText: Coasty backgroundColor: '#FFFFFF' x-mcp-server: name: '@coasty/mcp' install: npx -y @coasty/mcp description: Coasty's Model Context Protocol server. Wires the /v1/* surface plus pricing into any MCP-compatible client (Claude Desktop, Cursor, etc.). homepage: https://coasty.ai/mcp