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

# Pipeline REST API

> The Pipeline REST API lets you create, update, monitor, and delete pipelines programmatically - everything the Platform UI does, scripted.

The Pipeline REST API exposes the same operations as the **Manage Pipelines** view in the GoldRush Platform: list pipelines, create new ones, edit configuration, pause and resume, and inspect runtime state. Use it when you want pipelines to be managed by code - infrastructure-as-code, CI/CD, internal tooling - rather than by hand in the UI.

## Base URL

```
https://api.covalenthq.com/platform/pipeline-api/
```

## Authentication

All endpoints require a [ServiceKey](/goldrush-pipeline-api/service-keys) sent as a bearer token. Regular GoldRush API keys are rejected with `403`.

```bash theme={null}
curl https://api.covalenthq.com/platform/pipeline-api/ \
  -H "Authorization: Bearer $GOLDRUSH_SERVICE_KEY"
```

## Endpoints

<CardGroup cols={2}>
  <Card title="List pipelines" href="/api-reference/pipeline-api/list-pipelines">
    `GET /platform/pipeline-api/` - paginated list of pipelines visible to your ServiceKey.
  </Card>

  <Card title="Create a pipeline" href="/api-reference/pipeline-api/create-pipeline">
    `POST /platform/pipeline-api/` - create from a JSON config that mirrors the YAML schema.
  </Card>

  <Card title="Get a pipeline" href="/api-reference/pipeline-api/get-pipeline">
    `GET /platform/pipeline-api/{id}/` - fetch a single pipeline. Secrets returned as `******`.
  </Card>

  <Card title="Set pipeline status" href="/api-reference/pipeline-api/set-pipeline-status">
    `PUT /platform/pipeline-api/{id}/` - pause or resume by flipping `status`.
  </Card>

  <Card title="Update a pipeline" href="/api-reference/pipeline-api/update-pipeline">
    `PATCH /platform/pipeline-api/{id}/` - partial update of any writeable field.
  </Card>

  <Card title="Delete a pipeline" href="/api-reference/pipeline-api/delete-pipeline">
    `DELETE /platform/pipeline-api/{id}/` - permanent removal.
  </Card>

  <Card title="Status" href="/api-reference/pipeline-api/get-pipeline-status">
    `GET /platform/pipeline-api/{id}/status/` - runtime deployment phase.
  </Card>

  <Card title="Logs" href="/api-reference/pipeline-api/get-pipeline-logs">
    `GET /platform/pipeline-api/{id}/logs/` - recent worker log lines.
  </Card>

  <Card title="Metrics" href="/api-reference/pipeline-api/get-pipeline-metrics">
    `GET /platform/pipeline-api/{id}/metrics/` - throughput and lag snapshot.
  </Card>

  <Card title="Destination health" href="/api-reference/pipeline-api/get-pipeline-destination-health">
    `GET /platform/pipeline-api/{id}/destination-health/` - last connectivity check.
  </Card>
</CardGroup>

## Response envelope

Every response follows the standard GoldRush envelope:

```json theme={null}
{
  "data": { /* endpoint-specific payload */ },
  "error": false,
  "error_message": null,
  "error_code": null
}
```

List endpoints add `pagination` alongside `items`:

```json theme={null}
{
  "data": {
    "items": [ /* ... */ ],
    "pagination": {
      "page_number": 1,
      "page_size": 100,
      "total_count": 28,
      "has_more": false
    },
    "updated_at": "2026-04-29T05:53:16.294857+00:00"
  },
  "error": false,
  "error_message": null,
  "error_code": null
}
```

## End-to-end example

The flow below creates a pipeline that streams Base swap logs into Postgres, waits for the runtime to come up, and then pauses it.

<Steps>
  <Step title="Create the pipeline">
    ```bash theme={null}
    curl https://api.covalenthq.com/platform/pipeline-api/ \
      -X POST \
      -H "Authorization: Bearer $GOLDRUSH_SERVICE_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Base swaps to Postgres",
        "project": "analytics-prod",
        "description": "Uniswap v3 swaps on Base, unbounded",
        "topic": "base.mainnet.ref.block.swap.v3",
        "destination_type": "postgres",
        "destination_config": {
          "type": "postgres",
          "url": "postgresql://db.example.com:5432/analytics",
          "user": "goldrush",
          "password": "REDACTED"
        },
        "transforms": {
          "swaps": "SELECT chain_name, block_height, tx_hash, protocol, pair_address, token0, token1 FROM swaps WHERE protocol = '\''uniswap_v3'\''"
        },
        "execution_mode": "unbounded",
        "execution_start_from": "44745000"
      }'
    ```

    The response includes the new `id` (e.g. `pipe_3e8678c5fc9e48a7bf9879ca729`).
  </Step>

  <Step title="Wait for it to come up">
    Poll the status endpoint until `status == "RUNNING"` and `ready == replicas`:

    ```bash theme={null}
    curl https://api.covalenthq.com/platform/pipeline-api/pipe_3e8678c5fc9e48a7bf9879ca729/status/ \
      -H "Authorization: Bearer $GOLDRUSH_SERVICE_KEY"
    ```
  </Step>

  <Step title="Pause it">
    ```bash theme={null}
    curl https://api.covalenthq.com/platform/pipeline-api/pipe_3e8678c5fc9e48a7bf9879ca729/ \
      -X PATCH \
      -H "Authorization: Bearer $GOLDRUSH_SERVICE_KEY" \
      -H "Content-Type: application/json" \
      -d '{"status": "paused"}'
    ```
  </Step>
</Steps>

## Two notions of "status"

The API exposes two distinct status fields. Don't confuse them:

| Where                                 | Field    | Values                                                            | Meaning                                           |
| ------------------------------------- | -------- | ----------------------------------------------------------------- | ------------------------------------------------- |
| Pipeline object (`GET /{id}/`)        | `status` | `running`, `paused`                                               | User intent. What the user asked for.             |
| Status endpoint (`GET /{id}/status/`) | `status` | `DEPLOYING`, `RUNNING`, `PAUSED`, `FAILED`, `STOPPING`, `STOPPED` | Runtime phase. What the worker is actually doing. |

A pipeline you just created via `POST` has `status: "running"` immediately, but the status endpoint will show `DEPLOYING` for several seconds until the worker comes up. Use the status endpoint when you need to know whether the pipeline is actually live.

## Secrets are masked on read

Destination credentials (passwords, tokens, secret access keys) are returned as `******` from `GET` endpoints. To rotate a secret, send a `PATCH` with the new value in `destination_config` - never send the masked `******` back.

## See also

* [Service Keys](/goldrush-pipeline-api/service-keys) - how to create and rotate the credential.
* [Configuration Reference](/goldrush-pipeline-api/configuration) - the YAML schema that the JSON request bodies mirror.
* [Destinations](/goldrush-pipeline-api/destinations/overview) - the shape of `destination_config` for each `destination_type`.