API Overview¶

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

The following APIs are available:

API name	Description
Analyze API	Analyze a given NDJSON, CSV, or Parquet file to generate a Tinybird Data Source schema.
Data Sources API	List, create, update, or delete your Tinybird Data Sources, and insert or delete data from Data Sources.
Events API	Ingest NDJSON events with a simple HTTP POST request.
Jobs API	Get details on Tinybird jobs, and list the jobs for the last 48 hours or the last 100 jobs.
Pipes API	Interact with your Pipes, including Pipes themselves, API Endpoints, Materialized Views, and managing Copy jobs.
Query API	Query your Pipes and Data Sources inside Tinybird as if you were running SQL statements against a regular database.
Environment Variables API	Create, update, delete, and list variables that can be used in Pipes in a Workspace.
Sink Pipes API	Create, delete, schedule, and trigger Sink Pipes.
Tokens API	List, 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

Region	Provider	Provider region	API base URL
Europe	GCP	europe-west3	https://api.tinybird.co
US East	GCP	us-east4	https://api.us-east.tinybird.co
Europe	AWS	eu-central-1	https://api.eu-central-1.aws.tinybird.co
US East	AWS	us-east-1	https://api.us-east.aws.tinybird.co
US West	AWS	us-west-2	https://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 or region with the API region that matches your Workspace.

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
400	Bad request. This could be due to a missing parameter in a request, for instance
403	Forbidden. Provided auth token doesn't have the right scope or the Data Source is not available
404	Not found
405	HTTP Method not allowed
408	Request timeout (e.g. query execution time was exceeded)
409	You 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)
411	No valid Content-Length header containing the length of the message-body
413	The message body is too large
429	Too many requests. When over the rate limits of your account
500	Unexpected 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.