SwarmDebug.yaml

openapi: 3.0.3
info:
  version: 1.1.1
  title: Bee Debug API
  description: "A list of the currently provided debug interfaces to interact with the bee node"

security:
  - {}

externalDocs:
  description: Browse the documentation @ the Swarm Docs
  url: "https://docs.ethswarm.org"

servers:
  - url: "http://{apiRoot}:{port}"
    variables:
      apiRoot:
        default: "localhost"
        description: Base address of the local bee node debug API
      port:
        default: "1635"
        description: Service port provided in bee node config

paths:
  "/addresses":
    get:
      summary: Get overlay and underlay addresses of the node
      tags:
        - Connectivity
      responses:
        "200":
          description: Own node underlay and overlay addresses
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Addresses"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/balances":
    get:
      summary: Get the balances with all known peers including prepaid services
      tags:
        - Balance
      responses:
        "200":
          description: Own balances with all known peers
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Balances"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/balances/{address}":
    get:
      summary: Get the balances with a specific peer including prepaid services
      tags:
        - Balance
      parameters:
        - in: path
          name: address
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
          required: true
          description: Swarm address of peer
      responses:
        "200":
          description: Balance with the specific peer
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Balance"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/blocklist":
    get:
      summary: Get a list of blocklisted peers
      tags:
        - Connectivity
      responses:
        "200":
          description: Returns overlay addresses of blocklisted peers
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Peers"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/consumed":
    get:
      summary: Get the past due consumption balances with all known peers
      tags:
        - Balance
      responses:
        "200":
          description: Own past due consumption balances with all known peers
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Balances"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/consumed/{address}":
    get:
      summary: Get the past due consumption balance with a specific peer
      tags:
        - Balance
      parameters:
        - in: path
          name: address
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
          required: true
          description: Swarm address of peer
      responses:
        "200":
          description: Past-due consumption balance with the specific peer
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Balance"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/chequebook/address":
    get:
      summary: Get the address of the chequebook contract used
      tags:
        - Chequebook
      responses:
        "200":
          description: Ethereum address of chequebook contract
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ChequebookAddress"

  "/chequebook/balance":
    get:
      summary: Get the balance of the chequebook
      tags:
        - Chequebook
      responses:
        "200":
          description: Balance of the chequebook
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ChequebookBalance"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/chunks/{address}":
    get:
      summary: Check if chunk at address exists locally
      tags:
        - Chunk
      parameters:
        - in: path
          name: address
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
          required: true
          description: Swarm address of chunk
      responses:
        "200":
          description: Chunk exists
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Response"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        default:
          description: Default response
    delete:
      summary: Delete a chunk from local storage
      tags:
        - Chunk
      parameters:
        - in: path
          name: address
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
          required: true
          description: Swarm address of chunk
      responses:
        "200":
          description: Chunk exists
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Response"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        default:
          description: Default response

  "/connect/{multiAddress}":
    post:
      summary: Connect to address
      tags:
        - Connectivity
      parameters:
        - in: path
          allowReserved: true
          name: multiAddress
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/MultiAddress"
          required: true
          description: Underlay address of peer
      responses:
        "200":
          description: Returns overlay address of connected peer
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Address"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/reservestate":
    get:
      summary: Get reserve state
      tags:
        - Status
      responses:
        "200":
          description: Reserve State
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ReserveState"
        default:
          description: Default response

  "/chainstate":
    get:
      summary: Get chain state
      tags:
        - Status
      responses:
        "200":
          description: Chain State
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ChainState"
        default:
          description: Default response

  "/health":
    get:
      summary: Get health of node
      tags:
        - Status
      responses:
        "200":
          description: Health State of node
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Status"
        default:
          description: Default response

  "/peers":
    get:
      summary: Get a list of peers
      tags:
        - Connectivity
      responses:
        "200":
          description: Returns overlay addresses of connected peers
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Peers"
        default:
          description: Default response

  "/peers/{address}":
    delete:
      summary: Remove peer
      tags:
        - Connectivity
      parameters:
        - in: path
          name: address
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
          required: true
          description: Swarm address of peer
      responses:
        "200":
          description: Disconnected peer
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Response"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/pingpong/{peer-id}":
    post:
      summary: Try connection to node
      tags:
        - Connectivity
      parameters:
        - in: path
          name: peer-id
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
          required: true
          description: Swarm address of peer
      responses:
        "200":
          description: Returns round trip time for given peer
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/RttMs"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/readiness":
    get:
      summary: Get readiness state of node
      tags:
        - Status
      responses:
        "200":
          description: Health State of node
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Status"
        default:
          description: Default response

  "/settlements/{address}":
    get:
      summary: Get amount of sent and received from settlements with a peer
      tags:
        - Settlements
      parameters:
        - in: path
          name: address
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
          required: true
          description: Swarm address of peer
      responses:
        "200":
          description: Amount of sent or received from settlements with a peer
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Settlement"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/settlements":
    get:
      summary: Get settlements with all known peers and total amount sent or received
      tags:
        - Settlements
      responses:
        "200":
          description: Settlements with all known peers and total amount sent or received
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Settlements"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/timesettlements":
    get:
      summary: Get time based settlements with all known peers and total amount sent or received
      tags:
        - Settlements
      responses:
        "200":
          description: Time based settlements with all known peers and total amount sent or received
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Settlements"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/topology":
    get:
      description: Get topology of known network
      tags:
        - Connectivity
      responses:
        "200":
          description: Swarm topology of the bee node
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/BzzTopology"

  "/welcome-message":
    get:
      summary: Get configured P2P welcome message
      tags:
        - Connectivity
      responses:
        "200":
          description: Welcome message
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/WelcomeMessage"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response
    post:
      summary: Set P2P welcome message
      tags:
        - Connectivity
      requestBody:
        content:
          application/json:
            schema:
              $ref: "SwarmCommon.yaml#/components/schemas/WelcomeMessage"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Status"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/chequebook/cashout/{peer-id}":
    get:
      summary: Get last cashout action for the peer
      parameters:
        - in: path
          name: peer-id
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
          required: true
          description: Swarm address of peer
      tags:
        - Chequebook
      responses:
        "200":
          description: Cashout status
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/SwapCashoutStatus"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response
    post:
      summary: Cashout the last cheque for the peer
      parameters:
        - in: path
          name: peer-id
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
          required: true
          description: Swarm address of peer
        - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter"
      tags:
        - Chequebook
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/TransactionResponse"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "429":
          $ref: "SwarmCommon.yaml#/components/responses/429"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/chequebook/cheque/{peer-id}":
    get:
      summary: Get last cheques for the peer
      parameters:
        - in: path
          name: peer-id
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
          required: true
          description: Swarm address of peer
      tags:
        - Chequebook
      responses:
        "200":
          description: Last cheques
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ChequePeerResponse"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/chequebook/cheque":
    get:
      summary: Get last cheques for all peers
      tags:
        - Chequebook
      responses:
        "200":
          description: Last cheques
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ChequeAllPeersResponse"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/chequebook/deposit":
    post:
      summary: Deposit tokens from overlay address into chequebook
      parameters:
        - in: query
          name: amount
          schema:
            type: integer
          required: true
          description: amount of tokens to deposit
        - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter"
      tags:
        - Chequebook
      responses:
        "201":
          description: Transaction hash of the deposit transaction
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/TransactionResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/chequebook/withdraw":
    post:
      summary: Withdraw tokens from the chequebook to the overlay address
      parameters:
        - in: query
          name: amount
          schema:
            type: integer
          required: true
          description: amount of tokens to withdraw
        - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter"
      tags:
        - Chequebook
      responses:
        "201":
          description: Transaction hash of the withdraw transaction
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/TransactionResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/tags/{uid}":
    get:
      summary: "Get Tag information using Uid"
      tags:
        - Tag
      parameters:
        - in: path
          name: uid
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/Uid"
          required: true
          description: Uid
      responses:
        "200":
          description: Tag info
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/NewTagDebugResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/transactions":
    get:
      summary: Get list of pending transactions      
      tags:
        - Transaction
      responses:
        "200":
          description: List of pending transactions
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/PendingTransactionReponse"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/transactions/{txHash}":
    get:
      summary: Get information about a sent transaction
      parameters:
        - in: path
          name: txHash
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/TransactionHash"
          required: true
          description: Hash of the transaction
      tags:
        - Transaction
      responses:
        "200":
          description: Get info about transaction
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/TransactionInfoResponse"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response
    post:
      summary: Rebroadcast existing transaction
      parameters:
        - in: path
          name: txHash
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/TransactionHash"
          required: true
          description: Hash of the transaction
      tags:
        - Transaction
      responses:
        "200":
          description: Hash of the transaction
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/TransactionResponse"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response
    delete:
      summary: Cancel existing transaction
      parameters:
        - in: path
          name: txHash
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/TransactionHash"
          required: true
          description: Hash of the transaction
        - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter"
      tags:
        - Transaction
      responses:
        "200":
          description: Hash of the transaction
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/TransactionResponse"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/stamps":
    get:
      summary: Get all available stamps for this node
      tags:
        - Postage Stamps
      responses:
        "200":
          description: Returns an array of all available postage batches.
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/DebugPostageBatchesResponse"

        default:
          description: Default response

  "/stamps/{id}":
    parameters:
      - in: path
        name: id
        schema:
          $ref: "SwarmCommon.yaml#/components/schemas/BatchID"
        required: true
        description: Swarm address of the stamp
    get:
      summary: Get an individual postage batch status
      tags:
        - Postage Stamps
      responses:
        "200":
          description: Returns an individual postage batch state
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/DebugPostageBatch"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        default:
          description: Default response

  "/stamps/{id}/buckets":
    parameters:
      - in: path
        name: id
        schema:
          $ref: "SwarmCommon.yaml#/components/schemas/BatchID"
        required: true
        description: Swarm address of the stamp
    get:
      summary: Get extended bucket data of a batch
      tags:
        - Postage Stamps
      responses:
        "200":
          description: Returns extended bucket data of the provided batch ID
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/PostageStampBuckets"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        default:
          description: Default response

  "/stamps/{amount}/{depth}":
    post:
      summary: Buy a new postage batch.
      description: Be aware, this endpoint creates an on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance!
      tags:
        - Postage Stamps
      parameters:
        - in: path
          name: amount
          schema:
            type: integer
          required: true
          description: Amount of BZZ added that the postage batch will have.
        - in: path
          name: depth
          schema:
            type: integer
          required: true
          description: Batch depth which specifies how many chunks can be signed with the batch. It is a logarithm. Must be higher than default bucket depth (16)
        - in: query
          name: label
          schema:
            type: string
          required: false
          description: An optional label for this batch
        - in: header
          name: immutable
          schema:
            type: boolean
          required: false
        - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter"
      responses:
        "201":
          description: Returns the newly created postage batch ID
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/BatchIDResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "429":
          $ref: "SwarmCommon.yaml#/components/responses/429"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/stamps/topup/{id}/{amount}":
    patch:
      summary: Top up an existing postage batch.
      description: Be aware, this endpoint creates on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance!
      tags:
        - Postage Stamps
      parameters:
        - in: path
          name: id
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/BatchID"
          required: true
          description: Batch ID to top up
        - in: path
          name: amount
          schema:
            type: integer
          required: true
          description: Amount of BZZ per chunk to top up to an existing postage batch.
      responses:
        "202":
          description: Returns the postage batch ID that was topped up
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/BatchIDResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "429":
          $ref: "SwarmCommon.yaml#/components/responses/429"
        "402":
          $ref: "SwarmCommon.yaml#/components/responses/402"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/stamps/dilute/{id}/{depth}":
    patch:
      summary: Dilute an existing postage batch.
      description: Be aware, this endpoint creates on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance!
      tags:
        - Postage Stamps
      parameters:
        - in: path
          name: id
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/BatchID"
          required: true
          description: Swarm address of the stamp
        - in: path
          name: depth
          schema:
            type: integer
          required: true
          description: New batch depth. Must be higher than the previous depth.
      responses:
        "202":
          description: Returns the postage batch ID that was diluted.
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/BatchIDResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "429":
          $ref: "SwarmCommon.yaml#/components/responses/429"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response