API Overview

You can control Tinybird services using the API as an alternative to the UI and CLI.

The following APIs are available:

API nameDescription
Analyze APIAnalyze a given NDJSON, CSV, or Parquet file to generate a Tinybird Data Source schema.
Data Sources APIList, create, update, or delete your Tinybird Data Sources, and insert or delete data from Data Sources.
Events APIIngest NDJSON events with a simple HTTP POST request.
Jobs APIGet details on Tinybird jobs, and list the jobs for the last 48 hours or the last 100 jobs.
Pipes APIInteract with your Pipes, including Pipes themselves, API Endpoints, Materialized Views, and managing Copy jobs.
Query APIQuery your Pipes and Data Sources inside Tinybird as if you were running SQL statements against a regular database.
Environment Variables APICreate, update, delete, and list variables that can be used in Pipes in a Workspace.
Sink Pipes APICreate, delete, schedule, and trigger Sink Pipes.
Tokens APIList, create, update, or delete your Tinybird Static Tokens.

Make all requests to Tinybird's API Endpoints over TLS (HTTPS). All response bodies, including errors, are encoded as JSON.

You can get information on several Workspace operations by monitoring your jobs, using either the APIs or the built-in Tinybird Service Data Sources.

Regions and endpoints

A Workspace belongs to one region. The API for each region has a specific API base URL that you use to make API requests.

The following table lists the current regions and their corresponding API base URLs:

Current Tinybird regions

RegionProviderProvider regionAPI base URL
EuropeGCPeurope-west3https://api.tinybird.co
US EastGCPus-east4https://api.us-east.tinybird.co
EuropeAWSeu-central-1https://api.eu-central-1.aws.tinybird.co
US EastAWSus-east-1https://api.us-east.aws.tinybird.co
US WestAWSus-west-2https://api.us-west-2.aws.tinybird.co

Tinybird documentation uses https://api.tinybird.co as the default example API base URL in code snippets. If you are not using the Europe GCP region, replace the sample URL with the API base URL for your region.

Authentication

Tinybird makes use of Tokens for every API call. This ensures that each user or application can only access data that they are authorized to access. See Tokens.

You must make all API requests over HTTPS. Don't make calls over plain HTTP or send API requests without authentication.

Replace the Tinybird API hostname/region with the right API URL region that matches your Workspace. Your Token lives in the Workspace under "Tokens".

There are two ways to authenticate your requests in the Tinybird API: using an authorization header, or using a URL parameter.

1. Authorization header

You can send a Bearer authorization header to authenticate API calls. With curl, use -H "Authorization: Bearer <token>".

If you have a valid Token with read access to the particular Data Source, you can get a successful response by sending the following request:

Authorization header Authenticated request
curl \
-X GET \
-H "Authorization: Bearer <token>" \
"https://api.tinybird.co/v0/sql?q=SELECT+*+FROM+<pipe>"

2. URL parameter

You can also specify the Token using a parameter in the URL, using token=<token>. For example:

URL parameter authenticated request
curl -X GET \
"https://api.tinybird.co/v0/sql?q=SELECT+*+FROM+<pipe>&token=<token>"

Compression

To compress API responses, add Accept-Encoding: gzip to your requests. For example:

Request with compressed response
curl \
-X GET \
-H "Authorization: Bearer <token>" \
-H "Accept-Encoding: gzip" \
"https://api.tinybird.co/v0/sql?q=SELECT+*+FROM+<pipe>"

Errors

Tinybird's API returns standard HTTP success or error status codes. In case of errors, responses include additional information in JSON format.

The following table lists the error status codes.

Response codes

Code Description
400Bad request. This could be due to a missing parameter in a request, for instance
403Forbidden. Provided auth token doesn't have the right scope or the Data Source is not available
404Not found
405HTTP Method not allowed
408Request timeout (e.g. query execution time was exceeded)
409You need to resubmit the request due to a conflict with the current state of the target source (e.g.: you need to delete a Materialized View)
411No valid Content-Length header containing the length of the message-body
413The message body is too large
429Too many requests. When over the rate limits of your account
500Unexpected error

Limits

Check the limits page for limits on ingestion, queries, API Endpoints, and more.

Versioning

All Tinybird APIs are versioned with a version string specified in the base URL. We encourage you to always use the latest API available.

When versioning our web services, Tinybird adheres to semantic versioning rules.

Reserved words

The following keywords are reserved words. You can't use them to name Data Sources, Pipes, Nodes or Workspaces. Case is ignored.

  • Array
  • Boolean
  • Date
  • Date32
  • DateTime
  • DateTime32
  • DateTime64
  • Decimal
  • Decimal128
  • Decimal256
  • Decimal32
  • Decimal64
  • Enum
  • Enum16
  • Enum8
  • FixedString
  • Float32
  • Float64
  • IPv4
  • IPv6
  • Int128
  • Int16
  • Int256
  • Int32
  • Int64
  • Int8
  • MultiPolygon
  • Point
  • Polygon
  • Ring
  • String
  • TABLE
  • UInt128
  • UInt16
  • UInt256
  • UInt32
  • UInt64
  • UInt8
  • UUID
  • _temporary_and_external_tables
  • add
  • after
  • all
  • and
  • anti
  • any
  • array
  • as
  • asc
  • asof
  • between
  • by
  • case
  • collate
  • column
  • columns
  • cross
  • cube
  • custom_error
  • day_diff
  • default
  • defined
  • desc
  • distinct
  • else
  • end
  • enumerate_with_last
  • error
  • exists
  • from
  • full
  • functions
  • generateRandom
  • global
  • group
  • having
  • if
  • ilike
  • in
  • inner
  • insert
  • interval
  • into
  • join
  • left
  • like
  • limit
  • limits
  • max
  • min
  • not
  • null
  • numbers_mt
  • on
  • one
  • or
  • order
  • outer
  • prewhere
  • public
  • right
  • sample
  • select
  • semi
  • split_to_array
  • sql_and
  • sql_unescape
  • system
  • table
  • then
  • tinybird
  • to
  • union
  • using
  • where
  • with
  • zeros_mt

Pipe, Data Source and Node names are globally unique. You can't use an alias for a column that matches a globally unique name.

Was this page helpful?
Updated