Apache Druid

Apache Druid REST API

Druid exposes REST APIs for Druid SQL (POST /druid/v2/sql), native JSON queries (POST /druid/v2), batch and streaming data ingestion tasks, supervisor management for Kafka/Kinesis ingestion, data segment management, coordinator and overlord operations, process status, and dynamic configuration. A JDBC driver is also available for SQL access via JDBC clients.

Documentation GitHub OpenAPI

Documentation

https://druid.apache.org/docs/latest/api-reference/

https://druid.apache.org/docs/latest/tutorials/tutorial-batch-hadoop

https://druid.apache.org/docs/latest/api-reference/

Specifications

https://raw.githubusercontent.com/api-evangelist/apache-druid/refs/heads/main/openapi/apache-druid-openapi.yml

SDKs

GitHubRepository

https://github.com/apache/druid

JDBC Driver (Maven)

pydruid Python Client

Examples

https://raw.githubusercontent.com/api-evangelist/apache-druid/refs/heads/main/examples/apache-druid-ingestion-task-example.json

https://raw.githubusercontent.com/api-evangelist/apache-druid/refs/heads/main/examples/apache-druid-sql-query-request-example.json

https://raw.githubusercontent.com/api-evangelist/apache-druid/refs/heads/main/examples/apache-druid-sql-query-response-example.json

https://raw.githubusercontent.com/api-evangelist/apache-druid/refs/heads/main/examples/apache-druid-supervisor-example.json

Schemas & Data

Sql Query Request

Sql Query Response

https://raw.githubusercontent.com/api-evangelist/apache-druid/refs/heads/main/json-structure/apache-druid-ingestion-task-structure.json

https://raw.githubusercontent.com/api-evangelist/apache-druid/refs/heads/main/json-structure/apache-druid-sql-query-request-structure.json

https://raw.githubusercontent.com/api-evangelist/apache-druid/refs/heads/main/json-structure/apache-druid-sql-query-response-structure.json

https://raw.githubusercontent.com/api-evangelist/apache-druid/refs/heads/main/json-structure/apache-druid-supervisor-structure.json

Other Resources

Kubernetes Operator

https://raw.githubusercontent.com/api-evangelist/apache-druid/refs/heads/main/json-ld/apache-druid-context.jsonld

OpenAPI Specification

openapi: 3.1.0
info:
  title: Apache Druid REST API
  version: "1.0"
  description: >-
    Minimal OpenAPI for Apache Druid SQL and Data Management HTTP endpoints,
    covering SQL queries, asynchronous statement queries, and segment/datasource
    management via the indexer and coordinator.
servers:
  - url: http://localhost:8888
    description: Druid Router (default)
x-generated-from: https://druid.apache.org/docs/latest/api-reference/
x-generated-by: claude-crawl-2026-05-08
paths:
  /druid/v2/sql:
    post:
      summary: Submit a Druid SQL query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Query results
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
  /druid/v2/sql/{sqlQueryId}:
    delete:
      summary: Cancel a SQL query
      parameters:
        - name: sqlQueryId
          in: path
          required: true
          schema:
            type: string
      responses:
        "202":
          description: Cancellation accepted
  /druid/v2/sql/statements:
    post:
      summary: Submit an asynchronous SQL statement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Statement accepted
          content:
            application/json:
              schema:
                type: object
  /druid/v2/sql/statements/{queryId}:
    get:
      summary: Get statement status
      parameters:
        - name: queryId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Statement status
          content:
            application/json:
              schema:
                type: object
    delete:
      summary: Cancel an asynchronous statement
      parameters:
        - name: queryId
          in: path
          required: true
          schema:
            type: string
      responses:
        "202":
          description: Cancellation accepted
  /druid/v2/sql/statements/{queryId}/results:
    get:
      summary: Fetch statement results
      parameters:
        - name: queryId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Results
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
  /druid/indexer/v1/datasources/{datasource}:
    post:
      summary: Mark all segments of a datasource as used
      parameters:
        - name: datasource
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
    delete:
      summary: Mark all segments of a datasource as unused
      parameters:
        - name: datasource
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
  /druid/indexer/v1/datasources/{datasource}/markUsed:
    post:
      summary: Mark segments matching criteria as used
      parameters:
        - name: datasource
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: OK
  /druid/indexer/v1/datasources/{datasource}/markUnused:
    post:
      summary: Mark segments matching criteria as unused
      parameters:
        - name: datasource
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: OK
  /druid/indexer/v1/datasources/{datasource}/segments/{segmentId}:
    post:
      summary: Mark a specific segment as used
      parameters:
        - name: datasource
          in: path
          required: true
          schema:
            type: string
        - name: segmentId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
    delete:
      summary: Mark a specific segment as unused
      parameters:
        - name: datasource
          in: path
          required: true
          schema:
            type: string
        - name: segmentId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
  /druid/coordinator/v1/datasources/{datasource}/intervals/{interval}:
    delete:
      summary: Mark segments in an interval as unused
      parameters:
        - name: datasource
          in: path
          required: true
          schema:
            type: string
        - name: interval
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
components:
  schemas:
    GenericObject:
      type: object