API Endpoints¶

Tinybird can turn any Pipe into an API Endpoint that you can query. For example, you can ingest your data, build SQL logic inside a Pipe, and then publish the result of your query as an HTTP API Endpoint. You can then create interactive Charts of your data.

API Endpoints make it easy to use the results of your queries in applications. Any app that can run an HTTP GET can use Tinybird API Endpoints.

Tinybird represents API Endpoints using the icon.

Create an API Endpoint¶

To create an API Endpoint, you first need a Pipe. You can publish any of the queries in your Pipes as an API Endpoint.

Using the UI¶

First, create a Pipe in the UI.

In the Pipe, select Create API Endpoint, then select the Node that you want to publish.

Using the CLI¶

First, create a Pipe using the Tinybird CLI.

Use the following command to publish an API Endpoint from the CLI. This automatically selects the final Node in the Pipe.

tb pipe publish PIPE_NAME_OR_ID

If you want to manually select a different Node to publish, supply the Node name as the final command argument:

tb pipe publish PIPE_NAME_OR_ID NODE_NAME

Secure your API Endpoints¶

Access to the APIs you publish in Tinybird are also protected with Tokens.

You can limit which operations a specific Token can do through scopes. For example, you can create Tokens that are only able to do admin operations on Tinybird resources, or only have READ permission for a specific Data Source.

See Tokens to understand how they work and see what types are available.

API gateways¶

API gateways allow you to cloak or rebrand Tinybird API Endpoints while meeting additional security and compliance requirements.

When you publish an API Endpoint in Tinybird, it's available through api.tinybird.co or the API Gateway URL that corresponds to your Workspace region. See API Endpoint URLs. API Endpoints are secured using Tokens that are managed inside your Tinybird Workspace.

Sometimes you might want to put the Tinybird API Endpoints behind an API Gateway. For example:

• To present a unified brand experience to your users.
• To avoid exposing Tokens and the underlying technology.
• To comply with regulations around data privacy and security.
• To add Tinybird to an existing API architecture.

Alternative approaches¶

You can meet the requirements satisfied by an API gateway through other methods.

• Use JSON Web Tokens (JWTs) to habe your application call Tinybird API Endpoints from the frontend without proxying through your backend.
• Appropriately scope the Token used inside your application. Exposing a read-only Token has limited security concerns as it can't be used to modify data. You can invalidate the Token at any time.
• Use row-level security to ensure that an Token only provides access to the appropriate data.

Amazon API Gateway¶

The steps to create a reverse proxy using Amazon API Gateway are as follows:

1. Access the API Gateway console.
2. Select Create API, then HTTP API.
3. Select Add Integration and then select HTTP.
4. Configure the integration with the method GET and the full URL to your Tinybird API with its Token. For example, https://api.tinybird.co/v0/pipes/top-10-products.json?token=p.eyJ1Ijog...
5. Set a name for the API and select Next.
6. On the Routes page, set the method to GET and configure the desired Resource path. For example, /top-10-products.
7. Go through the rest of the step to create the API.

You can find more information about applying a custom domain name in the Amazon API Gateway documentation.

Google Cloud Apigee¶

The steps to create a reverse proxy using Apigee are as follows:

1. Access the Apigee console.
2. Add a new Reverse Proxy.
3. Add your Base path. For example, /top-10-products.
4. Add the Target. For example, https://api.tinybird.co/v0/pipes/top-10-products.json?token=p.eyJ1Ijog...
5. Select Pass through for security.
6. Select an environment to deploy the API to.
7. Deploy, and test the API.

You can find more information about applying a custom domain name in the Apigee documentation.

Grafbase Edge Gateway¶

To create a new Grafbase Edge Gateway using the Grafbase CLI, follow these steps.

Inside a new directory, run:

npx grafbase init --template openapi-tinybird

In Tinybird, open your API Endpoint page. Select Create Chart, Share this API Endpoint, then select OpenAPI 3.0. Copy the link that appears, including the full Token.

Create an .env file using the following template and enter the required details.

# TINYBIRD_API_URL is the URL for your published API Endpoint
TINYBIRD_API_URL=
# TINYBIRD_API_TOKEN is the Token with READ access to the API Endpoint
TINYBIRD_API_TOKEN=
# TINYBIRD_API_SCHEMA is the OpenAPI 3.0 spec URL copied from the API Endpoint docs page
TINYBIRD_API_SCHEMA=

You can now run the Grafbase Edge Gateway locally:

npx grafbase dev

Open the local Pathfinder at http://127.0.0.1:4000 to test your Edge Gateway.

Here is an example GraphQL query:

query Tinybird {
    tinybird {
        topPages {
            data {
                action
                payload
            }
            rows
        }
    }
}

NGINX¶

The following is an example NGINX configuration file that handles a GET request and make the request to Tinybird on your behalf. The Token is only accessed server-side and never exposed to the user.

worker_processes  1;

events {
    worker_connections  1024;
}

http {
    server {
        listen       8080;
        server_name  localhost;
        location /top-10-products {
                proxy_pass https://api.tinybird.co/v0/pipes/top-10-products.json?token=p.eyJ1Ijog...;
        }
    }
}

Query API and API Endpoints¶

The Query API is similar to running SQL statements against a normal database instead of using it as your backend, which is useful for ad-hoc queries.

Publish API Endpoints instead of using the Query API in the following situations:

• You want to build and maintain all the logic in Tinybird and call the API Endpoint to fetch the result.
• You want to use incremental Nodes in your Pipes to simplify the development and maintenance of your queries.
• You need support for query parameters and more complex logic using the Tinybird templating language.
• You need to incorporate changes from your query, which means little downstream impact.

You can monitor performance of individual API Endpoints using pipe_stats_rt and pipe_stats, uncovering optimization opportunities. All requests to the Query API are grouped together, making it more difficult to monitor performance of a specific query.

Errors and retries¶

API Endpoints return standard HTTP success or error codes. For errors, the response also includes extra information about what went wrong, encoded in the response as JSON.

Error codes¶

API Endpoints might return the following HTTP error codes:

Errors when running a query are usually reported as 400 Bad request or 500 Internal Server Error, depending on whether the error can be fixed by the caller or not.

In those cases the API response has an additional HTTP header, X-DB-Exception-Code where you can check the internal database error, reported as a stringified number. For a full list of internal database errors, see List of API Endpoint database errors.

Retries¶

When implementing an API Gateway, make sure to handle potential errors and implement retry strategies where appropriate.

Implement automatic retries for the following errors:

• HTTP 429: Too many requests
• HTTP 500: Internal Server Error

Follow an exponential backoff when retrying requests that produce the previous errors. See Exponential backoff in Wikipedia.

Token limitations with API Gateways¶

When using an API Gateway or proxy between your application and Tinybird, your proxy uses a Token to authenticate requests to Tinybird. Treat the Token as a secret and don't expose it to the client.

Use a service such as Unkey to add multi-tenant API keys, rate limiting, and token usage analytics to your app at scale.

Free plan limits¶

The Free plan is the free tier of Tinybird. See "Tinybird plans").

The Free plan has the following limits on the amount of API requests per day that you can make against published API Endpoints.

These limits don't apply to paid plans. To learn more about how Tinybird bills for different data operations, see Billing.

Next steps¶

• Read more about how to use Tokens in the Tokens docs.
• Read the guide: "Consume APIs in a Next.js frontend with JWTs".
• Understand Tokens.