API Reference¶

You can use this API to access all our API endpoints, such as the Query API to run fast queries, or the Import API to import data to your account.

The API is organized around REST. All requests should be made over SSL. On the other hand, all request and response bodies, including errors, are encoded in JSON.

We also have built an specific javascript library to make Tinybird easier to use directly from your frontend applications.

Authentication¶

Tinybird makes use of Auth tokens for every API call, so we can ensure different users or applications only get access to the data and permissions they should. Learn more about Auth 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 provide a bearer authorization header, using -H "Authorization: Bearer <token>.

If you have a valid token with read access to the particular Datasource, you should be able to get a succesfull 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+example"

2. URL parameter¶

You can also specify the token via a URL parameter, using token=<token>.

The following request will end with the same result as before.

URL parameter authenticated request¶

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

Errors¶

Tinybird 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¶
Code	Description
200	No error
403	Forbidden. Provided Auth token doesn’t have the right scope or the datasource is not available

Rate Limits¶

Tinybird APIs have rate limits that cap the number of requests that can be made against an endpoint.

Your rate limit will depend on your pricing plan. If you exceed a rate limit, your request will be throttled and you will receive HTTP 429 Too Many Requests responses from the API.

Versioning¶

All Tinybird APIs are versioned with a version string specified in the base URL, but using the newest available API is always encouraged.

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.

Tinybirddocs