openapi: 3.1.0
info:
  title: Dremio Intelligent Lakehouse REST API
  version: "3.0.0"
  description: >-
    Best-effort OpenAPI for Dremio's v3 REST API covering the catalog, jobs,
    reflections, sources, scripts, personal access tokens, and roles. Auth uses
    a bearer access token (OAuth or Personal Access Token).
  contact:
    name: API Evangelist
    email: kin@apievangelist.com
    url: https://docs.dremio.com/
servers:
  - url: https://{hostname}/api/v3
    description: A Dremio server (self-hosted; substitute your hostname)
    variables:
      hostname:
        default: dremio.example.com
security:
  - bearerAuth: []
tags:
  - name: Authentication
  - name: Catalog
  - name: Jobs
  - name: Reflections
  - name: Sources
  - name: Scripts
  - name: PAT
  - name: Roles
paths:
  /apiv2/login:
    post:
      tags: [Authentication]
      summary: Authenticate with username and password and receive a token
      operationId: login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userName: { type: string }
                password: { type: string }
      responses:
        "200": { description: Authentication token returned }
  /catalog:
    get:
      tags: [Catalog]
      summary: Retrieve the catalog for the current Dremio instance
      operationId: listCatalog
      parameters:
        - name: include
          in: query
          schema: { type: string, enum: [permissions, datasetCount] }
      responses:
        "200": { description: Catalog entries }
  /catalog/{id}:
    parameters:
      - $ref: "#/components/parameters/CatalogId"
    get:
      tags: [Catalog]
      summary: Get a catalog entity by ID
      operationId: getCatalogEntity
      responses:
        "200": { description: Catalog entity }
    delete:
      tags: [Catalog]
      summary: Delete a catalog entity
      operationId: deleteCatalogEntity
      responses:
        "204": { description: Deleted }
  /catalog/by-path/{path}:
    parameters:
      - name: path
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Catalog]
      summary: Get a catalog entity by path
      operationId: getCatalogByPath
      responses:
        "200": { description: Catalog entity }
  /job:
    post:
      tags: [Jobs]
      summary: Submit a SQL query as a job
      operationId: submitJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sql: { type: string }
                context: { type: array, items: { type: string } }
      responses:
        "200": { description: Job submitted; returns job id }
  /job/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Jobs]
      summary: Get job status
      operationId: getJob
      responses:
        "200": { description: Job status }
  /job/{id}/results:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Jobs]
      summary: Fetch results for a completed job
      operationId: getJobResults
      responses:
        "200": { description: Job results }
  /job/{id}/cancel:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [Jobs]
      summary: Cancel a running job
      operationId: cancelJob
      responses:
        "204": { description: Cancelled }
  /reflection:
    get:
      tags: [Reflections]
      summary: List reflections
      operationId: listReflections
      responses:
        "200": { description: Reflections }
    post:
      tags: [Reflections]
      summary: Create a reflection
      operationId: createReflection
      responses:
        "201": { description: Reflection created }
  /reflection/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Reflections]
      summary: Get a reflection
      operationId: getReflection
      responses:
        "200": { description: Reflection }
    put:
      tags: [Reflections]
      summary: Update a reflection
      operationId: updateReflection
      responses:
        "200": { description: Updated }
    delete:
      tags: [Reflections]
      summary: Delete a reflection
      operationId: deleteReflection
      responses:
        "204": { description: Deleted }
  /source:
    get:
      tags: [Sources]
      summary: List sources
      operationId: listSources
      responses:
        "200": { description: Sources }
  /scripts:
    get:
      tags: [Scripts]
      summary: List SQL scripts
      operationId: listScripts
      responses:
        "200": { description: Scripts }
    post:
      tags: [Scripts]
      summary: Create a SQL script
      operationId: createScript
      responses:
        "201": { description: Script created }
  /users/{userId}/tokens:
    parameters:
      - name: userId
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [PAT]
      summary: List personal access tokens for a user
      operationId: listUserTokens
      responses:
        "200": { description: Tokens }
    post:
      tags: [PAT]
      summary: Create a personal access token
      operationId: createUserToken
      responses:
        "201": { description: Token created }
  /roles:
    get:
      tags: [Roles]
      summary: List roles
      operationId: listRoles
      responses:
        "200": { description: Roles }
components:
  parameters:
    CatalogId:
      name: id
      in: path
      required: true
      schema: { type: string }
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth access token or Personal Access Token