# Code generated by VDL v0.5.0-alpha.5 (commit 1aaf1f7) using varavelio/vdl-plugin-rpc-openapi@v0.1.3 (hash 4cc00983)
# Any changes will be overwritten the next time VDL is run. DO NOT EDIT.
# Learn more: https://github.com/varavelio/vdl

openapi: 3.0.0
info:
  title: NSQLite API
  version: 1.0.0
security:
  - AuthToken: []
servers:
  - url: https://<baseURL>:9876/rpc
tags:
  - name: DatabaseProcedures
    description: Procedures for Database
  - name: SystemProcedures
    description: Procedures for System
paths:
  /Database/query:
    post:
      tags:
        - DatabaseProcedures
      requestBody:
        $ref: "#/components/requestBodies/DatabaseQueryInput"
      responses:
        "200":
          $ref: "#/components/responses/DatabaseQueryOutput"
      description: |-
        Executes one or more SQL queries against the database.

        Queries are executed in order and each query returns one result item.
        Empty or failed queries are returned as result items with type "error".
  /System/health:
    post:
      tags:
        - SystemProcedures
      requestBody:
        $ref: "#/components/requestBodies/SystemHealthInput"
      responses:
        "200":
          $ref: "#/components/responses/SystemHealthOutput"
      description: Checks whether the server can perform a basic database read.
  /System/session:
    post:
      tags:
        - SystemProcedures
      requestBody:
        $ref: "#/components/requestBodies/SystemSessionInput"
      responses:
        "200":
          $ref: "#/components/responses/SystemSessionOutput"
      description: Returns the authentication role for the current session.
  /System/status:
    post:
      tags:
        - SystemProcedures
      requestBody:
        $ref: "#/components/requestBodies/SystemStatusInput"
      responses:
        "200":
          $ref: "#/components/responses/SystemStatusOutput"
      description: Returns server information and runtime statistics.
components:
  securitySchemes:
    AuthToken:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Enter the full value for the Authorization header. The specific format
        (Bearer, Basic, API Key, etc.) is determined by the server's
        implementation.


        ---

        **Examples:**

        - **Bearer Token:** `Bearer eyJhbGciOiJIUzI1Ni...` (a JWT token)

        - **Basic Auth:** `Basic dXNlcm5hbWU6cGFzc3dvcmQ=` (a base64 encoding of
        `username:password`)

        - **API Key:** `sk_live_123abc456def` (a raw token)
  schemas:
    Query:
      type: object
      properties:
        txId:
          type: string
          description: Transaction ID to execute the query within an existing transaction.
        query:
          type: string
          description: The SQL query string.
        params:
          type: array
          items:
            $ref: "#/components/schemas/QueryParam"
          description: Optional query parameters.
      required:
        - query
      description: |-
        Represents one SQL query execution request.

        - txId is used to execute the query inside an existing transaction.
    QueryParam:
      type: object
      properties:
        name:
          type: string
          description: Parameter name for named parameters. Omitted for positional
            parameters.
        value:
          allOf:
            - $ref: "#/components/schemas/SqliteValue"
            - description: The parameter value.
      required:
        - value
      description: |-
        Represents one SQLite query parameter.

        When name is omitted, the parameter is positional.
        When name is present, the parameter is named.
    QueryResult:
      type: object
      properties:
        type:
          allOf:
            - $ref: "#/components/schemas/QueryResultType"
            - description: The type of result (read, write, begin, commit, rollback, or
                error).
        time:
          type: number
          description: Query execution time in seconds (as a floating-point duration).
        error:
          type: string
          description: Error message, present when type is "error".
        txId:
          type: string
          description: Transaction ID, present when type is "begin".
        lastInsertId:
          type: integer
          description: The rowid of the last inserted row, present for write results.
        rowsAffected:
          type: integer
          description: The number of rows affected, present for write results.
        columns:
          type: array
          items:
            type: string
          description: Column names for the returned rows, present for read/write results.
        types:
          type: array
          items:
            $ref: "#/components/schemas/SqliteStorageClass"
          description: Storage class of each column for the returned rows.
        rows:
          type: array
          items:
            type: array
            items:
              $ref: "#/components/schemas/SqliteValue"
          description: The returned rows, each row being an array of SqliteValue.
      required:
        - type
        - time
      description: >-
        Represents one SQL query execution result.


        - For read/write results with returned rows, columns, types, and rows
        are present.

        - For begin results, txId is present.

        - For write results, lastInsertId and rowsAffected are present.

        - For error results, error is present.
    SqliteValue:
      type: object
      properties:
        "null":
          type: boolean
          description: SQL NULL value.
        integer:
          type: integer
          description: SQL INTEGER value.
        real:
          type: number
          description: SQL REAL value.
        text:
          type: string
          description: SQL TEXT value.
        blob:
          type: string
          description: SQL BLOB value encoded as base64.
      description: |-
        Represents one SQLite value.

        Exactly one field must be present.

        Mappings:
        - null    -> SQLite NULL
        - integer -> SQLite INTEGER
        - real    -> SQLite REAL
        - text    -> SQLite TEXT
        - blob    -> SQLite BLOB encoded as base64
    Stats:
      type: object
      properties:
        startedAt:
          type: string
          format: date-time
          description: The server start time.
        uptimeSeconds:
          type: number
          description: Number of seconds since the server started.
        totals:
          allOf:
            - $ref: "#/components/schemas/StatsTotalsCounters"
            - description: Cumulative counters for all completed operations.
        queued:
          allOf:
            - $ref: "#/components/schemas/StatsQueuedCounters"
            - description: Counters for currently queued or in-flight operations.
        minutes:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/StatsTotalsCounters"
          description: Per-minute counters keyed by UTC minute in RFC3339 format.
      required:
        - startedAt
        - uptimeSeconds
        - totals
        - queued
        - minutes
      description: Aggregated server statistics including totals, queued operations,
        and per-minute history.
    StatsQueuedCounters:
      type: object
      properties:
        begins:
          type: integer
          description: Number of BEGIN TRANSACTION statements currently queued.
        writes:
          type: integer
          description: Number of write queries currently queued.
        httpRequests:
          type: integer
          description: Number of HTTP requests currently being processed or queued.
      required:
        - begins
        - writes
        - httpRequests
      description: Statistics counters for operations that are currently queued or
        in-flight.
    StatsTotalsCounters:
      type: object
      properties:
        reads:
          type: integer
          description: Total number of completed read queries.
        writes:
          type: integer
          description: Total number of completed write queries.
        begins:
          type: integer
          description: Total number of completed BEGIN TRANSACTION statements.
        commits:
          type: integer
          description: Total number of completed COMMIT statements.
        rollbacks:
          type: integer
          description: Total number of completed ROLLBACK statements.
        errors:
          type: integer
          description: Total number of queries that resulted in an error.
        httpRequests:
          type: integer
          description: Total number of HTTP requests received.
      required:
        - reads
        - writes
        - begins
        - commits
        - rollbacks
        - errors
        - httpRequests
      description: Statistics counters for operations that have completed.
    AuthRole:
      type: string
      enum:
        - admin
        - rw
        - ro
      description: AuthRole represents the authentication role assigned to a session.
    QueryResultType:
      type: string
      enum:
        - read
        - write
        - begin
        - commit
        - rollback
        - error
      description: QueryResultType represents the type of a given SQLite query.
    SqliteStorageClass:
      type: string
      enum:
        - "NULL"
        - INTEGER
        - REAL
        - TEXT
        - BLOB
      description: SqliteStorageClass represents the storage class of a given SQLite value.
  requestBodies:
    DatabaseQueryInput:
      description: Request body for Database/query procedure
      content:
        application/json:
          schema:
            type: object
            properties:
              queries:
                type: array
                items:
                  $ref: "#/components/schemas/Query"
                description: The list of SQL queries to execute in order.
            required:
              - queries
    SystemHealthInput:
      description: Request body for System/health procedure
      content:
        application/json:
          schema:
            type: object
            properties: {}
    SystemSessionInput:
      description: Request body for System/session procedure
      content:
        application/json:
          schema:
            type: object
            properties: {}
    SystemStatusInput:
      description: Request body for System/status procedure
      content:
        application/json:
          schema:
            type: object
            properties: {}
  responses:
    DatabaseQueryOutput:
      description: Response for Database/query procedure
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
              output:
                type: object
                properties:
                  time:
                    type: number
                    description: Total execution time in seconds for all queries.
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/QueryResult"
                    description: One result per input query, in the same order.
                required:
                  - time
                  - results
              error:
                type: object
                properties:
                  message:
                    type: string
                  category:
                    type: string
                  code:
                    type: string
                  details:
                    type: object
                    properties: {}
                    additionalProperties: true
                required:
                  - message
            required:
              - ok
    SystemHealthOutput:
      description: Response for System/health procedure
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
              output:
                type: object
                properties:
                  healthy:
                    type: boolean
                    description: Whether the server is healthy and fully operational.
                  database:
                    type: boolean
                    description: Whether the database is reachable and responsive.
                  message:
                    type: string
                    description: A human-readable message describing the health state.
                required:
                  - healthy
                  - database
                  - message
              error:
                type: object
                properties:
                  message:
                    type: string
                  category:
                    type: string
                  code:
                    type: string
                  details:
                    type: object
                    properties: {}
                    additionalProperties: true
                required:
                  - message
            required:
              - ok
    SystemSessionOutput:
      description: Response for System/session procedure
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
              output:
                type: object
                properties:
                  role:
                    allOf:
                      - $ref: "#/components/schemas/AuthRole"
                      - description: The authentication role assigned to the current session.
                required:
                  - role
              error:
                type: object
                properties:
                  message:
                    type: string
                  category:
                    type: string
                  code:
                    type: string
                  details:
                    type: object
                    properties: {}
                    additionalProperties: true
                required:
                  - message
            required:
              - ok
    SystemStatusOutput:
      description: Response for System/status procedure
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
              output:
                type: object
                properties:
                  name:
                    type: string
                    description: The server name.
                  version:
                    type: string
                    description: The server version string.
                  stats:
                    allOf:
                      - $ref: "#/components/schemas/Stats"
                      - description: Current runtime statistics.
                required:
                  - name
                  - version
                  - stats
              error:
                type: object
                properties:
                  message:
                    type: string
                  category:
                    type: string
                  code:
                    type: string
                  details:
                    type: object
                    properties: {}
                    additionalProperties: true
                required:
                  - message
            required:
              - ok