openapi: "3.0.0"
info:
  title: hostd API
  description: >
    hostd exposes endpoints for configuring and operating a Sia storage host. It covers consensus access, host settings, storage management, contract queries, metrics, alerts, and webhook notifications.

  version: 2.12.0-beta.1
servers:
  - url: http://localhost:9980/api
security:
  - basicAuth: []
tags:
  - name: state
    description: Host status, announcements, and build metadata.
  - name: consensus
    description: Read-only access to blockchain state and checkpoints.
  - name: syncer
    description: Manage peer connections and Siamux addresses.
  - name: index
    description: View host index synchronization.
  - name: alerts
    description: Retrieve and dismiss host alerts.
  - name: settings
    description: Host configuration, pinned settings, and dynamic DNS control.
  - name: metrics
    description: Metrics endpoints for Prometheus and historical analysis.
  - name: contracts
    description: Contract queries and integrity checks (v1 and v2).
  - name: sectors
    description: Inspect and remove individual sectors.
  - name: volumes
    description: Storage volume lifecycle management.
  - name: txpool
    description: Transaction pool fee estimation.
  - name: wallet
    description: Wallet balances, events, and outgoing payments.
  - name: system
    description: System utilities, backups, and connectivity tests.
  - name: webhooks
    description: Configure outbound webhook integrations.
paths:
  /state:
    get:
      tags:
        - state
      summary: Get host state
      description: Returns general metadata about the hostd instance.
      operationId: getState
      responses:
        "200":
          description: Current host state.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/State"
  /settings/announce:
    post:
      tags:
        - settings
      summary: Broadcast host announcement
      description: Queues a host announcement transaction on the Sia network.
      operationId: postSettingsAnnounce
      responses:
        "200":
          description: Announcement submitted.
  /consensus/tip:
    get:
      tags:
        - consensus
      summary: Current chain tip index
      description: Returns the current consensus chain tip index (height and block ID).
      operationId: getConsensusTip
      responses:
        "200":
          description: Current consensus tip index.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChainIndex"
  /consensus/tipstate:
    get:
      tags:
        - consensus
      summary: Current consensus state
      description: Returns the full consensus state at the current chain tip.
      operationId: getConsensusTipState
      responses:
        "200":
          description: Consensus state at the tip.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsensusState"
  /consensus/checkpoint/{id}:
    get:
      tags:
        - consensus
      summary: Retrieve checkpoint
      description: Returns the consensus state and block for a given block ID.
      operationId: getConsensusCheckpoint
      parameters:
        - name: id
          in: path
          required: true
          description: Block ID in hexadecimal.
          schema:
            $ref: "#/components/schemas/BlockID"
      responses:
        "200":
          description: Matching checkpoint.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsensusCheckpointResponse"
        "404":
          description: Block not found.
  /consensus/network:
    get:
      tags:
        - consensus
      summary: Network parameters
      description: Returns the consensus network parameters including hardfork heights.
      operationId: getConsensusNetwork
      responses:
        "200":
          description: Consensus network configuration.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConsensusNetwork"
  /syncer/address:
    get:
      tags:
        - syncer
      summary: Syncer address
      description: Returns the node's public syncer address.
      operationId: getSyncerAddress
      responses:
        "200":
          description: The node's public syncer address.
          content:
            application/json:
              schema:
                type: string
  /syncer/peers:
    get:
      tags:
        - syncer
      summary: List peers
      description: Returns a list of currently connected peers
      operationId: getSyncerPeers
      responses:
        "200":
          description: Current syncer peers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Peer"
    put:
      tags:
        - syncer
      summary: Connect to peer
      description: Initiates a connection to the specified peer address.
      operationId: putSyncerPeer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SyncerConnectRequest"
      responses:
        "200":
          description: Peer connection requested.
  /index/tip:
    get:
      tags:
        - index
      summary: Index tip
      description: Returns the last indexed tip. It may lag behind the consensus tip if the host is still synchronizing.
      operationId: getIndexTip
      responses:
        "200":
          description: Current index synchronization tip.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChainIndex"
  /alerts:
    get:
      tags:
        - alerts
      summary: List active alerts
      description: Returns all active host alerts.
      operationId: getAlerts
      responses:
        "200":
          description: Active alerts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Alert"
  /alerts/dismiss:
    post:
      tags:
        - alerts
      summary: Dismiss alerts
      description: Dismisses the alerts with the specified IDs.
      operationId: postAlertsDismiss
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/Hash256"
      responses:
        "200":
          description: Alerts dismissed.
  /settings:
    get:
      tags:
        - settings
      summary: Current host settings
      description: Returns the host's current configuration settings.
      operationId: getSettings
      responses:
        "200":
          description: Host configuration.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HostSettings"
    patch:
      tags:
        - settings
      summary: Update host settings
      description: Partially updates the host's settings by merging the provided fields with the current values.
      operationId: patchSettings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "200":
          description: Updated host settings.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HostSettings"
  /settings/pinned:
    get:
      tags:
        - settings
      summary: Pinned settings
      description: Returns the host's pinned price settings. Requires an explorer.
      operationId: getPinnedSettings
      responses:
        "200":
          description: Pinned settings response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PinnedSettings"
    put:
      tags:
        - settings
      summary: Update pinned settings
      description: Updates the host's pinned price settings. Requires an explorer.
      operationId: putPinnedSettings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PinnedSettings"
      responses:
        "200":
          description: Settings updated.
  /settings/ddns/update:
    put:
      tags:
        - settings
      summary: Trigger DDNS update
      description: Forces an immediate update of the host's dynamic DNS records.
      operationId: putSettingsDDNSUpdate
      responses:
        "200":
          description: Dynamic DNS updated.
  /metrics:
    get:
      tags:
        - metrics
      summary: Current metrics snapshot
      description: Returns a snapshot of host metrics at the specified or current timestamp.
      operationId: getMetrics
      parameters:
        - name: timestamp
          in: query
          required: false
          description: Optional ISO8601 timestamp. Defaults to now when omitted.
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: Metrics as of the requested timestamp.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Metrics"
  /metrics/{period}:
    get:
      tags:
        - metrics
      summary: Metrics over an interval
      description: Returns metrics aggregated over the specified interval and number of periods.
      operationId: getMetricsPeriod
      parameters:
        - name: period
          in: path
          required: true
          description: Interval identifier (e.g. 5m, 15m, hourly, daily).
          schema:
            type: string
            enum: ["5m", "15m", "hourly", "daily", "weekly", "monthly", "yearly"]
        - name: start
          in: query
          required: true
          description: Start timestamp for the first period.
          schema:
            type: string
            format: date-time
        - name: periods
          in: query
          required: false
          description: Number of periods to include. Defaults to cover up to current time when zero.
          schema:
            type: integer
            minimum: 0
      responses:
        "200":
          description: Metrics for each requested period.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Metrics"
  /contracts:
    post:
      deprecated: true
      tags:
        - contracts
      summary: Query contracts
      description: Queries v1 contracts matching the provided filter and returns a paginated result.
      operationId: postContracts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractFilter"
      responses:
        "200":
          description: Contracts matching filter.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractsResponse"
  /contracts/{id}:
    get:
      deprecated: true
      tags:
        - contracts
      summary: Get contract
      description: Returns the details of a single v1 contract by its file contract ID.
      operationId: getContract
      parameters:
        - $ref: "#/components/parameters/FileContractIDParam"
      responses:
        "200":
          description: Contract details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Contract"
        "404":
          description: Contract not found.
  /contracts/{id}/integrity:
    get:
      tags:
        - contracts
      summary: Get contract integrity result
      description: Returns the current or most recent integrity check result for the specified contract.
      operationId: getContractIntegrity
      parameters:
        - $ref: "#/components/parameters/FileContractIDParam"
      responses:
        "200":
          description: Latest integrity check result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IntegrityCheckResult"
        "404":
          description: Integrity check not found.
    put:
      tags:
        - contracts
      summary: Start integrity check
      description: Starts a background integrity check that reads and verifies every sector in the contract.
      operationId: putContractIntegrity
      parameters:
        - $ref: "#/components/parameters/FileContractIDParam"
      responses:
        "200":
          description: Integrity check started.
    delete:
      tags:
        - contracts
      summary: Delete integrity result
      description: Clears the stored integrity check result for the specified contract.
      operationId: deleteContractIntegrity
      parameters:
        - $ref: "#/components/parameters/FileContractIDParam"
      responses:
        "200":
          description: Integrity result cleared.
        "404":
          description: Integrity check not found.
  /v2/contracts:
    post:
      tags:
        - contracts
      summary: Query v2 contracts
      description: Queries v2 contracts matching the provided filter and returns a paginated result.
      operationId: postV2Contracts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/V2ContractFilter"
      responses:
        "200":
          description: V2 contracts matching filter.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V2ContractsResponse"
  /v2/contracts/{id}:
    get:
      tags:
        - contracts
      summary: Get v2 contract
      description: Returns the details of a single v2 contract by its file contract ID.
      operationId: getV2Contract
      parameters:
        - $ref: "#/components/parameters/FileContractIDParam"
      responses:
        "200":
          description: V2 contract details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V2Contract"
        "404":
          description: Contract not found.
  /sectors/{root}:
    delete:
      tags:
        - sectors
      summary: Delete sector
      description: Removes a sector's metadata and zeroes its data on disk.
      operationId: deleteSector
      parameters:
        - $ref: "#/components/parameters/SectorRootParam"
      responses:
        "200":
          description: Sector queued for deletion.
  /sectors/{root}/verify:
    get:
      tags:
        - sectors
      summary: Verify sector location
      description: Returns the sector's references and verifies its data integrity by reading it from disk.
      operationId: getSectorVerification
      parameters:
        - $ref: "#/components/parameters/SectorRootParam"
      responses:
        "200":
          description: Sector reference details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VerifySectorResponse"
  /volumes:
    get:
      tags:
        - volumes
      summary: List volumes
      description: Returns all storage volumes with their metadata and statistics.
      operationId: getVolumes
      responses:
        "200":
          description: Storage volumes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/VolumeMeta"
    post:
      tags:
        - volumes
      summary: Add volume
      description: Creates a new storage volume at the specified path with the given sector capacity.
      operationId: postVolume
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddVolumeRequest"
      responses:
        "200":
          description: Volume added.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Volume"
  /volumes/{id}:
    get:
      tags:
        - volumes
      summary: Get volume
      description: Returns the metadata and statistics for a single storage volume.
      operationId: getVolume
      parameters:
        - $ref: "#/components/parameters/VolumeIDParam"
      responses:
        "200":
          description: Volume metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VolumeMeta"
        "404":
          description: Volume not found.
    put:
      tags:
        - volumes
      summary: Set volume read-only
      description: Updates a volume's read-only status.
      operationId: putVolume
      parameters:
        - $ref: "#/components/parameters/VolumeIDParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateVolumeRequest"
      responses:
        "200":
          description: Volume updated.
    delete:
      tags:
        - volumes
      summary: Remove volume
      description: Initiates removal of a storage volume, migrating sectors to other volumes.
      operationId: deleteVolume
      parameters:
        - $ref: "#/components/parameters/VolumeIDParam"
        - name: force
          in: query
          required: false
          description: Force removal when true.
          schema:
            type: boolean
      responses:
        "200":
          description: Volume removal requested.
  /volumes/{id}/cancel:
    delete:
      tags:
        - volumes
      summary: Cancel volume operation
      description: Cancels an in-progress volume operation such as creation, resize, or removal.
      operationId: deleteVolumeCancel
      parameters:
        - $ref: "#/components/parameters/VolumeIDParam"
      responses:
        "200":
          description: Volume operation cancelled.
  /volumes/{id}/resize:
    put:
      tags:
        - volumes
      summary: Resize volume
      description: Initiates resizing a volume to the specified number of sectors.
      operationId: putVolumeResize
      parameters:
        - $ref: "#/components/parameters/VolumeIDParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResizeVolumeRequest"
      responses:
        "200":
          description: Resize initiated.
  /tpool/fee:
    get:
      tags:
        - txpool
      summary: Recommended transaction fee
      description: Returns the recommended transaction fee per byte in hastings.
      operationId: getTPoolFee
      responses:
        "200":
          description: Recommended fee per byte.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Currency"
  /wallet:
    get:
      tags:
        - wallet
      summary: Wallet state
      description: Returns the wallet's balance and address.
      operationId: getWallet
      responses:
        "200":
          description: Wallet balance and address.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WalletResponse"
  /wallet/events:
    get:
      tags:
        - wallet
      summary: Wallet events
      description: Returns a paginated list of wallet events.
      operationId: getWalletEvents
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
      responses:
        "200":
          description: Wallet events ordered by time.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WalletEvent"
  /wallet/events/{id}:
    get:
      tags:
        - wallet
      summary: Get wallet event
      description: Returns a single wallet event by its ID.
      operationId: getWalletEvent
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/Hash256"
      responses:
        "200":
          description: Wallet event details.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WalletEvent"
        "404":
          description: Event not found.
  /wallet/pending:
    get:
      tags:
        - wallet
      summary: Pending wallet events
      description: Returns unconfirmed wallet events.
      operationId: getWalletPending
      responses:
        "200":
          description: Pending wallet events.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WalletEvent"
  /wallet/send:
    post:
      tags:
        - wallet
      summary: Send Siacoins
      description: Sends Siacoins to the specified address and returns the transaction ID.
      operationId: postWalletSend
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WalletSendSiacoinsRequest"
      responses:
        "200":
          description: Transaction broadcasted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Hash256"
  /system/dir:
    get:
      tags:
        - system
      summary: Inspect system directory
      description: Returns the contents and disk usage of the specified directory path.
      operationId: getSystemDir
      parameters:
        - name: path
          in: query
          required: false
          description: Absolute path to inspect. Defaults to the daemon working directory.
          schema:
            type: string
      responses:
        "200":
          description: Directory contents and metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SystemDirResponse"
    put:
      tags:
        - system
      summary: Create directory
      description: Creates a directory at the specified path, including any necessary parent directories.
      operationId: putSystemDir
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDirRequest"
      responses:
        "200":
          description: Directory created.
  /system/sqlite3/backup:
    post:
      tags:
        - system
      summary: Create SQLite backup
      description: Creates a backup of the SQLite3 database at the specified path.
      operationId: postSystemSQLite3Backup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BackupRequest"
      responses:
        "200":
          description: Backup started.
  /system/connect/test:
    put:
      tags:
        - system
      summary: Run connectivity test
      description: Runs a connectivity test to verify the host is reachable from the network.
      operationId: putSystemConnectTest
      responses:
        "200":
          description: Connectivity test result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TestResult"
        "400":
          description: Connectivity test not enabled.
  /webhooks:
    get:
      tags:
        - webhooks
      summary: List webhooks
      description: Returns all registered webhooks.
      operationId: getWebhooks
      responses:
        "200":
          description: Registered webhooks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Webhook"
    post:
      tags:
        - webhooks
      summary: Register webhook
      description: Registers a new webhook with the specified callback URL and event scopes.
      operationId: postWebhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterWebHookRequest"
      responses:
        "200":
          description: Webhook registered.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Webhook"
  /webhooks/{id}:
    put:
      tags:
        - webhooks
      summary: Update webhook
      description: Updates the callback URL and scopes of an existing webhook.
      operationId: putWebhooks
      parameters:
        - $ref: "#/components/parameters/WebhookIDParam"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterWebHookRequest"
      responses:
        "200":
          description: Webhook updated.
    delete:
      tags:
        - webhooks
      summary: Delete webhook
      description: Removes a registered webhook.
      operationId: deleteWebhooks
      parameters:
        - $ref: "#/components/parameters/WebhookIDParam"
      responses:
        "200":
          description: Webhook removed.
  /webhooks/{id}/test:
    post:
      tags:
        - webhooks
      summary: Broadcast test event to webhook
      description: Sends a test event to the specified webhook.
      operationId: postWebhookTest
      parameters:
        - $ref: "#/components/parameters/WebhookIDParam"
      responses:
        "200":
          description: Test event dispatched.
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  parameters:
    FileContractIDParam:
      name: id
      in: path
      required: true
      description: File contract identifier.
      schema:
        type: string
        pattern: "^fcid:[0-9a-fA-F]{64}$"
    VolumeIDParam:
      name: id
      in: path
      required: true
      description: Volume identifier.
      schema:
        type: integer
        format: int64
    SectorRootParam:
      name: root
      in: path
      required: true
      description: Sector root hash.
      schema:
        $ref: "#/components/schemas/Hash256"
    WebhookIDParam:
      name: id
      in: path
      required: true
      description: Webhook identifier.
      schema:
        type: integer
        format: int64
  schemas:
    Hash256:
      type: string
      pattern: "^[0-9a-fA-F]{64}$"
      description: 256-bit blake2b hash.
    BlockID:
      allOf:
        - $ref: "#/components/schemas/Hash256"
      description: Unique identifier for a block.
    Currency:
      type: string
      pattern: "^\\d+$"
      maxLength: 39
      description: Hastings (1 Siacoin = 10^24 Hastings).
    Work:
      type: string
      pattern: "^\\d+$"
      description: Quantity of work encoded as a decimal string.
    Address:
      type: string
      description: Human-readable Sia address.
    PublicKey:
      type: string
      pattern: "^ed25519:[0-9a-fA-F]{64}$"
      description: Ed25519 public key with prefix.
    Signature:
      type: string
      pattern: "^[0-9a-fA-F]{128}$"
      description: Hex-encoded Ed25519 signature.
    ChainIndex:
      type: object
      properties:
        height:
          type: integer
          format: int64
          description: Block height.
        id:
          $ref: "#/components/schemas/BlockID"
          description: Block ID at this height.
      required:
        - height
        - id
    ElementAccumulator:
      type: object
      description: Sparse Merkle forest tracking consensus elements.
      properties:
        numLeaves:
          type: integer
          format: int64
          description: Number of leaves represented by the accumulator.
        trees:
          type: array
          description: Merkle roots for the populated accumulator trees in ascending height order.
          items:
            $ref: "#/components/schemas/Hash256"
      required:
        - numLeaves
        - trees
    BuildState:
      type: object
      properties:
        version:
          type: string
          description: Semantic version of the hostd build.
        commit:
          type: string
          description: Git commit hash of the build.
        os:
          type: string
          description: Operating system the host is running on.
        buildTime:
          type: string
          format: date-time
          description: Timestamp when the build was created.
      required:
        - version
        - commit
        - os
        - buildTime
    ExplorerState:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether the explorer data source is enabled.
        url:
          type: string
          description: Base URL of the explorer data source. Empty if not enabled.
      required:
        - enabled
    Announcement:
      type: object
      properties:
        index:
          $ref: "#/components/schemas/ChainIndex"
          description: Chain index at which the announcement was confirmed.
        address:
          type: string
          description: The host's announced network address.
      required:
        - index
        - address
    State:
      allOf:
        - $ref: "#/components/schemas/BuildState"
        - type: object
          properties:
            name:
              type: string
              nullable: true
              description: User-defined name of the host.
            publicKey:
              $ref: "#/components/schemas/PublicKey"
              description: Ed25519 public key of the host.
            lastAnnouncement:
              $ref: "#/components/schemas/Announcement"
              description: Most recent host announcement on the blockchain.
            startTime:
              type: string
              format: date-time
              description: Time the hostd process started.
            explorer:
              $ref: "#/components/schemas/ExplorerState"
              description: State of the explorer data source.
          required:
            - publicKey
            - lastAnnouncement
            - startTime
            - explorer
    ConsensusNetwork:
      type: object
      description: Parameters defining consensus behavior for the active network.
      properties:
        name:
          type: string
        initialCoinbase:
          $ref: "#/components/schemas/Currency"
        minimumCoinbase:
          $ref: "#/components/schemas/Currency"
        initialTarget:
          $ref: "#/components/schemas/BlockID"
        blockInterval:
          type: integer
          format: int64
          description: Target time between blocks as an integer number of nanoseconds.
        maturityDelay:
          type: integer
          format: int64
        hardforkDevAddr:
          type: object
          properties:
            height:
              type: integer
              format: int64
            oldAddress:
              $ref: "#/components/schemas/Address"
            newAddress:
              $ref: "#/components/schemas/Address"
          required:
            - height
            - oldAddress
            - newAddress
        hardforkTax:
          type: object
          properties:
            height:
              type: integer
              format: int64
          required:
            - height
        hardforkStorageProof:
          type: object
          properties:
            height:
              type: integer
              format: int64
          required:
            - height
        hardforkOak:
          type: object
          properties:
            height:
              type: integer
              format: int64
            fixHeight:
              type: integer
              format: int64
            genesisTimestamp:
              type: string
              format: date-time
          required:
            - height
            - fixHeight
            - genesisTimestamp
        hardforkASIC:
          type: object
          properties:
            height:
              type: integer
              format: int64
            oakTime:
              type: integer
              format: int64
              description: Difficulty adjustment window as an integer number of nanoseconds.
            oakTarget:
              $ref: "#/components/schemas/BlockID"
            nonceFactor:
              type: integer
              format: int64
          required:
            - height
            - oakTime
            - oakTarget
            - nonceFactor
        hardforkFoundation:
          type: object
          properties:
            height:
              type: integer
              format: int64
            primaryAddress:
              $ref: "#/components/schemas/Address"
            failsafeAddress:
              $ref: "#/components/schemas/Address"
          required:
            - height
            - primaryAddress
            - failsafeAddress
        hardforkV2:
          type: object
          properties:
            allowHeight:
              type: integer
              format: int64
            requireHeight:
              type: integer
              format: int64
            finalCutHeight:
              type: integer
              format: int64
          required:
            - allowHeight
            - requireHeight
            - finalCutHeight
      required:
        - name
        - initialCoinbase
        - minimumCoinbase
        - initialTarget
        - blockInterval
        - maturityDelay
        - hardforkDevAddr
        - hardforkTax
        - hardforkStorageProof
        - hardforkOak
        - hardforkASIC
        - hardforkFoundation
        - hardforkV2
    ConsensusState:
      type: object
      description: Snapshot of consensus state at a given tip.
      properties:
        index:
          $ref: "#/components/schemas/ChainIndex"
        prevTimestamps:
          type: array
          description: Recent block timestamps from newest to oldest.
          items:
            type: string
            format: date-time
          maxItems: 11
        depth:
          $ref: "#/components/schemas/BlockID"
        childTarget:
          $ref: "#/components/schemas/BlockID"
        siafundTaxRevenue:
          $ref: "#/components/schemas/Currency"
        oakTime:
          type: string
          description: Oak target window as a Go duration string.
        oakTarget:
          $ref: "#/components/schemas/BlockID"
        foundationSubsidyAddress:
          $ref: "#/components/schemas/Address"
        foundationManagementAddress:
          $ref: "#/components/schemas/Address"
        totalWork:
          $ref: "#/components/schemas/Work"
        difficulty:
          $ref: "#/components/schemas/Work"
        oakWork:
          $ref: "#/components/schemas/Work"
        elements:
          $ref: "#/components/schemas/ElementAccumulator"
        attestations:
          type: integer
          format: int64
      required:
        - index
        - prevTimestamps
        - depth
        - childTarget
        - siafundTaxRevenue
        - oakTime
        - oakTarget
        - foundationSubsidyAddress
        - foundationManagementAddress
        - totalWork
        - difficulty
        - oakWork
        - elements
        - attestations
    ConsensusCheckpointResponse:
      type: object
      properties:
        state:
          $ref: "#/components/schemas/ConsensusState"
          description: Consensus state at the specified block.
        block:
          type: object
          additionalProperties: true
          description: Full block at the specified block ID.
      required:
        - state
        - block
    SyncerConnectRequest:
      type: object
      properties:
        address:
          type: string
          description: Peer address in host:port form.
      required:
        - address
    Peer:
      type: object
      properties:
        address:
          type: string
          description: Network address of the connected peer.
        inbound:
          type: boolean
          description: Whether the peer initiated the connection.
        version:
          type: string
          description: Protocol version reported by the peer.
        firstSeen:
          type: string
          format: date-time
          nullable: true
          description: Time the peer was first seen.
        connectedSince:
          type: string
          format: date-time
          nullable: true
          description: Time the current connection was established.
        syncedBlocks:
          type: integer
          format: int64
          nullable: true
          description: Number of blocks synced from this peer in the current session.
        syncDuration:
          type: integer
          format: int64
          description: Total time spent syncing blocks from this peer in nanoseconds.
          nullable: true
      required:
        - address
        - inbound
        - version
    Alert:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/Hash256"
          description: Unique identifier for the alert.
        category:
          type: string
          description: Category used to group related alerts.
        severity:
          type: string
          enum: ["info", "warning", "error", "critical"]
          description: Severity level of the alert.
        message:
          type: string
          description: Human-readable message describing the alert.
        data:
          type: object
          additionalProperties: true
          nullable: true
          description: Arbitrary key-value data providing additional context.
        timestamp:
          type: string
          format: date-time
          description: Time the alert was registered.
      required:
        - id
        - category
        - severity
        - message
        - timestamp
    HostSettings:
      type: object
      properties:
        acceptingContracts:
          type: boolean
          description: Whether the host is accepting new contracts.
        netAddress:
          type: string
          description: Public hostname or IP address of the host. Must not include a port.
        maxContractDuration:
          type: integer
          format: int64
          description: Maximum allowed contract duration in blocks.
        windowSize:
          type: integer
          format: int64
          description: Storage proof window size in blocks.
        contractPrice:
          $ref: "#/components/schemas/Currency"
          description: One-time fee per contract formation in hastings.
        baseRPCPrice:
          $ref: "#/components/schemas/Currency"
          description: Base fee per RPC call in hastings.
        sectorAccessPrice:
          $ref: "#/components/schemas/Currency"
          description: Fee per sector access in hastings.
        collateralMultiplier:
          type: number
          format: double
          description: Multiplier applied to storage price to calculate collateral per byte per block.
        maxCollateral:
          $ref: "#/components/schemas/Currency"
          description: Maximum collateral the host will lock per contract in hastings.
        storagePrice:
          $ref: "#/components/schemas/Currency"
          description: Price per byte per block for storage in hastings.
        egressPrice:
          $ref: "#/components/schemas/Currency"
          description: Price per byte for download in hastings.
        ingressPrice:
          $ref: "#/components/schemas/Currency"
          description: Price per byte for upload in hastings.
        priceTableValidity:
          type: integer
          format: int64
          description: How long a price table remains valid in nanoseconds.
        maxRegistryEntries:
          type: integer
          format: int64
          description: Maximum number of registry entries the host will store.
        accountExpiry:
          type: integer
          format: int64
          description: Duration before an idle ephemeral account expires in nanoseconds.
        maxAccountBalance:
          $ref: "#/components/schemas/Currency"
          description: Maximum balance allowed in an ephemeral account in hastings.
        ingressLimit:
          type: integer
          format: int64
          description: Bandwidth limit for RHP ingress in bytes per second. 0 means unlimited.
        egressLimit:
          type: integer
          format: int64
          description: Bandwidth limit for RHP egress in bytes per second. 0 means unlimited.
        syncerIngressLimit:
          type: integer
          format: int64
          description: Bandwidth limit for syncer ingress in bytes per second. 0 means unlimited.
        syncerEgressLimit:
          type: integer
          format: int64
          description: Bandwidth limit for syncer egress in bytes per second. 0 means unlimited.
        ddns:
          $ref: "#/components/schemas/DNSSettings"
          description: Dynamic DNS configuration.
        sectorCacheSize:
          type: integer
          format: int64
          deprecated: true
          description: Deprecated. The sector cache was removed and the value is ignored.
        revision:
          type: integer
          format: int64
          description: Settings revision number managed by the caller.
      additionalProperties: false
    DNSSettings:
      type: object
      properties:
        provider:
          type: string
          description: DNS provider name (e.g. "cloudflare", "duckdns", "noip", "route53"). Empty disables DDNS.
        ipv4:
          type: boolean
          description: Whether to update the IPv4 DNS record.
        ipv6:
          type: boolean
          description: Whether to update the IPv6 DNS record.
        options:
          type: object
          nullable: true
          additionalProperties: true
          description: Provider-specific configuration options.
      additionalProperties: false
    Pin:
      type: object
      properties:
        pinned:
          type: boolean
          description: Whether this price is pinned to the external currency.
        value:
          type: number
          format: double
          description: Price in the external currency. Only used when pinned is true.
      required:
        - pinned
        - value
    PinnedSettings:
      type: object
      properties:
        currency:
          type: string
          description: Three-letter external currency code (e.g. "usd"). Required when any pin is enabled.
        threshold:
          type: number
          format: double
          description: Percentage threshold (0 to 1) that triggers a settings update when the exchange rate changes.
        storage:
          $ref: "#/components/schemas/Pin"
          description: Pinned storage price in the external currency per TB per month.
        ingress:
          $ref: "#/components/schemas/Pin"
          description: Pinned ingress price in the external currency per TB.
        egress:
          $ref: "#/components/schemas/Pin"
          description: Pinned egress price in the external currency per TB.
        maxCollateral:
          $ref: "#/components/schemas/Pin"
          description: Pinned maximum collateral in the external currency.
      required:
        - currency
        - threshold
        - storage
        - ingress
        - egress
        - maxCollateral
    Revenue:
      type: object
      properties:
        rpc:
          $ref: "#/components/schemas/Currency"
          description: Revenue from RPC fees in hastings.
        storage:
          $ref: "#/components/schemas/Currency"
          description: Revenue from storage fees in hastings.
        ingress:
          $ref: "#/components/schemas/Currency"
          description: Revenue from upload fees in hastings.
        egress:
          $ref: "#/components/schemas/Currency"
          description: Revenue from download fees in hastings.
        registryRead:
          $ref: "#/components/schemas/Currency"
          description: Revenue from registry read operations in hastings.
        registryWrite:
          $ref: "#/components/schemas/Currency"
          description: Revenue from registry write operations in hastings.
      required:
        - rpc
        - storage
        - ingress
        - egress
        - registryRead
        - registryWrite
    RevenueMetrics:
      type: object
      properties:
        potential:
          $ref: "#/components/schemas/Revenue"
          description: Revenue from active contracts that has not yet been confirmed.
        earned:
          $ref: "#/components/schemas/Revenue"
          description: Revenue that has been confirmed on the blockchain.
      required:
        - potential
        - earned
    AccountsMetrics:
      type: object
      properties:
        active:
          type: integer
          format: int64
          description: Number of active ephemeral accounts.
        balance:
          $ref: "#/components/schemas/Currency"
          description: Total balance across all active ephemeral accounts in hastings.
      required:
        - active
        - balance
    PricingMetrics:
      type: object
      properties:
        contractPrice:
          $ref: "#/components/schemas/Currency"
          description: Current contract formation price in hastings.
        ingressPrice:
          $ref: "#/components/schemas/Currency"
          description: Current ingress price per byte in hastings.
        egressPrice:
          $ref: "#/components/schemas/Currency"
          description: Current egress price per byte in hastings.
        baseRPCPrice:
          $ref: "#/components/schemas/Currency"
          description: Current base RPC fee in hastings.
        sectorAccessPrice:
          $ref: "#/components/schemas/Currency"
          description: Current sector access fee in hastings.
        storagePrice:
          $ref: "#/components/schemas/Currency"
          description: Current storage price per byte per block in hastings.
        collateralMultiplier:
          type: number
          format: double
          description: Current collateral multiplier applied to storage price.
      required:
        - contractPrice
        - ingressPrice
        - egressPrice
        - baseRPCPrice
        - sectorAccessPrice
        - storagePrice
        - collateralMultiplier
    ContractsMetrics:
      type: object
      properties:
        active:
          type: integer
          format: int64
          description: Number of active contracts.
        rejected:
          type: integer
          format: int64
          description: Number of rejected contracts.
        failed:
          type: integer
          format: int64
          description: Number of failed contracts.
        renewed:
          type: integer
          format: int64
          description: Number of renewed contracts.
        successful:
          type: integer
          format: int64
          description: Number of successfully completed contracts.
        lockedCollateral:
          $ref: "#/components/schemas/Currency"
          description: Total collateral locked in active contracts in hastings.
        riskedCollateral:
          $ref: "#/components/schemas/Currency"
          description: Total collateral at risk in active contracts in hastings.
      required:
        - active
        - rejected
        - failed
        - renewed
        - successful
        - lockedCollateral
        - riskedCollateral
    RegistryMetrics:
      type: object
      properties:
        entries:
          type: integer
          format: int64
          description: Current number of registry entries.
        maxEntries:
          type: integer
          format: int64
          description: Maximum number of registry entries allowed.
        reads:
          type: integer
          format: int64
          description: Total number of registry read operations.
        writes:
          type: integer
          format: int64
          description: Total number of registry write operations.
      required:
        - entries
        - maxEntries
        - reads
        - writes
    StorageMetrics:
      type: object
      properties:
        totalSectors:
          type: integer
          format: int64
          description: Total number of sector slots across all volumes.
        physicalSectors:
          type: integer
          format: int64
          description: Number of sectors physically stored on disk.
        lostSectors:
          type: integer
          format: int64
          description: Number of sectors lost due to failed volumes.
        contractSectors:
          type: integer
          format: int64
          description: Number of sectors associated with contracts.
        tempSectors:
          type: integer
          format: int64
          description: Number of temporary sectors not yet associated with contracts.
        reads:
          type: integer
          format: int64
          description: Total number of successful sector reads.
        writes:
          type: integer
          format: int64
          description: Total number of successful sector writes.
        readBytes:
          type: integer
          format: int64
          description: Total bytes read from disk.
        writeBytes:
          type: integer
          format: int64
          description: Total bytes written to disk.
        sectorCacheHits:
          type: integer
          format: int64
          deprecated: true
          description: Deprecated. The sector cache was removed and the counter is no longer updated.
        sectorCacheMisses:
          type: integer
          format: int64
          deprecated: true
          description: Deprecated. The sector cache was removed and the counter is no longer updated.
      required:
        - totalSectors
        - physicalSectors
        - lostSectors
        - contractSectors
        - tempSectors
        - reads
        - writes
        - readBytes
        - writeBytes
        - sectorCacheHits
        - sectorCacheMisses
    RHPData:
      type: object
      properties:
        ingress:
          type: integer
          format: int64
          description: Total bytes received in the period.
        egress:
          type: integer
          format: int64
          description: Total bytes sent in the period.
      required:
        - ingress
        - egress
    DataMetrics:
      type: object
      properties:
        rhp:
          $ref: "#/components/schemas/RHPData"
          description: Data transfer metrics for RHP traffic.
        syncer:
          $ref: "#/components/schemas/RHPData"
          description: Data transfer metrics for syncer traffic.
      required:
        - rhp
        - syncer
    WalletMetrics:
      type: object
      properties:
        balance:
          $ref: "#/components/schemas/Currency"
          description: Confirmed spendable wallet balance in hastings.
        immatureBalance:
          $ref: "#/components/schemas/Currency"
          description: Balance from immature outputs in hastings.
      required:
        - balance
        - immatureBalance
    Metrics:
      type: object
      properties:
        accounts:
          $ref: "#/components/schemas/AccountsMetrics"
          description: Ephemeral account metrics.
        revenue:
          $ref: "#/components/schemas/RevenueMetrics"
          description: Revenue metrics split by potential and earned.
        pricing:
          $ref: "#/components/schemas/PricingMetrics"
          description: Current host pricing settings.
        contracts:
          $ref: "#/components/schemas/ContractsMetrics"
          description: Contract status counts and collateral metrics.
        storage:
          $ref: "#/components/schemas/StorageMetrics"
          description: Storage usage and I/O metrics.
        registry:
          $ref: "#/components/schemas/RegistryMetrics"
          description: Registry usage metrics.
        data:
          $ref: "#/components/schemas/DataMetrics"
          description: Data transfer metrics.
        wallet:
          $ref: "#/components/schemas/WalletMetrics"
          description: Wallet balance metrics.
        timestamp:
          type: string
          format: date-time
          description: Timestamp the metrics were recorded at.
      required:
        - accounts
        - revenue
        - pricing
        - contracts
        - storage
        - registry
        - data
        - wallet
        - timestamp
    ContractFilter:
      type: object
      properties:
        statuses:
          type: array
          description: Filter by contract statuses.
          items:
            type: string
            enum: ["pending", "rejected", "active", "successful", "failed"]
        contractIDs:
          type: array
          description: Filter by specific contract IDs.
          items:
            $ref: "#/components/schemas/FileContractID"
        renewedFrom:
          type: array
          description: Filter by the contract ID this contract was renewed from.
          items:
            $ref: "#/components/schemas/FileContractID"
        renewedTo:
          type: array
          description: Filter by the contract ID this contract was renewed to.
          items:
            $ref: "#/components/schemas/FileContractID"
        renterKey:
          type: array
          description: Filter by renter public keys.
          items:
            $ref: "#/components/schemas/PublicKey"
        minNegotiationHeight:
          type: integer
          format: int64
          description: Minimum block height at which the contract was negotiated.
        maxNegotiationHeight:
          type: integer
          format: int64
          description: Maximum block height at which the contract was negotiated.
        minExpirationHeight:
          type: integer
          format: int64
          description: Minimum contract expiration block height.
        maxExpirationHeight:
          type: integer
          format: int64
          description: Maximum contract expiration block height.
        limit:
          type: integer
          minimum: 1
          maximum: 100
          description: Maximum number of contracts to return per page. Defaults to 100.
        offset:
          type: integer
          minimum: 0
          description: Number of contracts to skip for pagination.
        sortField:
          type: string
          description: 'Field to sort results by. Valid values are "status", "negotiationHeight", "expirationHeight".'
        sortDesc:
          type: boolean
          description: Sort in descending order when true.
      additionalProperties: false
    FileContractID:
      type: string
      pattern: "^fcid:[0-9a-fA-F]{64}$"
      description: File contract identifier.
    V2ContractFilter:
      type: object
      properties:
        statuses:
          type: array
          description: Filter by v2 contract statuses.
          items:
            type: string
            enum: ["pending", "rejected", "active", "renewed", "successful", "failed"]
        contractIDs:
          type: array
          description: Filter by specific contract IDs.
          items:
            $ref: "#/components/schemas/FileContractID"
        renewedFrom:
          type: array
          description: Filter by the contract ID this contract was renewed from.
          items:
            $ref: "#/components/schemas/FileContractID"
        renewedTo:
          type: array
          description: Filter by the contract ID this contract was renewed to.
          items:
            $ref: "#/components/schemas/FileContractID"
        renterKey:
          type: array
          description: Filter by renter public keys.
          items:
            $ref: "#/components/schemas/PublicKey"
        minNegotiationHeight:
          type: integer
          format: int64
          description: Minimum block height at which the contract was negotiated.
        maxNegotiationHeight:
          type: integer
          format: int64
          description: Maximum block height at which the contract was negotiated.
        minExpirationHeight:
          type: integer
          format: int64
          description: Minimum contract expiration block height.
        maxExpirationHeight:
          type: integer
          format: int64
          description: Maximum contract expiration block height.
        limit:
          type: integer
          minimum: 1
          maximum: 100
          description: Maximum number of v2 contracts to return per page. Defaults to 100.
        offset:
          type: integer
          minimum: 0
          description: Number of contracts to skip for pagination.
        sortField:
          type: string
          description: 'Field to sort results by. Valid values are "status", "negotiationHeight", "expirationHeight".'
        sortDesc:
          type: boolean
          description: Sort in descending order when true.
      additionalProperties: false
    ContractsResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of contracts matching the filter.
        contracts:
          type: array
          description: Contracts matching the filter for the current page.
          items:
            $ref: "#/components/schemas/Contract"
      required:
        - count
        - contracts
    V2ContractsResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of v2 contracts matching the filter.
        contracts:
          type: array
          description: V2 contracts matching the filter for the current page.
          items:
            $ref: "#/components/schemas/V2Contract"
      required:
        - count
        - contracts
    Contract:
      type: object
      description: Host contract metadata.
      additionalProperties: true
    V2Contract:
      type: object
      description: Host v2 contract metadata.
      additionalProperties: true
    IntegritySectorResult:
      type: object
      properties:
        expectedRoot:
          $ref: "#/components/schemas/Hash256"
          description: Expected Merkle root of the sector from the contract.
        actualRoot:
          $ref: "#/components/schemas/Hash256"
          description: Actual Merkle root calculated from the sector data on disk.
        error:
          type: string
          description: Error message if the sector could not be read. Omitted if readable.
      required:
        - expectedRoot
        - actualRoot
    IntegrityCheckResult:
      type: object
      properties:
        start:
          type: string
          format: date-time
          description: Time the integrity check started.
        end:
          type: string
          format: date-time
          description: Time the integrity check completed. Zero value if the check is still running.
        checkedSectors:
          type: integer
          format: int64
          description: Number of sectors that have been checked so far.
        totalSectors:
          type: integer
          format: int64
          description: Total number of sectors to check in the contract.
        badSectors:
          type: array
          description: List of sectors that failed the integrity check.
          items:
            $ref: "#/components/schemas/IntegritySectorResult"
      required:
        - start
        - checkedSectors
        - totalSectors
        - badSectors
    AddVolumeRequest:
      type: object
      properties:
        localPath:
          type: string
          description: Absolute filesystem path where the volume data will be stored.
        maxSectors:
          type: integer
          format: int64
          description: Initial number of sectors the volume can store. Each sector is 4 MiB.
      required:
        - localPath
        - maxSectors
    UpdateVolumeRequest:
      type: object
      properties:
        readOnly:
          type: boolean
          description: Whether the volume should be read-only. A read-only volume will not accept new sectors.
      required:
        - readOnly
    ResizeVolumeRequest:
      type: object
      properties:
        maxSectors:
          type: integer
          format: int64
          description: New maximum number of sectors for the volume. Each sector is 4 MiB.
      required:
        - maxSectors
    Volume:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the volume.
        localPath:
          type: string
          description: Absolute filesystem path of the volume data.
        usedSectors:
          type: integer
          format: int64
          description: Number of sectors currently stored in the volume.
        totalSectors:
          type: integer
          format: int64
          description: Maximum number of sectors the volume can store.
        readOnly:
          type: boolean
          description: Whether the volume is read-only.
        available:
          type: boolean
          description: Whether the volume is currently available for I/O operations.
      required:
        - id
        - localPath
        - usedSectors
        - totalSectors
        - readOnly
        - available
    VolumeStats:
      type: object
      properties:
        failedReads:
          type: integer
          format: int64
          description: Number of failed sector read operations.
        failedWrites:
          type: integer
          format: int64
          description: Number of failed sector write operations.
        successfulReads:
          type: integer
          format: int64
          description: Number of successful sector read operations.
        successfulWrites:
          type: integer
          format: int64
          description: Number of successful sector write operations.
        corruptSectors:
          type: integer
          format: int64
          description: Number of sectors that failed to verify against their root while being read.
        status:
          type: string
          description: Current volume status (unavailable, creating, resizing, removing, ready).
        errors:
          type: array
          items:
            type: string
          nullable: true
          description: Recent error messages from volume operations.
    VolumeMeta:
      allOf:
        - $ref: "#/components/schemas/Volume"
        - $ref: "#/components/schemas/VolumeStats"
    SectorReference:
      type: object
      properties:
        contracts:
          type: array
          description: List of contract IDs that reference this sector.
          items:
            $ref: "#/components/schemas/FileContractID"
        tempStorage:
          type: integer
          format: int64
          description: Number of temporary storage references to this sector.
      required:
        - contracts
        - tempStorage
    VerifySectorResponse:
      allOf:
        - $ref: "#/components/schemas/SectorReference"
        - type: object
          properties:
            error:
              type: string
              nullable: true
              description: Error message if the sector data failed verification. Null if valid.
    WalletResponse:
      type: object
      properties:
        spendable:
          $ref: "#/components/schemas/Currency"
          description: Spendable wallet balance in hastings.
        confirmed:
          $ref: "#/components/schemas/Currency"
          description: Total confirmed wallet balance in hastings.
        unconfirmed:
          $ref: "#/components/schemas/Currency"
          description: Unconfirmed wallet balance in hastings.
        immature:
          $ref: "#/components/schemas/Currency"
          description: Immature wallet balance in hastings.
        address:
          $ref: "#/components/schemas/Address"
          description: The host wallet's Siacoin address.
      required:
        - spendable
        - confirmed
        - unconfirmed
        - immature
        - address
    WalletEvent:
      type: object
      description: Wallet event record with type-specific payload.
      additionalProperties: true
    WalletSendSiacoinsRequest:
      type: object
      properties:
        address:
          $ref: "#/components/schemas/Address"
          description: Recipient's Siacoin address.
        amount:
          $ref: "#/components/schemas/Currency"
          description: Amount of hastings to send.
        subtractMinerFee:
          type: boolean
          description: If true, the estimated miner fee is subtracted from the amount instead of added on top.
      required:
        - address
        - amount
    SystemDirResponse:
      type: object
      properties:
        path:
          type: string
          description: Absolute path of the inspected directory.
        totalBytes:
          type: integer
          format: int64
          description: Total disk space on the volume containing the path in bytes.
        freeBytes:
          type: integer
          format: int64
          description: Available disk space on the volume containing the path in bytes.
        directories:
          type: array
          description: Subdirectory names in the inspected directory.
          items:
            type: string
      required:
        - path
        - directories
    CreateDirRequest:
      type: object
      properties:
        path:
          type: string
          description: Absolute filesystem path of the directory to create.
      required:
        - path
    BackupRequest:
      type: object
      properties:
        path:
          type: string
          description: Absolute filesystem path where the backup file will be written.
      required:
        - path
    RHP4Result:
      type: object
      properties:
        netAddress:
          type: string
          description: Protocol and address that was tested.
        resolvedAddresses:
          type: array
          description: IP addresses the hostname resolved to.
          items:
            type: string
        connected:
          type: boolean
          description: Whether a TCP/UDP connection was established.
        dialTime:
          type: integer
          format: int64
          description: Time to establish the connection in nanoseconds.
        handshake:
          type: boolean
          description: Whether the protocol handshake completed.
        handshakeTime:
          type: integer
          format: int64
          description: Time to complete the handshake in nanoseconds.
        scanned:
          type: boolean
          description: Whether the host settings were successfully retrieved.
        scanTime:
          type: integer
          format: int64
          description: Time to retrieve host settings in nanoseconds.
        settings:
          type: object
          nullable: true
          additionalProperties: true
          description: Host settings returned during the scan. Null if the scan failed.
        errors:
          type: array
          description: Errors encountered during the connectivity test.
          items:
            type: string
          nullable: true
        warnings:
          type: array
          description: Warnings encountered during the connectivity test.
          items:
            type: string
          nullable: true
      required:
        - netAddress
        - resolvedAddresses
        - connected
        - handshake
        - scanned
    TestResult:
      type: object
      properties:
        publicKey:
          $ref: "#/components/schemas/PublicKey"
          description: Public key of the host that was tested.
        version:
          type: string
          description: Explorer API version used for the test.
        rhp4:
          type: array
          description: Results for each RHP4 protocol and address tested.
          items:
            $ref: "#/components/schemas/RHP4Result"
      required:
        - publicKey
        - version
        - rhp4
    RegisterWebHookRequest:
      type: object
      properties:
        callbackURL:
          type: string
          format: uri
          description: URL that will receive webhook event POST requests.
        scopes:
          type: array
          description: Event scopes to subscribe to.
          items:
            type: string
      required:
        - callbackURL
        - scopes
    Webhook:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the webhook.
        callbackURL:
          type: string
          format: uri
          description: URL that receives webhook event POST requests.
        secretKey:
          type: string
          description: Secret key used for webhook request authentication via HTTP Basic Auth.
        scopes:
          type: array
          description: Event scopes the webhook is subscribed to.
          items:
            type: string
      required:
        - id
        - callbackURL
        - secretKey
        - scopes