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

# API quickstart

> Create, deploy, and monitor a Beam pipeline using curl.

<Info>
  **Prerequisites:** You need an Allium API key. Get one from [app.allium.so/settings/api-keys](https://app.allium.so/settings/api-keys).
</Info>

This guide walks through the full lifecycle of a Beam pipeline using the REST API: create a config, populate filter values, deploy, and check health.

## Setup

```bash theme={null}
export ALLIUM_API_KEY="your-api-key-here"
```

All requests use the `X-API-Key` header for authentication against the base URL `https://api.allium.so/api/v1/beam`.

## Filter USDC transfers on Base

<Steps>
  <Step title="Create the pipeline config">
    Create a pipeline that streams ERC20 transfers on Base, filtered by token address using a Redis set filter, and outputs to a managed Kafka topic.

    ```bash theme={null}
    RESP=$(curl -s -X POST https://api.allium.so/api/v1/beam \
      -H "X-API-Key: ${ALLIUM_API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "USDC Transfer Monitor",
        "description": "Monitors USDC ERC20 transfers on Base",
        "tags": ["quickstart"],
        "pipeline_config": {
          "source": {
            "type": "pubsub",
            "chain": "base",
            "entity": "erc20_token_transfer",
            "is_zerolag": false
          },
          "transforms": [
            {
              "type": "redis_set_filter",
              "filter_expr": "root = this.token_address"
            }
          ],
          "sinks": [
            {
              "type": "kafka",
              "name": "usdc-transfers"
            }
          ]
        }
      }')
    echo "Response is $RESP" | jq
    CONFIG_ID=$(echo "$RESP" | jq -r '.id')
    echo "CONFIG_ID=${CONFIG_ID}"
    ```

    The response returns the full `BeamConfig` with a generated `id`.
  </Step>

  <Step title="Get the transform UID">
    Fetch the config to extract the auto-generated transform UID — you'll need it to manage filter values.

    ```bash theme={null}
    RESP=$(curl -s -X GET "https://api.allium.so/api/v1/beam/${CONFIG_ID}" \
      -H "X-API-Key: ${ALLIUM_API_KEY}")

    TRANSFORM_UID=$(echo "$RESP" | jq -r '.pipeline_config.transforms[0].uid')
    echo "TRANSFORM_UID=${TRANSFORM_UID}"
    ```
  </Step>

  <Step title="Add filter values">
    Add the USDC contract address on Base. Use **lowercase** — values are normalized in the system.

    ```bash theme={null}
    curl -s -X POST https://api.allium.so/api/v1/beam/${CONFIG_ID}/transforms/${TRANSFORM_UID}/filter-values \
      -H "X-API-Key: ${ALLIUM_API_KEY}" \
      -H "Content-Type: application/json" \
      -d '{ "values": ["0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"] }' | jq
    ```

    Expected: `{ "added": 1 }`
  </Step>

  <Step title="Deploy">
    ```bash theme={null}
    curl -s -X POST https://api.allium.so/api/v1/beam/${CONFIG_ID}/deploy \
      -H "X-API-Key: ${ALLIUM_API_KEY}" | jq
    ```

    Expected: `{"message": "Pipeline <CONFIG_ID> successfully deployed"}`
  </Step>

  <Step title="Check deployment health">
    ```bash theme={null}
    curl -s -X GET https://api.allium.so/api/v1/beam/${CONFIG_ID}/deploy/stats \
      -H "X-API-Key: ${ALLIUM_API_KEY}" | jq
    ```

    `healthy_workers` should match `total_workers`. If workers are still starting, wait a few seconds and retry.
  </Step>

  <Step title="Verify filter values">
    ```bash theme={null}
    curl -s -X GET "https://api.allium.so/api/v1/beam/${CONFIG_ID}/transforms/${TRANSFORM_UID}/filter-values?count=10" \
      -H "X-API-Key: ${ALLIUM_API_KEY}" | jq
    ```

    You should see your USDC address in the `values` array. Data is now streaming to `beam.${CONFIG_ID}.usdc-transfers`.
  </Step>
</Steps>

## What's next

* **Update your pipeline** — modify the config with `PUT /api/v1/beam/{config_id}`, then redeploy. No need to teardown first.
* **Monitor metrics** — use `GET /api/v1/beam/{config_id}/deploy/metrics?time_range=1h&aggregated=true` for a throughput summary.
* **Add more filter values** — post additional addresses to the filter values endpoint at any time (no redeploy needed).

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/beam/api-reference/overview">
    Full endpoint reference
  </Card>

  <Card title="Configuration reference" icon="sliders" href="/beam/api-reference/configuration">
    Source, transform, and sink schemas
  </Card>
</CardGroup>