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

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 and API Access.

Request body

Example request

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

{
  "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.

{
  "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.

{
  "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:

{
  "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

Related pages

• Pipelines — Designing and testing pipelines.
• API Authentication — API key authentication.
• API Overview — Base URL, headers, and standard error format.