Share Tinybird API Endpoints documentation

In this guide, you'll learn ways of sharing your Tinybird API Endpoints documentation with development teams.

The Tinybird API Endpoint page

When you publish an API Endpoint, Tinybird generates a documentation page for you that is ready to share and OpenAPI-compatible (v3.0). It contains your API Endpoint description, information about the dynamic parameters you can use when querying this Endpoint, and code snippets for quickly integrating your API in 3rd party applications.

To share your published API Endpoint, select the "Share docs" button on the UI (top right) and select your preferred method from the modal.

Use Auth Tokens to define API Endpoint subsets

Tinybird authentication is based on Auth Tokens which contain different scopes for specific resources. For example, an Auth Token lets you read from one or many API Endpoints, or get write permissions for a particular Data Source.

If you take a closer look at the URLs generated for sharing a public API Endpoint page, you'll see that after the Endpoint ID, it includes a token parameter. This means that this page is only accessible if the Auth Token provided in the URL has read permissions for it:

https://api.tinybird.co/endpoint/t_bdcad2252e794c6573e21e7e?token=<token_with_permissions>

For security, Tinybird automatically generates a read-only Auth Token when sharing a public API Endpoint page for the first time. If you don't explicitly use it, your Admin Token won't ever get exposed.

The API Endpoints list page

Tinybird also allows you to render the API Endpoints information for a given Token.

https://api.tinybird.co/endpoints?token=<your_token>

Enter the URL above (with your Token) into the browser, and it'll return a list that shows all API Endpoints that this token can read from.

The API Endpoints list page is extremely useful for sharing your API Endpoint documentation with development teams

When integrating your API Endpoint in your applications it is highly recommend that you manage dedicated Auth Tokens. The easiest way is creating an Auth Token for every application environment, so that you can also track the different requests to your API Endpoints by application, and choose which API Endpoints are accessible for them.

Once you do that, you can share auto-generated documentation with ease, without compromising your data privacy and security.

API Endpoint docs pages include a read token by default. In the "Share this API Endpoint" modal, you can also see public URLs for every Auth Token with read permissions for your Pipe.

Browse your docs in Swagger 😎

As mentioned above, all Tinybird's documentation is compatible with OpenAPI 3.0 and accessible via API. A quick way of generating documentation in Swagger is navigating to the "Share docs" modal > OpenAPI 3.0 tab, copying the "Shareable link" URL, and using it in your preferred Swagger installation.

You can generate as many URLs as you need by using different Auth Tokens

If you use an Auth Token with permissions for more than one API Endpoint, the Swagger documentation will contain information about all the API Endpoints at once.