> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryblend.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a response

> Starts a published workflow run.

Set `stream: true` for an SSE stream that ends with `data: [DONE]`. Leave it `false` for `202 Accepted` with a `run_id` you can poll via `GET /api/v1/runs/{runId}` or resume via `GET /api/v1/runs/{runId}/stream`.



## OpenAPI

````yaml /openapi.json post /api/v1/responses
openapi: 3.0.3
info:
  title: Blend AI Workflow API
  version: 1.0.0
  description: Run published Blend AI workflows over HTTP.
  contact:
    name: Blend AI Support
    url: https://tryblend.ai
servers:
  - url: https://tryblend.ai
    description: Production
security:
  - BearerAuth: []
paths:
  /api/v1/responses:
    post:
      summary: Start a response
      description: >-
        Starts a published workflow run.


        Set `stream: true` for an SSE stream that ends with `data: [DONE]`.
        Leave it `false` for `202 Accepted` with a `run_id` you can poll via
        `GET /api/v1/runs/{runId}` or resume via `GET
        /api/v1/runs/{runId}/stream`.
      operationId: startResponse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
      responses:
        '200':
          description: 'Server-Sent Events stream (when `stream: true`).'
          content:
            text/event-stream:
              schema:
                type: string
                description: Newline-delimited SSE frames.
        '202':
          description: >-
            Run accepted (when `stream: false`). Poll `GET
            /api/v1/runs/{runId}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncStartResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    ResponsesRequest:
      type: object
      properties:
        workflowId:
          type: string
          description: Published workflow ID or owner-scoped API slug.
          example: pub_abc123
        versionId:
          type: string
          description: >-
            Pin to a specific published version. Defaults to the latest
            published version.
          example: ver_xyz789
        stream:
          type: boolean
          default: false
          description: >-
            When `true`, the response is an SSE stream. When `false`, returns
            `202` with a `run_id` for polling.
        inputs:
          type: object
          description: >-
            Workflow inputs keyed by the normalized label of each User Input
            node. Text inputs are strings; file/image/video inputs are URLs or
            uploaded file references. Internal Batch rows are not public API
            inputs unless exposed through User Input nodes.
          additionalProperties: true
          example:
            prompt: A cat on the moon
            reference_image: https://example.com/ref.png
      required:
        - workflowId
    AsyncStartResponse:
      type: object
      required:
        - run_id
        - status
        - created_at
      properties:
        run_id:
          type: string
          description: Unique run identifier.
          example: run_xyz789
        status:
          type: string
          enum:
            - pending
          description: Initial run status.
        published_workflow_id:
          type: string
          nullable: true
          example: pub_abc123
        published_workflow_version_id:
          type: string
          nullable: true
          example: ver_xyz789
        created_at:
          type: string
          format: date-time
          example: '2026-04-18T12:00:00.000Z'
    ErrorEnvelope:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              example: Invalid or missing API key.
            type:
              type: string
              enum:
                - authentication_error
                - insufficient_credits
                - rate_limit_error
                - invalid_request_error
                - not_found_error
                - server_error
            code:
              type: string
              description: >-
                Machine-readable sub-code. Examples: `invalid_api_key`,
                `rate_limit_exceeded`, `insufficient_credits`, `not_found`,
                `published_workflow_not_found`,
                `published_workflow_version_not_found`, `invalid_input_fields`,
                `workflow_graph_corrupt`.
  responses:
    BadRequest:
      description: >-
        Invalid request body, missing `workflowId`, invalid inputs, or the
        workflow failed pre-run validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InsufficientCredits:
      description: Not enough credits to run this workflow.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: >-
        Run, published workflow, or version not found — or not owned by the
        caller.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: >-
        Per-API-key rate limit exceeded. Inspect `X-RateLimit-*` and
        `Retry-After` headers.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    ServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: bai_...
      description: >-
        API key issued from the Blend AI dashboard. Prefix: `bai_`. Send as
        `Authorization: Bearer bai_...`.

````