Skip to main content

​
Overview

createTinybirdApi() creates a low-level API wrapper that provides direct access to Tinybird’s REST API. This is a standalone alternative to the typed TinybirdClient that requires only a baseUrl and token. Use this when you:
  • Want a simple API client without type definitions
  • Need dynamic access without compile-time schemas
  • Are building scripts, CLI tools, or integrations
  • Don’t want to define datasources and pipes in TypeScript

​
Signature

function createTinybirdApi(config: TinybirdApiConfig): TinybirdApi

​
Parameters

​
config
TinybirdApiConfig
required
Configuration object with the following properties:

​
Return Value

Returns a TinybirdApi instance with methods for querying, ingesting, and managing data.

​
Example

​
Basic Usage

import { createTinybirdApi } from "@tinybirdco/sdk";

const api = createTinybirdApi({
  baseUrl: "https://api.tinybird.co",
  token: process.env.TINYBIRD_TOKEN!,
});

// Query an endpoint
interface TopPagesRow { pathname: string; visits: number }

const result = await api.query<TopPagesRow>("top_pages", {
  start_date: "2024-01-01",
  end_date: "2024-01-31",
  limit: 5,
});

console.log(result.data);

​
Ingest Data

interface EventRow {
  timestamp: string;
  event_name: string;
  pathname: string;
}

// Ingest a single row
await api.ingest<EventRow>("events", {
  timestamp: "2024-01-15 10:30:00",
  event_name: "page_view",
  pathname: "/home",
});

// Ingest multiple rows
await api.ingestBatch<EventRow>("events", [
  { timestamp: "2024-01-15 10:30:00", event_name: "page_view", pathname: "/home" },
  { timestamp: "2024-01-15 10:31:00", event_name: "click", pathname: "/pricing" },
]);

​
Manage Datasource Data

// Import rows from a remote file
await api.appendDatasource("events", {
  url: "https://example.com/events.csv",
});

// Delete rows matching a SQL condition
await api.deleteDatasource("events", {
  deleteCondition: "event_name = 'test'",
});

// Preview deletion without executing
const preview = await api.deleteDatasource("events", {
  deleteCondition: "event_name = 'test'",
  dryRun: true,
});
console.log(`Would delete ${preview.rows_to_be_deleted} rows`);

// Remove all rows from the datasource
await api.truncateDatasource("events");

​
Execute Raw SQL

interface CountResult { total: number }

const result = await api.sql<CountResult>(
  "SELECT count() AS total FROM events"
);

console.log(`Total events: ${result.data[0].total}`);

​
Custom Fetch Implementation

import { createTinybirdApi } from "@tinybirdco/sdk";
import { fetch } from "undici";

const api = createTinybirdApi({
  baseUrl: "https://api.tinybird.co",
  token: process.env.TINYBIRD_TOKEN!,
  fetch, // Use undici's fetch
  timeout: 60000, // 60 second timeout
});

​
Per-Request Token Override

const api = createTinybirdApi({
  baseUrl: "https://api.tinybird.co",
  token: process.env.TINYBIRD_DEFAULT_TOKEN!,
});

// Use a different token for this request
await api.query(
  "top_pages",
  { start_date: "2024-01-01", end_date: "2024-01-31" },
  { token: process.env.TINYBIRD_BRANCH_TOKEN }
);

​
Configuration Options

​
Base URL by Region

Tinybird operates in multiple regions. Use the appropriate base URL for your workspace:
RegionBase URL
EU (default)https://api.tinybird.co
US Easthttps://api.us-east.tinybird.co

​
Token Types

Different token types grant different levels of access:
Token TypePrefixCapabilities
Adminp.Full access: read, write, manage resources
Readp.Query endpoints only
Appendp.Ingest data into datasources only
JWTeyJScoped, time-limited access with fixed parameters
See the JWT Token Creation section for creating scoped tokens programmatically.

​
Custom Timeouts

Set a default timeout for all requests, or override per-request: 
const api = createTinybirdApi({
  baseUrl: "https://api.tinybird.co",
  token: process.env.TINYBIRD_TOKEN!,
  timeout: 60000, // 60 second default timeout
});

// Override for a specific request
await api.query(
  "long_running_query",
  { start_date: "2020-01-01", end_date: "2024-12-31" },
  { timeout: 120000 } // 2 minute timeout
);

​
Alias

createTinybirdApiWrapper() is an alias for teams that prefer “wrapper” naming: 
import { createTinybirdApiWrapper } from "@tinybirdco/sdk";

const api = createTinybirdApiWrapper({
  baseUrl: "https://api.tinybird.co",
  token: process.env.TINYBIRD_TOKEN!,
});

​
When to Use This vs. Tinybird Client

​
Use createTinybirdApi() when:

  • Building scripts, CLI tools, or automation
  • You don’t want to define schemas in TypeScript
  • Working with dynamic datasources/pipes
  • Prototyping or exploring the API
  • Integrating into non-TypeScript projects

​
Use Tinybird client when:

  • You want full type safety and autocomplete
  • Working in a TypeScript application
  • Managing datasources and pipes as code
  • Need compile-time validation of queries and ingestion
  • Want to leverage the full SDK tooling (tinybird dev, tinybird deploy, etc.)
See the Tinybird Client documentation for the typed approach.

​
Error Handling

All API methods throw TinybirdApiError on failure: 
import { createTinybirdApi, TinybirdApiError } from "@tinybirdco/sdk";

const api = createTinybirdApi({
  baseUrl: "https://api.tinybird.co",
  token: process.env.TINYBIRD_TOKEN!,
});

try {
  await api.query("broken_endpoint");
} catch (error) {
  if (error instanceof TinybirdApiError) {
    console.error(`Status: ${error.statusCode}`);
    console.error(`Message: ${error.message}`);
    console.error(`Response:`, error.response);
    console.error(`Raw Body:`, error.responseBody);
  }
}

TinybirdApi

Full API reference for the TinybirdApi class

Tinybird Client

Type-safe client with schema definitions

Build docs developers (and LLMs) love

Get started for freeTalk to us