dblab_openapi.yaml

# OpenAPI spec for DBLab API
# Useful links:
# - validate and test: https://editor.swagger.io/
# - official reference location for this API: https://dblab.readme.io/
# - GitHub (give us a ⭐️): https://github.com/postgres-ai/database-lab-engine

openapi: 3.0.1
info:
  title: DBLab API
  description: This page provides the OpenAPI specification for the Database Lab (DBLab)
    API, previously recognized as the DLE API (Database Lab Engine API).
  contact:
    name: DBLab API Support
    url: https://postgres.ai/contact
    email: api@postgres.ai
  license:
    name: Apache 2.0
    url: https://github.com/postgres-ai/database-lab-engine/blob/dle-4-0/LICENSE
  version: 4.1.0
externalDocs:
  description: DBLab Docs
  url: https://postgres.ai/docs/database-lab

servers:
  - url: "https://demo.dblab.dev/api"
    description: "DBLab demo server (with DB branching support); token: 'demo-token'"
    x-examples:
      Verification-Token: "demo-token"
  - url: "https://demo.aws.postgres.ai:446/api"
    description: "DBLab 3.x demo server; token: 'demo-token'"
    x-examples:
      Verification-Token: "demo-token"
  - url: "{scheme}://{host}:{port}/{basePath}"
    description: "Any DBLab accessed locally / through SSH port forwarding"
    variables:
      scheme:
        enum:
          - "https"
          - "http"
        default: "http"
        description: "'http' for local connections and SSH port forwarding;
          'https' for everything else."
      host:
        default: "localhost"
        description: "where DBLab server is installed. Use 'localhost' to work locally
          or when SSH port forwarding is used."
      port:
        default: "2346"
        description: "Port to access DBLab UI or API. Originally, '2345' is used for
          direct work with API and '2346' – with UI. However, with UI, API is also available,
          at ':2346/api'."
      basePath:
        default: "api"
        description: "basePath value to access API. Use empty when working with API port
          (2345 by default), or '/api' when working with UI port ('2346' by default)."
    x-examples:
      Verification-Token: "custom_example_token"

tags:
- name: DBLab
  description: "DBLab API Reference – database branching, instant cloning, and more.
    DBLab CLI and UI rely on DBLab API."
  externalDocs:
    description: "DBLab Docs - tutorials, howtos, references."
    url: https://postgres.ai/docs/reference-guides/database-lab-engine-api-reference

paths:
  /status:
    get:
      tags:
      - Instance
      summary: DBLab instance status and detailed information
      description: "Retrieves detailed information about the DBLab instance: status, version,
        clones, snapshots, etc."
      operationId: status
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      responses:
        200:
          description: Returned detailed information about the DBLab instance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
              example:
                status:
                  code: OK
                  message: Instance is ready
                engine:
                  version: v4.0.0-alpha.5-20230516-0224
                  edition: standard
                  billingActive: true
                  instanceID: chhfqfcnvrvc73d0lij0
                  startedAt: '2023-05-16T03:50:19Z'
                  telemetry: true
                  disableConfigModification: false
                pools:
                - name: dblab_pool/dataset_1
                  mode: zfs
                  dataStateAt: ''
                  status: empty
                  cloneList: []
                  fileSystem:
                    mode: zfs
                    size: 30685528064
                    free: 30685282816
                    used: 245248
                    dataSize: 12288
                    usedBySnapshots: 0
                    usedByClones: 219648
                    compressRatio: 1
                - name: dblab_pool/dataset_2
                  mode: zfs
                  dataStateAt: ''
                  status: empty
                  cloneList: []
                  fileSystem:
                    mode: zfs
                    size: 30685528064
                    free: 30685282816
                    used: 245248
                    dataSize: 12288
                    usedBySnapshots: 0
                    usedByClones: 219648
                    compressRatio: 1
                - name: dblab_pool/dataset_3
                  mode: zfs
                  dataStateAt: ''
                  status: empty
                  cloneList: []
                  fileSystem:
                    mode: zfs
                    size: 30685528064
                    free: 30685282816
                    used: 245248
                    dataSize: 12288
                    usedBySnapshots: 0
                    usedByClones: 219648
                    compressRatio: 1
                cloning:
                  expectedCloningTime: 0
                  numClones: 0
                  clones: []
                retrieving:
                  mode: logical
                  status: pending
                  lastRefresh:
                  nextRefresh:
                  alerts: {}
                  activity:
                provisioner:
                  dockerImage: postgresai/extended-postgres:15
                  containerConfig:
                    shm-size: 1gb
                synchronization:
                  status:
                    code: Not available
                    message: ''
                  lastReplayedLsn: ''
                  lastReplayedLsnAt: ''
                  replicationLag: 0
                  replicationUptime: 0
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
  /snapshots:
    get:
      tags:
      - Snapshots
      summary: List all snapshots
      description: Return a list of all available snapshots.
      operationId: snapshots
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      - name: branch
        in: query
        required: false
        schema:
          type: string
      responses:
        200:
          description: Returned a list of snapshots
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Snapshot'
              example:
                - id: dblab_pool/dataset_2/nik-test-branch/20230509212711@20230509212711
                  createdAt: '2023-05-09T21:27:11Z'
                  dataStateAt: '2023-05-09T21:27:11Z'
                  physicalSize: 0
                  logicalSize: 11518021632
                  pool: dblab_pool/dataset_2
                  numClones: 1
                - id: dblab_pool/dataset_2/nik-test-branch/20230307171959@20230307171959
                  createdAt: '2023-03-07T17:19:59Z'
                  dataStateAt: '2023-03-07T17:19:59Z'
                  physicalSize: 151552
                  logicalSize: 11518015488
                  pool: dblab_pool/dataset_2
                  numClones: 1
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
  /full-refresh:
    post:
      tags:
        - Instance
      summary: Trigger full data refresh
      description: "Initiates a full data refresh."
      operationId: refresh
      parameters:
        - name: Verification-Token
          in: header
          required: true
          schema:
            type: string
      responses:
        200:
          description: Full refresh has been initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FullRefresh'
              example:
                status: OK
                message: Full refresh started
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
  /snapshot:
    post:
      tags:
        - Snapshots
      summary: Create a snapshot
      description: "Create a new snapshot from the current state of the selected pool.
        This snapshot can later be used to create clones or new branches."
      parameters:
        - name: Verification-Token
          in: header
          required: true
          schema:
            type: string
      requestBody:
        description: "Optional parameters for snapshot creation.
          If no pool name is provided, the first available pool is used."
        content:
          '*/*':
            schema:
              type: object
              properties:
                poolName:
                  type: string
                  description: Name of the pool to create snapshot in.
        required: false
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Snapshot'
        400:
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: body
  /snapshot/{id}:
    delete:
      tags:
        - Snapshots
      summary: Delete a snapshot
      description: "Permanently delete the specified snapshot.
        If the snapshot has dependent clones or datasets, `force=true` can be provided as a query parameter."
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the snapshot to delete.
          schema:
            type: string
            pattern: '.*'
        - name: force
          in: query
          required: false
          description: Force deletion even if dependent clones or datasets exist.
          schema:
            type: boolean
        - name: Verification-Token
          in: header
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ResponseStatus'
        400:
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
  /clones:
    get:
      tags:
      - Clones
      summary: List all clones
      description: Return a list of all available clones (database endpoints).
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      responses:
        200:
          description: Returned a list of all available clones
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Clone'
              example:
                - id: test-clone-2
                  snapshot:
                    id: dblab_pool/dataset_2/nik-test-branch/20230509212711@20230509212711
                    createdAt: '2023-05-09T21:27:11Z'
                    dataStateAt: '2023-05-09T21:27:11Z'
                    physicalSize: 120832
                    logicalSize: 11518021632
                    pool: dblab_pool/dataset_2
                    numClones: 3
                  branch: ''
                  protected: false
                  deleteAt:
                  createdAt: '2023-05-16T06:12:52Z'
                  status:
                    code: OK
                    message: Clone is ready to accept Postgres connections.
                  db:
                    connStr: host=branching.aws.postgres.ai port=6005 user=tester dbname=postgres
                    host: branching.aws.postgres.ai
                    port: '6005'
                    username: tester
                    password: ''
                    dbName: postgres
                  metadata:
                    cloneDiffSize: 484352
                    logicalSize: 11518029312
                    cloningTime: 1.5250661829999999
                    maxIdleMinutes: 120
                - id: test-clone
                  snapshot:
                    id: dblab_pool/dataset_2/nik-test-branch/20230509212711@20230509212711
                    createdAt: '2023-05-09T21:27:11Z'
                    dataStateAt: '2023-05-09T21:27:11Z'
                    physicalSize: 120832
                    logicalSize: 11518021632
                    pool: dblab_pool/dataset_2
                    numClones: 3
                  branch: ''
                  protected: false
                  deleteAt:
                  createdAt: '2023-05-16T06:12:30Z'
                  status:
                    code: OK
                    message: Clone is ready to accept Postgres connections.
                  db:
                    connStr: host=branching.aws.postgres.ai port=6004 user=tester dbname=postgres
                    host: branching.aws.postgres.ai
                    port: '6004'
                    username: tester
                    password: ''
                    dbName: postgres
                  metadata:
                    cloneDiffSize: 486400
                    logicalSize: 11518030336
                    cloningTime: 1.57552338
                    maxIdleMinutes: 120
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
  /clone:
    post:
      tags:
      - Clones
      summary: Create a clone
      operationId: createClone
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      requestBody:
        description: Clone object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateClone'
        required: true
      responses:
        201:
          description: Created a new clone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Clone'
              example:
                id: test-clone-2
                snapshot:
                  id: dblab_pool/dataset_2/nik-test-branch/20230509212711@20230509212711
                  createdAt: '2023-05-09T21:27:11Z'
                  dataStateAt: '2023-05-09T21:27:11Z'
                  physicalSize: 120832
                  logicalSize: 11518021632
                  pool: dblab_pool/dataset_2
                  numClones: 3
                branch: ''
                protected: false
                deleteAt:
                createdAt: '2023-05-16T06:12:52Z'
                status:
                  code: CREATING
                  message: Clone is being created.
                db:
                  connStr: ''
                  host: ''
                  port: ''
                  username: tester
                  password: ''
                  dbName: postgres
                metadata:
                  cloneDiffSize: 0
                  logicalSize: 0
                  cloningTime: 0
                  maxIdleMinutes: 0
        400:
          description: Returned an error caused by invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: "BAD_REQUEST"
                message: "clone with such ID already exists"
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
      x-codegen-request-body-name: body
  /clone/{id}:
    get:
      tags:
      - Clones
      summary: Retrieve a clone
      description: Retrieves the information for the specified clone.
      operationId: getClone
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Clone ID
        required: true
        schema:
          type: string
      responses:
        200:
          description: Returned detailed information for the specified clone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Clone'
              example:
                id: test-clone
                snapshot:
                  id: dblab_pool/dataset_2/nik-test-branch/20230509212711@20230509212711
                  createdAt: '2023-05-09T21:27:11Z'
                  dataStateAt: '2023-05-09T21:27:11Z'
                  physicalSize: 120832
                  logicalSize: 11518021632
                  pool: dblab_pool/dataset_2
                  numClones: 3
                branch: ''
                protected: false
                deleteAt:
                createdAt: '2023-05-16T06:12:30Z'
                status:
                  code: OK
                  message: Clone is ready to accept Postgres connections.
                db:
                  connStr: host=branching.aws.postgres.ai port=6004 user=tester dbname=postgres
                  host: branching.aws.postgres.ai
                  port: '6004'
                  username: tester
                  password: ''
                  dbName: postgres
                metadata:
                  cloneDiffSize: 486400
                  logicalSize: 11518030336
                  cloningTime: 1.57552338
                  maxIdleMinutes: 120
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: NOT_FOUND
                message: Requested object does not exist. Specify your request.
    delete:
      tags:
      - Clones
      summary: Delete a clone
      description: Permanently delete the specified clone. It cannot be undone.
      operationId: deleteClone
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Clone ID
        required: true
        schema:
          type: string
      responses:
        200:
          description: Successfully deleted the specified clone
          content:
            application/json:
              example:
                "OK"
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: NOT_FOUND
                message: Requested object does not exist. Specify your request.
    patch:
      tags:
      - Clones
      summary: Update a clone
      description: "Updates the specified clone by setting the values of the parameters passed.
        Currently, only one paramater is supported: 'protected'."
      operationId: updateClone
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Clone ID
        required: true
        schema:
          type: string
      requestBody:
        description: Clone object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateClone'
        required: true
      responses:
        200:
          description: Successfully updated the specified clone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Clone'
              example:
                id: test-clone-2
                snapshot:
                  id: dblab_pool/dataset_2/nik-test-branch/20230509212711@20230509212711
                  createdAt: '2023-05-09T21:27:11Z'
                  dataStateAt: '2023-05-09T21:27:11Z'
                  physicalSize: 120832
                  logicalSize: 11518021632
                  pool: dblab_pool/dataset_2
                  numClones: 2
                branch: ''
                protected: true
                deleteAt:
                createdAt: '2023-05-16T06:12:52Z'
                status:
                  code: OK
                  message: Clone is ready to accept Postgres connections.
                db:
                  connStr: host=branching.aws.postgres.ai port=6005 user=tester dbname=postgres
                  host: branching.aws.postgres.ai
                  port: '6005'
                  username: tester
                  password: ''
                  dbName: postgres
                metadata:
                  cloneDiffSize: 561664
                  logicalSize: 11518030336
                  cloningTime: 1.5250661829999999
                  maxIdleMinutes: 120
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
        #404:  # TODO: fix it in engine (currently returns 500)
        #  description: Not found
        #  content:
        #    application/json:
        #      schema:
        #        $ref: '#/components/schemas/Error'
        #      example:
        #        code: NOT_FOUND
        #        message: Requested object does not exist. Specify your request.
      x-codegen-request-body-name: body
  /clone/{id}/reset:
    post:
      tags:
      - Clones
      summary: Reset a clone
      description: "Reset the specified clone to a previously stored state.
        This can be done by specifying a particular snapshot ID or using the 'latest' flag.
        All changes made after the snapshot are discarded during the reset, unless those
        changes were preserved in a snapshot. All database connections will be reset,
        requiring users and applications to reconnect. The duration of the reset operation
        is comparable to the creation of a new clone. However, unlike creating a new clone,
        the reset operation retains the database credentials and does not change the port.
        Consequently, users and applications can continue to use the same database credentials
        post-reset, though reconnection will be necessary. Please note that any unsaved changes
        will be irretrievably lost during this operation, so ensure necessary data is backed up
        in a snapshot prior to resetting the clone."
      operationId: resetClone
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Clone ID
        required: true
        schema:
          type: string
      requestBody:
        description: Reset object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetClone'
        required: false
      responses:
        200:
          description: Successfully reset the state of the specified clone
          content:
            application/json:
              example:
                "OK"
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
        #404:    # TODO: fix it in engine (currently returns 500)
        #  description: Not found
        #  content:
        #    application/json:
        #      schema:
        #        $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: body
  /branches:
    get:
      tags:
      - Branches
      summary: List all branches
      description: Return a list of all available branches (named pointers to snapshots).
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      responses:
        200:
          description: Returned a list of all available branches
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Branch'
              example:
                - name: my-1
                  parent: main
                  dataStateAt: '20230224202652'
                  snapshotID: dblab_pool/dataset_2/main/20230224202652@20230224202652
                - name: nik-test-branch
                  parent: "-"
                  dataStateAt: '20230509212711'
                  snapshotID: dblab_pool/dataset_2/nik-test-branch/20230509212711@20230509212711
                - name: main
                  parent: "-"
                  dataStateAt: '20230224202652'
                  snapshotID: dblab_pool/dataset_2/main/20230224202652@20230224202652
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
  /branch/snapshot/{id}:
    get:
      tags:
        - Snapshots
      summary: Retrieve a snapshot
      description: Retrieves the information for the specified snapshot.
      parameters:
      - name: id
        in: path
        description: ID of the branch snapshot
        required: true
        schema:
          type: string
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SnapshotDetails'
        400:
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
  /branch:
    post:
      tags:
      - Branches
      summary: Create a branch
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      requestBody:
        content:
          '*/*':
            schema:
              type: object
              properties:
                branchName:
                  type: string
                  description: The name of the new branch.
                baseBranch:
                  type: string
                  description: "The name of parent branch user to create a new branch.
                    Must not be specified if 'snapshotID' is specified."
                snapshotID:
                  type: string
                  description: "The ID of the snapshot used to create a new branch.
                    Must not be specified if 'baseBranch' is specified."
        required: true
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
                properties:
                  name:
                    type: string
        400:
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: body
  /branch/snapshot:
    post:
      tags:
      - Snapshots
      summary: Create a snapshot
      description: "Create a new snapshot using the specified clone. After a snapshot
        has been created, the original clone can be deleted in order to free up compute resources, if necessary. 
        The snapshot created by this endpoint can be used later to create one or more new clones."
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      requestBody:
        description: "Parameters necessary for snapshot creation: 'cloneID' – the
          ID of the clone, 'message' – description of the snapshot"
        content:
          '*/*':
            schema:
              type: object
              properties:
                cloneID:
                  type: string
                message:
                  type: string
        required: true
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: object
                properties:
                  snapshotID:
                    type: string
        400:
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: body
  /branch/{branchName}:
    delete:
      tags:
      - Branches
      summary: Delete a branch
      description: "Permanently delete the specified branch. It cannot be undone."
      parameters:
        - name: branchName
          in: path
          required: true
          schema:
            type: string
            description: "The name of the branch to be deleted."
        - name: Verification-Token
          in: header
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ResponseStatus'
        400:
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: body
  /branch/{branchName}/log:
    get:
      tags:
      - Branches
      summary: Retrieve a branch log
      description: Retrieve a log of the specified branch (history of snapshots).
      parameters:
        - name: branchName
          in: path
          required: true
          schema:
            type: string
            description: The name of the branch.
        - name: Verification-Token
          in: header
          required: true
          schema:
            type: string
      responses:
        200:
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SnapshotDetails'
      x-codegen-request-body-name: body
  /instance/retrieval:
    get:
      tags:
      - Instance
      summary: Data refresh status
      description: 'Report a status of the data refresh subsystem (also known as
        "data retrieval"): timestamps of the previous and next refresh runs, status, messages.'
      operationId: instanceRetrieval
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      responses:
        200:
          description: Reported a status of the data retrieval subsystem
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Retrieving'
              example:
                mode: logical
                status: pending
                lastRefresh:
                nextRefresh:
                alerts: {}
                activity:
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
  /healthz:
    get:
      tags:
      - Instance
      summary: Service health check
      description: "Check the overall health and availability of the API system.
        This endpoint does not require the 'Verification-Token' header."
      operationId: healthz
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Engine'
              example:
                version: "v4.0.0-alpha.5-20230516-0224"
                edition: "standard"
                instanceID: "chhfqfcnvrvc73d0lij0"
  /admin/config:
    get:
      tags:
      - Admin
      summary: Get config
      description: "Retrieve the DBLab configuration. All sensitive values are masked.
        Only limited set of configuration parameters is returned – only those that can be
        changed via API (unless reconfiguration via API is disabled by admin). The result
        is provided in JSON format."
      operationId: getConfig
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      responses:
        200:
          description: Returned configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Config'
              example:
                databaseConfigs:
                  configs:
                    shared_buffers: 1GB
                    shared_preload_libraries: pg_stat_statements, pg_stat_kcache, auto_explain, logerrors
                databaseContainer:
                  dockerImage: registry.gitlab.com/postgres-ai/se-images/supabase:15
                global:
                  debug: true
                retrieval:
                  refresh:
                    timetable: 0 1 * * 0
                  spec:
                    logicalDump:
                      options:
                        customOptions: []
                        databases:
                          test_small: {}
                        parallelJobs: 4
                        source:
                          connection:
                            dbname: test_small
                            host: dev1.postgres.ai
                            port: 6666
                            username: john
                    logicalRestore:
                      options:
                        customOptions:
                        - "--no-tablespaces"
                        - "--no-privileges"
                        - "--no-owner"
                        - "--exit-on-error"
                        parallelJobs: 4
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
    post:
      tags:
      - Admin
      summary: Set config
      description: "Set specific configurations for the DBLab instance using this endpoint.
        The returned configuration parameters are limited to those that can be modified
        via the API (unless the API-based reconfiguration has been disabled by an administrator).
        The result will be provided in JSON format."
      operationId: setConfig
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      requestBody:
        description: Set configuration object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Config'
        required: true
      responses:
        200:
          description: Successfully saved configuration parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Config'
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: BAD_REQUEST
                message: configuration management via UI/API disabled by admin
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
      x-codegen-request-body-name: body
  /admin/config.yaml:
    get:
      tags:
      - Admin
      summary: Get full config (YAML)
      description: "Retrieve the DBLab configuration in YAML format. All sensitive values are masked.
        This method allows seeing the entire configuration file and can be helpful for
        reviewing configuration and setting up workflows to automate DBLab provisioning
        and configuration."
      operationId: getConfigYaml
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      responses:
        200:
          description: "Returned configuration (YAML)"
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Config'
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
  /admin/test-db-source:
    post:
      tags:
      - Admin
      summary: Test source database
      operationId: testDBConnection1
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      requestBody:
        description: Connection DB object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Connection'
        required: true
      responses:
        200:
          description: Successful operation
          content: {}
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: BAD_REQUEST
                message: configuration management via UI/API disabled by admin
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
      x-codegen-request-body-name: body
  /admin/ws-auth:
    get:
      tags:
      - Admin
      summary: WebSocket authentication
      operationId: wsAuth
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      responses:
        200:
          description: Successful operation
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/WSToken'
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: BAD_REQUEST
                message: configuration management via UI/API disabled by admin
        401:
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Instance'
              example:
                code: "UNAUTHORIZED"
                message: "Check your verification token."
  /metrics:
    get:
      tags:
      - Instance
      summary: Prometheus metrics
      description: "Returns Prometheus-formatted metrics for monitoring the DBLab instance.
        Includes metrics for instance status, disk usage, clones, snapshots, branches,
        sync status, and more. This endpoint does not require the 'Verification-Token' header."
      operationId: metrics
      responses:
        200:
          description: Prometheus metrics in text format
          content:
            text/plain:
              schema:
                type: string
  /observation/start:
    post:
      tags:
      - Observation
      summary: Start observing
      description: "[EXPERIMENTAL] Start an observation session for the specified clone.
        Observation sessions help detect dangerous (long-lasting, exclusive) locks in CI/CD pipelines.
        One of common scenarios is using observation sessions to test schema changes (DB migrations)."
      operationId: startObservation
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      requestBody:
        description: Start observation object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartObservationRequest'
        required: true
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservationSession'
        404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                code: NOT_FOUND
                message: Requested object does not exist. Specify your request.
      x-codegen-request-body-name: body
  /observation/stop:
    post:
      tags:
      - Observation
      summary: Stop observing
      description: "[EXPERIMENTAL] Stop the previously started observation session."
      operationId: stopObservation
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      requestBody:
        description: Stop observation object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StopObservationRequest'
        required: true
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservationSession'
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: body
  /observation/summary/{clone_id}/{session_id}:
    get:
      tags:
      - Observation
      summary: Get observation summary
      description: "[EXPERIMENTAL] Collect the observation summary info."
      operationId: summaryObservation
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      - name: clone_id
        in: path
        description: Clone ID
        required: true
        schema:
          type: string
      - name: session_id
        in: path
        description: Session ID
        required: true
        schema:
          type: string
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservationSummaryArtifact'
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /observation/download:
    get:
      tags:
      - Observation
      summary: Download an observation artifact
      description: "[EXPERIMENTAL] Download an artifact for the specified clone and observation session."
      operationId: downloadObservationArtifact
      parameters:
      - name: Verification-Token
        in: header
        required: true
        schema:
          type: string
      - name: artifact_type
        in: query
        description: Type of the requested artifact
        required: true
        schema:
          type: string
      - name: clone_id
        in: query
        description: Clone ID
        required: true
        schema:
          type: string
      - name: session_id
        in: query
        description: Session ID
        required: true
        schema:
          type: string
      responses:
        200:
          description: Successful operation
          content: {}
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Instance:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/Status'
        engine:
          $ref: '#/components/schemas/Engine'
        pools:
          type: array
          items:
            $ref: '#/components/schemas/PoolEntry'
        cloning:
          $ref: '#/components/schemas/Cloning'
        retrieving:
          $ref: '#/components/schemas/Retrieving'
        provisioner:
          $ref: '#/components/schemas/Provisioner'
        synchronization:
          $ref: '#/components/schemas/Synchronization'
    Status:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: string
          description: Status code
        message:
          type: string
          description: Status description
    Engine:
      type: object
      properties:
        version:
          type: string
        edition:
          type: string
        billingActive:
          type: string
        instanceID:
          type: string
        startedAt:
          type: string
          format: date-time
        telemetry:
          type: boolean
        disableConfigModification:
          type: boolean
    PoolEntry:
      type: object
      properties:
        name:
          type: string
        mode:
          type: string
        dataStateAt:
          type: string
          format: date-time
        status:
          type: string
        cloneList:
          type: array
          items:
            type: string
        fileSystem:
          $ref: '#/components/schemas/FileSystem'
    FileSystem:
      type: object
      properties:
        mode:
          type: string
        free:
          type: integer
          format: int64
        size:
          type: integer
          format: int64
        used:
          type: integer
          format: int64
        dataSize:
          type: integer
          format: int64
        usedBySnapshots:
          type: integer
          format: int64
        usedByClones:
          type: integer
          format: int64
        compressRatio:
          type: integer
          format: float64
    Cloning:
      type: object
      properties:
        expectedCloningTime:
          type: integer
          format: float64
        numClones:
          type: integer
          format: int64
        clones:
          type: array
          items:
            $ref: '#/components/schemas/Clone'
        protectionLeaseDurationMinutes:
          type: integer
          format: int64
          minimum: 0
          description: Default protection lease duration in minutes
        protectionMaxDurationMinutes:
          type: integer
          format: int64
          minimum: 0
          description: Maximum allowed protection duration in minutes
    Retrieving:
      type: object
      properties:
        mode:
          type: string
        status:
          type: string
        lastRefresh:
          type: string
          format: date-time
        nextRefresh:
          type: string
          format: date-time
        alerts:
          type: array
          items:
            type: string
        activity:
          $ref: '#/components/schemas/Activity'
    Activity:
      type: object
      properties:
        source:
          type: array
          items:
            $ref: '#/components/schemas/PGActivityEvent'
        target:
          type: array
          items:
            $ref: '#/components/schemas/PGActivityEvent'
    PGActivityEvent:
      type: object
      properties:
        user:
          type: string
        query:
          type: string
        duration:
          type: number
        waitEventType:
          type: string
        waitEvent:
          type: string
    Provisioner:
      type: object
      properties:
        dockerImage:
          type: string
        containerConfig:
          type: object
          properties: {}
    Synchronization:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/Status'
        startedAt:
          type: string
          format: date-time
        lastReplayedLsn:
          type: string
        lastReplayedLsnAt:
          type: string
          format: date-time
        replicationLag:
          type: string
        replicationUptime:
          type: integer
    Snapshot:
      type: object
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        dataStateAt:
          type: string
          format: date-time
        physicalSize:
          type: integer
          format: int64
        logicalSize:
          type: integer
          format: int64
        pool:
          type: string
        numClones:
          type: integer
          format: int
    Database:
      type: object
      properties:
        connStr:
          type: string
        host:
          type: string
        port:
          type: string
        username:
          type: string
        password:
          type: string
        dbName:
          type: string
    Clone:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        snapshot:
          $ref: '#/components/schemas/Snapshot'
        branch:
          type: string
        revision:
          type: integer
        protected:
          type: boolean
          default: false
        protectedTill:
          type: string
          format: date-time
          description: Time when the protection lease expires
        deleteAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/Status'
        db:
          $ref: '#/components/schemas/Database'
        metadata:
          $ref: '#/components/schemas/CloneMetadata'
    CloneMetadata:
      type: object
      properties:
        cloneDiffSize:
          type: integer
          format: int64
        logicalSize:
          type: integer
          format: int64
        cloningTime:
          type: integer
          format: float64
        maxIdleMinutes:
          type: integer
          format: int64
        protectionLeaseDurationMinutes:
          type: integer
          format: int64
          minimum: 0
          description: Protection lease duration in minutes
        protectionMaxDurationMinutes:
          type: integer
          format: int64
          minimum: 0
          description: Maximum allowed protection duration in minutes
    CreateClone:
      type: object
      properties:
        id:
          type: string
        snapshot:
          type: object
          properties:
            id:
              type: string
        branch:
          type: string
        protected:
          type: boolean
          default:
        protectionDurationMinutes:
          type: integer
          format: int64
          minimum: 0
          description: Protection duration in minutes. 0 means forever, omit for default duration.
        db:
          type: object
          properties:
            username:
              type: string
            password:
              type: string
            restricted:
              type: boolean
              default:
            db_name:
              type: string
        extra_conf:
          type: object
          additionalProperties:
            type: string
          description: Extra PostgreSQL configuration parameters for the clone
    ResetClone:
      type: object
      properties:
        snapshotID:
          type: string
        latest:
          type: boolean
          default: false
      description: "Define what snapshot needs to be used when resetting the clone.
       'snapshotID' allows specifying the exact snapshot, while 'latest' allows using 
       the latest snapshot among all available snapshots. The latter method can be 
       helpful when the exact snapshot ID is not known."
    UpdateClone:
      type: object
      properties:
        protected:
          type: boolean
          default: false
        protectionDurationMinutes:
          type: integer
          format: int64
          minimum: 0
          description: Protection duration in minutes. 0 means forever, omit for default duration.
    StartObservationRequest:
      type: object
      properties:
        clone_id:
          type: string
        config:
          $ref: '#/components/schemas/ObservationConfig'
        tags:
          type: object
          properties: {}
        db_name:
          type: string
    ObservationConfig:
      type: object
      properties:
        observation_interval:
          type: integer
          format: int64
        max_lock_duration:
          type: integer
          format: int64
        max_duration:
          type: integer
          format: int64
    ObservationSession:
      type: object
      properties:
        session_id:
          type: integer
          format: int64
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
        config:
          $ref: '#/components/schemas/ObservationConfig'
        tags:
          type: object
          properties: {}
        artifacts:
          type: array
          items:
            type: string
        result:
          $ref: '#/components/schemas/ObservationResult'
    ObservationResult:
      type: object
      properties:
        status:
          type: string
        intervals:
          type: array
          items:
            $ref: '#/components/schemas/ObservationInterval'
        summary:
          $ref: '#/components/schemas/ObservationSummary'
    ObservationInterval:
      type: object
      properties:
        started_at:
          type: string
          format: date-time
        duration:
          type: integer
          format: int64
        warning:
          type: string
    ObservationSummary:
      type: object
      properties:
        total_duration:
          type: integer
          format: float64
        total_intervals:
          type: integer
          format: int
        warning_intervals:
          type: integer
          format: int
        checklist:
          $ref: '#/components/schemas/ObservationChecklist'
    ObservationChecklist:
      type: object
      properties:
        overall_success:
          type: boolean
        session_duration_acceptable:
          type: boolean
        no_long_dangerous_locks:
          type: boolean
    StopObservationRequest:
      type: object
      properties:
        clone_id:
          type: string
        overall_error:
          type: boolean
    SummaryObservationRequest:
      type: object
      properties:
        clone_id:
          type: string
        session_id:
          type: string
    ObservationSummaryArtifact:
      type: object
      properties:
        session_id:
          type: integer
          format: int64
        clone_id:
          type: string
        duration:
          type: object
          properties: {}
        db_size:
          type: object
          properties: {}
        locks:
          type: object
          properties: {}
        log_errors:
          type: object
          properties: {}
        artifact_types:
          type: array
          items:
            type: string
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        detail:
          type: string
        hint:
          type: string
    ResponseStatus:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
    Config:
      type: object
    Connection:
      type: object
      properties:
        host:
          type: string
        port:
          type: string
        dbname:
          type: string
        username:
          type: string
        password:
          type: string
        db_list:
          type: array
          items:
            type: string
    WSToken:
      type: object
      properties:
        token:
          type: string
          description: WebSocket token
    Branch:
      type: object
      properties:
        name:
          type: string
        parent:
          type: string
        dataStateAt:
          type: string
          format: date-time
        snapshotID:
          type: string
    SnapshotDetails:
      type: object
      properties:
        id:
          type: string
        parent:
          type: string
        child:
          type: string
        branch:
          type: array
          items:
            type: string
        root:
          type: string
        dataStateAt:
          type: string
          format: date-time
        message:
          type: string
    FullRefresh:
      type: object
      properties:
        status:
          type: string
          example: OK
        message:
          type: string
          example: Full refresh started