# Pipeline API

The Pipeline API executes active saved pipelines for a workspace. Pipelines run sequential pipe actions and return the execution status, output, optional pipeline response, error message, and execution log ID.

## Execute a pipeline

```http
POST /api/v1/{workspace}/pipelines/{id_or_name}/execute
```

The `{workspace}` segment is the workspace name. The `{id_or_name}` segment accepts either the pipeline ID or its slug name.

### Authentication

Requires an API key for the target workspace with pipeline execution access. Pipelines are resolved through the route workspace.

See [API Authentication](/docs/api/authentication) and [API Access](/docs/platform/api-access).

### Request body

| Field | Required | Type | Description |
|---|---|---|---|
| `input` | No | object | Payload made available to the pipeline as `{input.*}` |
| `dry_run` | No | boolean | Runs in test mode where supported |

### Example request

```shell
curl -X POST "https://app.example.com/api/v1/acme/pipelines/123/execute" \
  -H "Authorization: Bearer $VIRESSO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "input": {
      "email": "customer@example.com",
      "name": "Ada Lovelace"
    },
    "dry_run": false
  }'
```

### Example response

```json
{
  "execution_id": 42,
  "status": "success",
  "output": {
    "dry_run": false,
    "steps": [
      {
        "id": "validate-email",
        "type": "validate_data",
        "name": "Validate email",
        "status": "success",
        "message": "Validation passed.",
        "output": {
          "validated": true
        }
      }
    ],
    "total_steps": 1,
    "context": {
      "input": {
        "email": "customer@example.com",
        "name": "Ada Lovelace"
      },
      "pipes": {
        "validate-email": {
          "validated": true
        }
      }
    }
  },
  "response": null,
  "error": null
}
```

If the pipeline uses a response pipe, the `response` object contains the configured status, headers, and body. The HTTP status also follows the configured response status for successful executions.

### Queued execution

With a queue worker configured, send `Prefer: respond-async` to return immediately with HTTP `202` and a pending execution. Poll the returned `status_url` with the same API key until its status is `success` or `failed`.

```json
{
  "execution_id": 42,
  "status": "pending",
  "status_url": "https://app.example.com/api/v1/acme/pipelines/123/executions/42"
}
```

The status endpoint returns `execution_id`, `status`, `output`, and `error`. When the queue driver is `sync` or `null`, requests continue to execute inline.

## Failure responses

If a pipe fails, execution stops and the response returns `422` with the failed execution ID, output collected so far, and a safe error message.

```json
{
  "execution_id": 43,
  "status": "failed",
  "output": {
    "dry_run": false,
    "steps": [
      {
        "id": "validate-email",
        "type": "validate_data",
        "name": "Validate email",
        "status": "failed",
        "message": "The email field must be a valid email address.",
        "output": []
      }
    ],
    "total_steps": 1,
    "context": {
      "input": {
        "email": "not-an-email"
      }
    }
  },
  "response": null,
  "error": "The email field must be a valid email address."
}
```

If the pipeline is not active, the API returns `422` before execution:

```json
{
  "message": "Only active pipelines can be executed through the API."
}
```

HTTP request pipe connection failures return a failed pipeline execution with a safe `"HTTP request failed."` message. Provider response bodies are not logged.

## Status codes

| Status | Meaning |
|---|---|
| 100–599 | A successful response pipe uses its configured HTTP status; successful pipelines without one return `200` |
| 403 | Invalid API key, origin mismatch, missing pipeline execution access, or forbidden workspace access |
| 404 | Pipeline or workspace not found |
| 202 | Queued execution accepted |
| 422 | Request validation failed, inactive pipeline, or pipeline execution failed |
| 429 | Rate limit exceeded |

## Related pages

- [Pipelines](/docs/platform/pipelines) — Designing and testing pipelines.
- [API Authentication](/docs/api/authentication) — API key authentication.
- [API Overview](/docs/api/overview) — Base URL, headers, and standard error format.