openapi: 3.0.3
info:
  title: Tinybird API
  description: >-
    Tinybird is a real-time data platform that allows you to ingest, process, and expose
    data through low-latency, high-concurrency APIs. The Tinybird API provides endpoints
    for managing data sources, pipes, queries, tokens, jobs, organizations, events,
    environment variables, and sink pipes.
  version: v0
  contact:
    name: Tinybird Support
    url: https://www.tinybird.co/docs
  x-logo:
    url: https://www.tinybird.co/logo.png
servers:
  - url: https://api.tinybird.co
    description: Europe (Frankfurt) - Default
  - url: https://api.us-east.tinybird.co
    description: US East (Virginia)
  - url: https://api.europe-west2.gcp.tinybird.co
    description: Europe (London)
  - url: https://api.northamerica-northeast2.gcp.tinybird.co
    description: North America (Toronto)
security:
  - bearerAuth: []
tags:
  - name: Data Sources
    description: Manage data source lifecycle and data operations
  - name: Pipes
    description: Manage pipes, API endpoints, and materialized views
  - name: Query
    description: Execute SQL queries against pipes and data sources
  - name: Events
    description: Ingest NDJSON events via HTTP POST
  - name: Tokens
    description: Manage authentication tokens
  - name: Jobs
    description: Retrieve job details and historical records
  - name: Organizations
    description: Handle organization management, members, workspaces, and clusters
  - name: Environment Variables
    description: Create and manage workspace variables
  - name: Sink Pipes
    description: Manage sink pipes with scheduling and triggering
  - name: Analyze
    description: Analyze files to generate data source schemas
paths:
  /v0/datasources/:
    get:
      operationId: listDataSources
      summary: List Data Sources
      description: List all accessible data sources in the workspace.
      tags:
        - Data Sources
      parameters:
        - name: attrs
          in: query
          description: Comma-separated list of attributes to include in response
          schema:
            type: string
      responses:
        '200':
          description: Successful response with list of data sources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createDataSource
      summary: Create Data Source
      description: Create, append, or replace a data source. The mode is determined by the mode parameter.
      tags:
        - Data Sources
      parameters:
        - name: mode
          in: query
          description: Operation mode - create, append, or replace
          schema:
            type: string
            enum: [create, append, replace]
        - name: name
          in: query
          description: Name of the data source
          schema:
            type: string
        - name: format
          in: query
          description: Format of the data being ingested
          schema:
            type: string
            enum: [ndjson, csv, parquet]
      requestBody:
        description: Data to ingest
        content:
          text/plain:
            schema:
              type: string
          multipart/form-data:
            schema:
              type: object
      responses:
        '200':
          description: Data source created or updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSource'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v0/datasources/{name}:
    get:
      operationId: getDataSource
      summary: Get Data Source
      description: Retrieve information and statistics for a specific data source.
      tags:
        - Data Sources
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the data source
          schema:
            type: string
      responses:
        '200':
          description: Data source details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSource'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateDataSource
      summary: Update Data Source
      description: Update data source attributes like name or connector configuration.
      tags:
        - Data Sources
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataSourceUpdate'
      responses:
        '200':
          description: Data source updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSource'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteDataSource
      summary: Delete Data Source
      description: Drop an entire data source and all its data.
      tags:
        - Data Sources
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Data source deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
  /v0/datasources/{name}/alter:
    post:
      operationId: alterDataSource
      summary: Alter Data Source
      description: Modify data source schema, description, or TTL settings.
      tags:
        - Data Sources
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                schema:
                  type: string
                  description: New schema definition
                ttl:
                  type: string
                  description: Time-to-live for data rows
      responses:
        '200':
          description: Data source altered successfully
        '400':
          $ref: '#/components/responses/BadRequest'
  /v0/datasources/{name}/truncate:
    post:
      operationId: truncateDataSource
      summary: Truncate Data Source
      description: Remove all data from a data source while keeping the schema.
      tags:
        - Data Sources
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Data source truncated successfully
  /v0/datasources/{name}/delete:
    post:
      operationId: deleteDataSourceRows
      summary: Delete Data Source Rows
      description: Delete rows matching specific SQL conditions from a data source.
      tags:
        - Data Sources
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                delete_condition:
                  type: string
                  description: SQL WHERE clause condition for rows to delete
      responses:
        '200':
          description: Rows deleted successfully
  /v0/events:
    post:
      operationId: ingestEvents
      summary: Ingest Events
      description: Ingest NDJSON events with a simple HTTP POST request to a data source.
      tags:
        - Events
      parameters:
        - name: name
          in: query
          required: true
          description: Name of the target data source
          schema:
            type: string
        - name: wait
          in: query
          description: Wait for the ingestion to complete before returning
          schema:
            type: boolean
      requestBody:
        required: true
        content:
          application/x-ndjson:
            schema:
              type: string
              description: NDJSON formatted events, one JSON object per line
      responses:
        '202':
          description: Events accepted for ingestion
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v0/pipes/:
    get:
      operationId: listPipes
      summary: List Pipes
      description: List all pipes in the workspace.
      tags:
        - Pipes
      responses:
        '200':
          description: List of pipes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipeList'
    post:
      operationId: createPipe
      summary: Create Pipe
      description: Create a new pipe with SQL transformation nodes.
      tags:
        - Pipes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipeCreate'
      responses:
        '200':
          description: Pipe created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pipe'
  /v0/pipes/{name}:
    get:
      operationId: getPipe
      summary: Get Pipe
      description: Retrieve details about a specific pipe.
      tags:
        - Pipes
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Pipe details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pipe'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updatePipe
      summary: Update Pipe
      description: Update pipe attributes.
      tags:
        - Pipes
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipeUpdate'
      responses:
        '200':
          description: Pipe updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pipe'
    delete:
      operationId: deletePipe
      summary: Delete Pipe
      description: Delete a pipe and all its nodes.
      tags:
        - Pipes
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Pipe deleted successfully
  /v0/pipes/{name}/nodes:
    post:
      operationId: createPipeNode
      summary: Create Pipe Node
      description: Add a new SQL node to an existing pipe.
      tags:
        - Pipes
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipeNodeCreate'
      responses:
        '200':
          description: Node created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipeNode'
  /v0/pipes/{name}/nodes/{nodeId}:
    put:
      operationId: updatePipeNode
      summary: Update Pipe Node
      description: Update an existing pipe node's SQL or description.
      tags:
        - Pipes
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
        - name: nodeId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipeNodeUpdate'
      responses:
        '200':
          description: Node updated successfully
    delete:
      operationId: deletePipeNode
      summary: Delete Pipe Node
      description: Delete a specific node from a pipe.
      tags:
        - Pipes
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
        - name: nodeId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Node deleted successfully
  /v0/pipes/{name}/explain:
    get:
      operationId: explainPipe
      summary: Explain Pipe Query
      description: Get the query execution plan for a pipe.
      tags:
        - Pipes
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Query execution plan
          content:
            application/json:
              schema:
                type: object
  /v0/sql:
    get:
      operationId: querySql
      summary: Execute SQL Query (GET)
      description: Execute a SQL query using the Tinybird query engine via GET request.
      tags:
        - Query
      parameters:
        - name: q
          in: query
          required: true
          description: SQL query string to execute
          schema:
            type: string
        - name: format
          in: query
          description: Output format
          schema:
            type: string
            enum: [JSON, CSV, NDJSON, Parquet]
      responses:
        '200':
          description: Query results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
    post:
      operationId: querySqlPost
      summary: Execute SQL Query (POST)
      description: Execute a SQL query using the Tinybird query engine via POST request, supporting templated queries.
      tags:
        - Query
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - q
              properties:
                q:
                  type: string
                  description: SQL query string
                format:
                  type: string
                  enum: [JSON, CSV, NDJSON, Parquet]
      responses:
        '200':
          description: Query results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
  /v0/tokens/:
    get:
      operationId: listTokens
      summary: List Tokens
      description: Retrieve all workspace static tokens.
      tags:
        - Tokens
      responses:
        '200':
          description: List of tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenList'
    post:
      operationId: createToken
      summary: Create Token
      description: Create a new static or JWT token with specified scopes and permissions.
      tags:
        - Tokens
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenCreate'
      responses:
        '200':
          description: Token created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
  /v0/tokens/{tokenId}:
    get:
      operationId: getToken
      summary: Get Token
      description: Fetch information about a particular static token.
      tags:
        - Tokens
      parameters:
        - name: tokenId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Token details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateToken
      summary: Update Token
      description: Modify an existing static token's properties and scopes.
      tags:
        - Tokens
      parameters:
        - name: tokenId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenUpdate'
      responses:
        '200':
          description: Token updated successfully
    delete:
      operationId: deleteToken
      summary: Delete Token
      description: Remove a static token, immediately revoking its access.
      tags:
        - Tokens
      parameters:
        - name: tokenId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Token deleted successfully
  /v0/tokens/{tokenId}/refresh:
    post:
      operationId: refreshToken
      summary: Refresh Token
      description: Refresh a static token's value while preserving all other attributes.
      tags:
        - Tokens
      parameters:
        - name: tokenId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Token refreshed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
  /v0/jobs/:
    get:
      operationId: listJobs
      summary: List Jobs
      description: Retrieve job history from the past 48 hours or last 100 jobs.
      tags:
        - Jobs
      parameters:
        - name: status
          in: query
          description: Filter jobs by status
          schema:
            type: string
            enum: [done, error, working, waiting]
        - name: kind
          in: query
          description: Filter jobs by type
          schema:
            type: string
      responses:
        '200':
          description: List of jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobList'
  /v0/jobs/{jobId}:
    get:
      operationId: getJob
      summary: Get Job
      description: Retrieve details about a specific job.
      tags:
        - Jobs
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '404':
          $ref: '#/components/responses/NotFound'
  /v0/analyze:
    post:
      operationId: analyzeFile
      summary: Analyze File Schema
      description: Analyze a given NDJSON, CSV, or Parquet file to generate a Tinybird Data Source schema.
      tags:
        - Analyze
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: NDJSON, CSV, or Parquet file to analyze
      responses:
        '200':
          description: Generated schema
          content:
            application/json:
              schema:
                type: object
                properties:
                  schema:
                    type: string
  /v0/env_vars:
    get:
      operationId: listEnvironmentVariables
      summary: List Environment Variables
      description: List all environment variables in the workspace.
      tags:
        - Environment Variables
      responses:
        '200':
          description: List of environment variables
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvVarList'
    post:
      operationId: createEnvironmentVariable
      summary: Create Environment Variable
      description: Create a new environment variable for use within pipes.
      tags:
        - Environment Variables
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvVarCreate'
      responses:
        '200':
          description: Environment variable created
  /v0/env_vars/{name}:
    put:
      operationId: updateEnvironmentVariable
      summary: Update Environment Variable
      description: Update an existing environment variable's value.
      tags:
        - Environment Variables
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvVarUpdate'
      responses:
        '200':
          description: Environment variable updated
    delete:
      operationId: deleteEnvironmentVariable
      summary: Delete Environment Variable
      description: Delete an environment variable from the workspace.
      tags:
        - Environment Variables
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Environment variable deleted
  /v0/sink_pipes:
    get:
      operationId: listSinkPipes
      summary: List Sink Pipes
      description: List all sink pipes in the workspace.
      tags:
        - Sink Pipes
      responses:
        '200':
          description: List of sink pipes
          content:
            application/json:
              schema:
                type: object
    post:
      operationId: createSinkPipe
      summary: Create Sink Pipe
      description: Create a new sink pipe with scheduling and triggering capabilities.
      tags:
        - Sink Pipes
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                schedule:
                  type: string
                  description: Cron expression for scheduling
      responses:
        '200':
          description: Sink pipe created
  /v0/organizations:
    get:
      operationId: listOrganizations
      summary: List Organizations
      description: List all organizations the authenticated user belongs to.
      tags:
        - Organizations
      responses:
        '200':
          description: List of organizations
          content:
            application/json:
              schema:
                type: object
  /v0/organizations/{orgId}/members:
    get:
      operationId: listOrganizationMembers
      summary: List Organization Members
      description: List all members in an organization.
      tags:
        - Organizations
      parameters:
        - name: orgId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of organization members
          content:
            application/json:
              schema:
                type: object
  /v0/organizations/{orgId}/workspaces:
    get:
      operationId: listOrganizationWorkspaces
      summary: List Organization Workspaces
      description: List all workspaces in an organization.
      tags:
        - Organizations
      parameters:
        - name: orgId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of workspaces
          content:
            application/json:
              schema:
                type: object
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Tinybird authentication token
  responses:
    Unauthorized:
      description: Unauthorized - invalid or missing token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        documentation:
          type: string
    DataSource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        cluster:
          type: string
        tags:
          type: object
        schema:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        row_count:
          type: integer
        disk_bytes:
          type: integer
        replicated:
          type: boolean
        ttl_expression:
          type: string
    DataSourceList:
      type: object
      properties:
        datasources:
          type: array
          items:
            $ref: '#/components/schemas/DataSource'
    DataSourceUpdate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    Pipe:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/PipeNode'
        type:
          type: string
          enum: [standard, materialized, sink, copy]
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    PipeList:
      type: object
      properties:
        pipes:
          type: array
          items:
            $ref: '#/components/schemas/Pipe'
    PipeCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/PipeNodeCreate'
    PipeUpdate:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    PipeNode:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        sql:
          type: string
        created_at:
          type: string
          format: date-time
    PipeNodeCreate:
      type: object
      required:
        - sql
      properties:
        name:
          type: string
        sql:
          type: string
        description:
          type: string
    PipeNodeUpdate:
      type: object
      properties:
        sql:
          type: string
        description:
          type: string
    QueryResponse:
      type: object
      properties:
        meta:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
        data:
          type: array
          items:
            type: object
        rows:
          type: integer
        statistics:
          type: object
          properties:
            elapsed:
              type: number
            rows_read:
              type: integer
            bytes_read:
              type: integer
    Token:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        token:
          type: string
        scopes:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              resource:
                type: string
        created_at:
          type: string
          format: date-time
    TokenList:
      type: object
      properties:
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/Token'
    TokenCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        scopes:
          type: array
          items:
            type: object
    TokenUpdate:
      type: object
      properties:
        name:
          type: string
        scopes:
          type: array
          items:
            type: object
    Job:
      type: object
      properties:
        id:
          type: string
        kind:
          type: string
        status:
          type: string
          enum: [done, error, working, waiting]
        progress:
          type: number
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        error:
          type: string
    JobList:
      type: object
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Job'
    IngestResponse:
      type: object
      properties:
        successful_rows:
          type: integer
        quarantined_rows:
          type: integer
    EnvVar:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
    EnvVarList:
      type: object
      properties:
        env_vars:
          type: array
          items:
            $ref: '#/components/schemas/EnvVar'
    EnvVarCreate:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
        value:
          type: string
    EnvVarUpdate:
      type: object
      properties:
        value:
          type: string