openapi: 3.1.0
info:
  title: pyxray assets API
  version: 0.1.0
  description: Contract for Xray runtime asset detection, download, and update.
servers:
  - url: /api/v1
paths:
  /assets/config:
    get:
      operationId: getAssetsConfig
      summary: Read core.toml content
      responses:
        "200":
          description: Core configuration as TOML text.
          content:
            application/json:
              schema:
                $ref: "../schemas/assets.schema.json#/$defs/CoreConfigText"
  /assets/status:
    get:
      operationId: getAssetsStatus
      summary: Inspect local Xray and geo assets
      responses:
        "200":
          description: Local asset status.
          content:
            application/json:
              schema:
                $ref: "../schemas/assets.schema.json#/$defs/AssetsStatus"
  /assets/update:
    post:
      operationId: updateAssets
      summary: Update assets when needed
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "../schemas/assets.schema.json#/$defs/AssetsUpdateRequest"
      responses:
        "202":
          description: Download task accepted.
          content:
            application/json:
              schema:
                $ref: "../schemas/assets.schema.json#/$defs/AssetsTaskStartResponse"
        "409":
          description: Another download task is already running.
          content:
            application/json:
              schema:
                $ref: "../schemas/assets.schema.json#/$defs/ErrorResponse"
  /assets/download:
    post:
      operationId: downloadAssets
      summary: Download selected assets
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "../schemas/assets.schema.json#/$defs/AssetsDownloadRequest"
      responses:
        "202":
          description: Download task accepted.
          content:
            application/json:
              schema:
                $ref: "../schemas/assets.schema.json#/$defs/AssetsTaskStartResponse"
        "409":
          description: Another download task is already running.
          content:
            application/json:
              schema:
                $ref: "../schemas/assets.schema.json#/$defs/ErrorResponse"
  /assets/download/task:
    get:
      operationId: getAssetsDownloadTask
      summary: Read current download task status
      responses:
        "200":
          description: Current download task status.
          content:
            application/json:
              schema:
                $ref: "../schemas/assets.schema.json#/$defs/DownloadTaskStatus"
  /assets/download/cancel:
    post:
      operationId: cancelAssetsDownload
      summary: Request cancellation for the current download task
      responses:
        "200":
          description: Current download task status after cancellation was requested.
          content:
            application/json:
              schema:
                $ref: "../schemas/assets.schema.json#/$defs/DownloadTaskStatus"