Coasty workflows API

openapi: 3.1.0
info:
  title: Coasty Public keys workflows 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: workflows
  description: Versioned, branching multi-step automations (DSL) and their runs.
paths:
  /v1/workflows:
    post:
      tags:
      - workflows
      operationId: createWorkflow
      summary: Create a workflow
      description: 'Scope: `workflows:write`. Free (definition only). Creates a versioned workflow from a DSL `definition`.'
      security:
      - apiKey: []
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowCreateRequest'
      responses:
        '200':
          description: The created workflow.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
          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'
        '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: workflows:write
      x-required-scopes:
      - workflows:write
      x-scope-policy: required
      x-billing-code: null
      x-offering: workflows
      x-feature-flag: WORKFLOWS_API_ENABLED
      x-idempotency: reserve-and-replay
    get:
      tags:
      - workflows
      operationId: listWorkflows
      summary: List workflows
      description: 'Scope: `workflows:read`. Free. `limit` 1-200 (default 20).'
      security:
      - apiKey: []
      - bearerAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 20
      responses:
        '200':
          description: A list of workflows.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkflowsResponse'
          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: workflows:read
      x-required-scopes:
      - workflows:read
      x-scope-policy: required
      x-billing-code: null
      x-offering: workflows
      x-feature-flag: WORKFLOWS_API_ENABLED
      x-idempotency: none
  /v1/workflows/runs:
    post:
      tags:
      - workflows
      operationId: startAdhocWorkflowRun
      summary: Start an ad-hoc workflow run
      description: 'Scope: `workflows:write`. Runs an inline `definition` without saving it. Each `task` step bills at the /v1/predict rate under the optional `budget_cents` cap; other step types are free. Test keys never bill. `webhook_secret` is returned ONCE.'
      security:
      - apiKey: []
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartWorkflowRunRequest'
      responses:
        '200':
          description: The started workflow run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunResponse'
          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: workflows:write
      x-required-scopes:
      - workflows:write
      x-scope-policy: required
      x-billing-code: run_step
      x-offering: workflows
      x-feature-flag: WORKFLOWS_API_ENABLED
      x-idempotency: reserve-and-replay
    get:
      tags:
      - workflows
      operationId: listWorkflowRuns
      summary: List workflow runs
      description: 'Scope: `workflows:read`. Free. Optional `workflow_id` filter and `limit` (1-200, default 20).'
      security:
      - apiKey: []
      - bearerAuth: []
      parameters:
      - name: workflow_id
        in: query
        required: false
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 20
      responses:
        '200':
          description: A list of workflow runs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkflowRunsResponse'
          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: workflows:read
      x-required-scopes:
      - workflows:read
      x-scope-policy: required
      x-billing-code: null
      x-offering: workflows
      x-feature-flag: WORKFLOWS_API_ENABLED
      x-idempotency: none
  /v1/workflows/runs/{run_id}:
    parameters:
    - $ref: '#/components/parameters/RunId'
    get:
      tags:
      - workflows
      operationId: getWorkflowRun
      summary: Get a workflow run
      description: 'Scope: `workflows:read`. Free.'
      security:
      - apiKey: []
      - bearerAuth: []
      responses:
        '200':
          description: The workflow run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunResponse'
          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: workflows:read
      x-required-scopes:
      - workflows:read
      x-scope-policy: required
      x-billing-code: null
      x-offering: workflows
      x-feature-flag: WORKFLOWS_API_ENABLED
      x-idempotency: none
  /v1/workflows/runs/{run_id}/events:
    parameters:
    - $ref: '#/components/parameters/RunId'
    get:
      tags:
      - workflows
      operationId: streamWorkflowRunEvents
      summary: Stream workflow run events (SSE)
      description: 'Scope: `workflows:read`. Free. Durable SSE stream; resume with `Last-Event-ID` or `?after=<seq>`. The edge may rotate a connection after 300 seconds, so reconnect with the last sequence until the terminal event arrives.'
      security:
      - apiKey: []
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/LastEventId'
      - name: after
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: SSE stream (text/event-stream).
          content:
            text/event-stream:
              schema:
                type: string
              description: A Server-Sent Events byte stream. Each frame carries an event name/id and JSON in its data field; reconnect with Last-Event-ID.
          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: workflows:read
      x-required-scopes:
      - workflows:read
      x-scope-policy: required
      x-billing-code: null
      x-offering: workflows
      x-feature-flag: WORKFLOWS_API_ENABLED
      x-idempotency: none
  /v1/workflows/runs/{run_id}/cancel:
    parameters:
    - $ref: '#/components/parameters/RunId'
    post:
      tags:
      - workflows
      operationId: cancelWorkflowRun
      summary: Cancel a workflow run
      description: 'Scope: `workflows:write`. Free.'
      security:
      - apiKey: []
      - bearerAuth: []
      responses:
        '200':
          description: The cancelled workflow run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunResponse'
          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: workflows:write
      x-required-scopes:
      - workflows:write
      x-scope-policy: required
      x-billing-code: null
      x-offering: workflows
      x-feature-flag: WORKFLOWS_API_ENABLED
      x-idempotency: none
  /v1/workflows/runs/{run_id}/resume:
    parameters:
    - $ref: '#/components/parameters/RunId'
    post:
      tags:
      - workflows
      operationId: resumeWorkflowRun
      summary: Approve or reject a paused workflow run
      description: 'Scope: `workflows:write`. Free. Approves (continues) or rejects (fails) a run paused on a `human_approval` step.'
      security:
      - apiKey: []
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeWorkflowRunRequest'
      responses:
        '200':
          description: The resumed workflow run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunResponse'
          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: workflows:write
      x-required-scopes:
      - workflows:write
      x-scope-policy: required
      x-billing-code: null
      x-offering: workflows
      x-feature-flag: WORKFLOWS_API_ENABLED
      x-idempotency: none
  /v1/workflows/{workflow_id}:
    parameters:
    - $ref: '#/components/parameters/WorkflowId'
    get:
      tags:
      - workflows
      operationId: getWorkflow
      summary: Get a workflow
      description: 'Scope: `workflows:read`. Free.'
      security:
      - apiKey: []
      - bearerAuth: []
      responses:
        '200':
          description: The workflow.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
          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: workflows:read
      x-required-scopes:
      - workflows:read
      x-scope-policy: required
      x-billing-code: null
      x-offering: workflows
      x-feature-flag: WORKFLOWS_API_ENABLED
      x-idempotency: none
    put:
      tags:
      - workflows
      operationId: updateWorkflow
      summary: Update a workflow
      description: 'Scope: `workflows:write`. Free. Bumps the workflow `version`.'
      security:
      - apiKey: []
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowUpdateRequest'
      responses:
        '200':
          description: The updated workflow.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
          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: workflows:write
      x-required-scopes:
      - workflows:write
      x-scope-policy: required
      x-billing-code: null
      x-offering: workflows
      x-feature-flag: WORKFLOWS_API_ENABLED
      x-idempotency: none
    delete:
      tags:
      - workflows
      operationId: deleteWorkflow
      summary: Archive a workflow
      description: 'Scope: `workflows:write`. Free. Archives the workflow.'
      security:
      - apiKey: []
      - bearerAuth: []
      responses:
        '200':
          description: Deletion acknowledged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowDeleteResponse'
          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: workflows:write
      x-required-scopes:
      - workflows:write
      x-scope-policy: required
      x-billing-code: null
      x-offering: workflows
      x-feature-flag: WORKFLOWS_API_ENABLED
      x-idempotency: none
  /v1/workflows/{workflow_id}/runs:
    parameters:
    - $ref: '#/components/parameters/WorkflowId'
    post:
      tags:
      - workflows
      operationId: startWorkflowRun
      summary: Start a run of a saved workflow
      description: 'Scope: `workflows:write`. Runs the saved workflow. Each `task` step bills at the /v1/predict rate under the optional `budget_cents` cap; other steps are free. Test keys never bill. `webhook_secret` is returned ONCE. BYOK: opt in via the body `llm` block or the X-LLM-* headers to run every task step''s LLM calls on YOUR provider key (no silent fallback).'
      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/StartWorkflowRunRequest'
      responses:
        '200':
          description: The started workflow run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunResponse'
          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: workflows:write
      x-required-scopes:
      - workflows:write
      x-scope-policy: required
      x-billing-code: run_step
      x-offering: workflows
      x-feature-flag: WORKFLOWS_API_ENABLED
      x-idempotency: reserve-and-replay
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/Coast

# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coasty/refs/heads/main/openapi/coasty-workflows-api-openapi.yml