API Overview¶

You can control Tinybird services using the API. This is an alternative way to interact with Tinybird, along with the UI and CLI.

There are several APIs available to interact with Tinybird:

Requests to Tinybird's API Endpoints must be made over TLS (HTTPS). All response bodies, including errors, are encoded in JSON.

Regions and endpoints¶

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

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

Current Tinybird regions

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, you will need to replace this with the API base URL for your region.

Authentication¶

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

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

There are two ways two authenticate your requests in the Tinybird API.

1. Authorization header¶

You can send a "Bearer authorization" header. With curl this would look like -H "Authorization: Bearer <token>".

If you have a valid Token with read access to the particular Data Source, you should be able to get a successful response by sending the following 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 via a parameter in the URL, using token=<token>.

The following request is equivalent to the previous one:

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

Errors¶

Tinybird's API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON. The various HTTP status codes we might return are listed below.

Response codes

Limits¶

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, we follow semantic versioning rules. Given a version number MAJOR.MINOR.PATCH, we increment the:

• MAJOR version when you make incompatible API changes,
• MINOR version when you add functionality in a backwards-compatible manner, and
• PATCH version when you make backwards-compatible bug fixes.

Forbidden names¶

Words below are considered as reserved words and cannot be used to name Data Sources, Pipes, Nodes or Workspaces. Case of the words 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 cannot use an alias for a column that matches a globally unique name.