---
title: Pipes API Reference
meta:
    description: The Pipe API enables you to manage your Pipes. With Pipes you can transform data via SQL queries and publish the results of those queries as API Endpoints.
---

# Pipe API

{% snippet title="api-region-reminder" /%}

{% snippet title="pipes-api-snippet" /%}

All Tinybird API Endpoints require authentication [using a Token](/forward/administration/tokens) with the appropriate scope.

{% callout type="caution" %}
Adding or modifying pipes or data sources in [Tinybird Local](/forward/install-tinybird/local) and [Tinybird Forward](/forward) can only be done through deployments.
{% /callout %}

## Example: create a Tinybird Pipe

Imagine you have an events Data Source named `app_events` and you want to expose an API Endpoint containing the aggregation of events per day.

First, create a Pipe called `events_per_day`:

```shell {% title="creating a Pipe from a Data Source" %}
curl \
-H "Authorization: Bearer <token>" \
-d "name=events_per_day&sql=select * from app_events" \
{% user("apiHost") %}/v0/pipes
```

In the previous snippet, creating the Pipe also defines the first transformation node SQL query, which in this case gets all the data from the Data Source. 

The following JSON example shows a successful request response after creating a Pipe:

```json {% title="Pipe successfully created" %}
{
  "id": "t_1b501ccf34764a69aaf886bac9a7a6d8",
  "name": "events_per_day",
  "published_version": "t_878a81f0e1344a2ca990c8c1aa7dd69f",
  "published_date": "2019-06-14 09:46:07.884855",
  "nodes": [
    {
      "name": "events_per_day_0",
      "sql": "select * from app_events",
      "id": "t_878a81f0e1344a2ca990c8c1aa7dd69f",
      "dependencies": [
        "app_events"
      ],
      "materialized": false,
      "created_at": "2019-06-14 09:46:07.884849"
    }
  ]
}
```

Add a new transformation node to perform the aggregation per date, using the previously created node `events_per_day_0`:

```shell {% title="appending a new node to transform your data" %}
curl -d "select toDate(timestamp) date, count() event_count from events_per_day_0 group by date" \
  -H "Authorization: Bearer <token>" \
  {% user("apiHost") %}/v0/pipes/events_per_day/nodes
```

Whenever a transformation node is added to a Pipe, you receive a response like the following, which summarizes the response and provides an autogenerated name for the node, as well as some metadata such as the dependencies with other transformation nodes:

```json {% title="successful response" %}
{
  "name": "events_per_day_1",
  "sql": "select toDate(timestamp) date, count() event_count from events_per_day_0 group by date",
  "id": "t_5164622050b244338ea2b79c19bd1e57",
  "dependencies": [
    "events_per_day_0"
  ],
  "materialized": false,
  "created_at": "2019-06-14 09:58:08.311812"
}
```

To make a Pipe publicly accessible through the API, activate your desired transformation node as an API Endpoint. Pipes only support one enabled node each, so enabling one makes previously enabled nodes inaccessible.

```shell {% title="Enabling a transformation node as an API Endpoint" %}
curl \
  -X PUT \
  -H "Authorization: Bearer <token>" \
  -d t_878a81f0e1344a2ca990c8c1aa7dd69f \
  {% user("apiHost") %}/v0/pipes/events_per_day/endpoint
```

When enabling a transformation node as an API Endpoint, a JSON containing the full Pipe description is sent as the response.

```json {% title="Successful response" %}
{
  "id": "t_1b501ccf34764a69aaf886bac9a7a6d8",
  "name": "events_per_day",
  "published_version": "t_5164622050b244338ea2b79c19bd1e57",
  "published_date": "2019-06-14 10:17:01.201962",
  "nodes": [
    {
      "name": "events_per_day_0",
      "sql": "select * from app_events",
      "id": "t_878a81f0e1344a2ca990c8c1aa7dd69f",
      "dependencies": [
        "app_events"
      ],
      "materialized": false,
      "created_at": "2019-06-14 10:17:01.201784"
    },
    {
      "name": "events_per_day_1",
      "sql": "select toDate(date) date, count() event_count from events_per_day_0 group by date",
      "id": "t_5164622050b244338ea2b79c19bd1e57",
      "dependencies": [
        "events_per_day_0"
      ],
      "materialized": false,
      "created_at": "2019-06-14 10:17:01.201943"
    }
  ]
}
```

After creating the Pipe and enabling a transformation node as an Endpoint, you can easily integrate it into any third-party application.

Using the [Query API](/api-reference/query-api), you can query the Pipe using its name, like a regular table in a SQL query:

```shell {% title="Querying a Pipe using SQL" %}
curl \
-H "Authorization: Bearer <token>" \
-d 'SELECT * FROM events_per_day where date > yesterday()' \
'{% user("apiHost") %}/v0/sql'
```

{% callout %}
If you don't need to run any special operations against your Pipe, you can use the Pipe data Endpoint accessible at `{% user("apiHost") %}/v0/pipes/events_per_day.json`. It's an alias for `SELECT * FROM events_per_day`.
{% /callout %}

Pipes are updated in real time, so as you insert the new data in `app_events` Data Source, every Pipe using it `events_per_day` is updated.

To share this endpoint, you can create a READ token. You can add a new token for the Pipe with:

> ```shell {% title="Adding a READ Token to an API Endpoint Pipe" %}
> curl -X POST "{% user("apiHost") %}/v0/tokens/?name=events_per_day_token&scope=PIPES:READ:events_per_day"
> ```

## Pipes

{% api_reference api="pipe-list" /%}

{% api_reference api="pipe-node-explain" /%}