openapi: 3.1.0
info:
  title: QuestDB HTTP REST API
  version: "1.0.0"
  description: >-
    HTTP REST endpoints exposed by QuestDB on the default HTTP port (9000)
    for SQL execution, CSV import/export, table existence checks, runtime
    metrics, and the InfluxDB Line Protocol HTTP ingestion endpoint.
    Authentication is unauthenticated by default in the open-source build;
    QuestDB Enterprise supports HTTP Basic Authentication and TLS.
  contact:
    name: QuestDB Documentation
    url: https://questdb.com/docs/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: http://{host}:{port}
    description: QuestDB HTTP server
    variables:
      host:
        default: localhost
        description: QuestDB host
      port:
        default: "9000"
        description: QuestDB HTTP port
security:
  - {}
  - basicAuth: []
paths:
  /exec:
    get:
      summary: Execute a SQL statement
      description: >-
        Compiles and executes a SQL statement passed as the `query`
        URL parameter and returns JSON-formatted results.
      operationId: execQuery
      parameters:
        - name: query
          in: query
          required: true
          description: SQL statement to execute (URL-encoded).
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Optional row range, for example `0,1000`.
          schema:
            type: string
        - name: count
          in: query
          required: false
          description: Include total row count in the response.
          schema:
            type: boolean
        - name: nm
          in: query
          required: false
          description: Skip metadata in the response when true.
          schema:
            type: boolean
        - name: timings
          in: query
          required: false
          description: Include execution timings in the response.
          schema:
            type: boolean
      responses:
        "200":
          description: Query executed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecResponse'
        "400":
          description: Invalid query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /imp:
    post:
      summary: Import a CSV file
      description: >-
        Imports a CSV file into a QuestDB table using a multipart form upload.
      operationId: importCsv
      parameters:
        - name: name
          in: query
          required: false
          description: Target table name (defaults to the uploaded file name).
          schema:
            type: string
        - name: overwrite
          in: query
          required: false
          description: When true, drop and recreate the target table.
          schema:
            type: boolean
        - name: forceHeader
          in: query
          required: false
          description: Treat the first row as a header row.
          schema:
            type: boolean
        - name: timestamp
          in: query
          required: false
          description: Name of the designated timestamp column.
          schema:
            type: string
        - name: partitionBy
          in: query
          required: false
          description: Partition strategy (NONE, HOUR, DAY, WEEK, MONTH, YEAR).
          schema:
            type: string
            enum: [NONE, HOUR, DAY, WEEK, MONTH, YEAR]
        - name: fmt
          in: query
          required: false
          description: Response format, for example `json` or `tabular`.
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                schema:
                  type: string
                  description: Optional JSON schema describing column types.
                data:
                  type: string
                  format: binary
                  description: CSV file payload.
      responses:
        "200":
          description: Import completed.
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                type: object
        "400":
          description: Invalid CSV or request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /exp:
    get:
      summary: Export query results as CSV
      description: >-
        Executes a SQL statement and streams the result set as CSV.
      operationId: exportCsv
      parameters:
        - name: query
          in: query
          required: true
          description: SQL statement to execute (URL-encoded).
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Optional row range, for example `0,1000`.
          schema:
            type: string
      responses:
        "200":
          description: CSV export stream.
          content:
            text/csv:
              schema:
                type: string
        "400":
          description: Invalid query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /chk:
    get:
      summary: Check whether a table exists
      description: >-
        Returns whether the supplied table exists in the database.
      operationId: checkTable
      parameters:
        - name: f
          in: query
          required: false
          description: Response format, typically `json`.
          schema:
            type: string
            example: json
        - name: j
          in: query
          required: true
          description: Table name to check.
          schema:
            type: string
      responses:
        "200":
          description: Existence response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: "`Exists` or `Does not exist`."
  /write:
    post:
      summary: Ingest data via InfluxDB Line Protocol over HTTP
      description: >-
        Accepts InfluxDB Line Protocol payloads for high-throughput
        time-series ingestion. Served on the same HTTP port as the REST API.
      operationId: ilpWrite
      parameters:
        - name: precision
          in: query
          required: false
          description: Timestamp precision (n, u, ms, s).
          schema:
            type: string
            enum: [n, u, ms, s]
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              description: Newline-delimited InfluxDB Line Protocol records.
      responses:
        "204":
          description: Ingestion accepted.
        "400":
          description: Malformed line protocol payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /settings:
    get:
      summary: Return effective runtime settings
      description: Returns the current server runtime settings as JSON.
      operationId: getSettings
      responses:
        "200":
          description: Runtime settings.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication (QuestDB Enterprise).
  schemas:
    ExecResponse:
      type: object
      properties:
        query:
          type: string
        columns:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
        dataset:
          type: array
          items:
            type: array
            items: {}
        count:
          type: integer
        timings:
          type: object
    Error:
      type: object
      properties:
        query:
          type: string
        error:
          type: string
        position:
          type: integer