> ## 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.

# Overview

> Quick tour of the Blend AI Workflow API.

The Blend AI Workflow API runs published workflows from code. It is a small surface — three endpoints cover every use case.

## Base URL

```
https://tryblend.ai
```

All requests are HTTPS. CORS is permissive (`*`) so you can call the API from any origin, including browsers.

## Endpoints

<CardGroup cols={1}>
  <Card title="POST /api/v1/responses" icon="play" href="/endpoint/start-a-response">
    Start a workflow run. Stream results over SSE, or get a `run_id` back and poll asynchronously.
  </Card>

  <Card title="GET /api/v1/runs/{runId}" icon="magnifying-glass" href="/endpoint/get-a-run">
    Fetch the status and output of a run. Safe to poll.
  </Card>

  <Card title="GET /api/v1/runs/{runId}/stream" icon="bolt" href="/endpoint/stream-a-run">
    Reconnect to an in-flight run's SSE stream, or attach to a fire-and-forget run.
  </Card>
</CardGroup>

## Two execution modes

Every workflow run operates in one of two modes, controlled by the `stream` field on `POST /responses`:

| Mode          | `stream`          | Response                       | Good for                              |
| ------------- | ----------------- | ------------------------------ | ------------------------------------- |
| **Streaming** | `true`            | SSE stream, ends with `[DONE]` | Interactive UIs, realtime progress    |
| **Async**     | `false` (default) | `202` with `run_id`            | Background jobs, serverless, webhooks |

Async mode is the common choice for server-to-server integration. Streaming mode is what you want when a user is watching progress in real time.

## Request shape

Every call to `/responses` follows the same shape:

```json theme={null}
{
    "workflowId": "pub_abc123",   // published workflow ID or API slug
    "stream": true,                // or false for async
    "inputs": {                    // workflow inputs (optional)
        "prompt": "A cat on the moon"
    }
}
```

Keys in `inputs` are the **normalized labels** of the User Input nodes in your workflow — "Reference Image" becomes `reference_image`, "Prompt" becomes `prompt`.

Only [User Input](/workflow/nodes/input) nodes become API inputs. Ordinary node fields, Batch rows, and internal tool/model settings stay inside the workflow unless you expose them with a User Input.

## Response shape

Async mode returns:

```json theme={null}
{
    "run_id": "run_xyz789",
    "status": "pending",
    "published_workflow_id": "pub_abc123",
    "published_workflow_version_id": "ver_xyz789",
    "created_at": "2026-04-18T12:00:00.000Z"
}
```

Poll `GET /runs/{run_id}` until `status` is `completed`, then read the `output` object. Each key corresponds to a User Result node in your workflow. Each value is an array of output items, and each item contains typed parts — see [Output Parts](/parts) for the full shape.

## Explore the reference

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API keys, rate limits, and headers.
  </Card>

  <Card title="Streaming" icon="bolt" href="/api-reference/streaming">
    SSE event types and how to handle them.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api-reference/errors">
    Status codes, error types, and sub-codes.
  </Card>

  <Card title="Output Parts" icon="shapes" href="/parts">
    How to read output items and `text`, `image`, `video`, `file`, and `json` parts.
  </Card>
</CardGroup>