openapi: 3.0.3

info:
  version: 7.4.1
  title: Bee API
  description: "API endpoints for interacting with the Swarm network, supporting file operations, messaging, and node management"

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

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

paths:
  "/grantee":
    post:
      summary: "Create a grantee list"
      tags:
        - ACT
      parameters:
        - in: header
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
          name: swarm-postage-batch-id
          required: true
        - in: header
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter"
          name: swarm-tag
          required: false
        - in: header
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter"
          name: swarm-pin
          required: false
        - in: header
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload"
          name: swarm-deferred-upload
          required: false
        - in: header
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
          name: swarm-act-history-address
          required: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "SwarmCommon.yaml#/components/schemas/ActGranteesCreateRequest"
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ActGranteesOperationResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"

  "/grantee/{reference}":
    get:
      summary: "Get the grantee list"
      tags:
        - ACT
      parameters:
        - in: path
          name: reference
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmEncryptedReference"
          required: true
          description: Grantee list reference
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "SwarmCommon.yaml#/components/schemas/PublicKey"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
    patch:
      summary: "Update the grantee list"
      description: "Add or remove grantees from an existing grantee list"
      tags:
        - ACT
      parameters:
        - in: path
          name: reference
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmEncryptedReference"
          required: true
          description: Grantee list reference
        - in: header
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
          name: swarm-act-history-address
          required: true
        - in: header
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
          name: swarm-postage-batch-id
          required: true
        - in: header
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter"
          name: swarm-tag
          required: false
        - in: header
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter"
          name: swarm-pin
          required: false
        - in: header
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload"
          name: swarm-deferred-upload
          required: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "SwarmCommon.yaml#/components/schemas/ActGranteesPatchRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ActGranteesOperationResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"

  "/bytes":
    post:
      summary: "Upload data"
      tags:
        - Bytes
      parameters:
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmEncryptParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter"
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "201":
          description: OK
          headers:
            "swarm-tag":
              $ref: "SwarmCommon.yaml#/components/headers/SwarmTag"
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ReferenceResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "402":
          $ref: "SwarmCommon.yaml#/components/responses/402"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/bytes/{reference}":
    get:
      summary: "Retrieve data by reference"
      tags:
        - Bytes
      parameters:
        - in: path
          name: reference
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference"
          required: true
          description: Swarm address reference to content
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyStrategyParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
      responses:
        "200":
          description: Retrieved content specified by reference
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        default:
          description: Default response
    head:
      summary: Retrieve headers containing the content type and length for the reference
      tags:
        - Bytes
      parameters:
        - in: path
          name: address
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
          required: true
          description: Swarm address of chunk
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
      responses:
        "200":
          description: The chunk exists.
          headers:
            Content-Type:
              description: The MIME type of the resource (e.g., application/octet-stream).
              schema:
                type: string
                example: application/octet-stream
            Content-Length:
              description: The size of the chunk in bytes.
              schema:
                type: integer
                example: 1024
            Access-Control-Expose-Headers:
              description: Headers exposed for CORS.
              schema:
                type: string
                example: Accept-Ranges, Content-Encoding
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        default:
          description: Default response

  "/chunks":
    post:
      summary: "Upload a chunk"
      tags:
        - Chunk
      parameters:
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter"
        - in: header
          name: swarm-postage-batch-id
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
          required: false
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageStamp"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
      requestBody:
        description: Chunk binary data containing at least 8 bytes.
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "201":
          description: OK
          headers:
            "swarm-tag":
              description: Tag UID from the request `swarm-tag` header if provided.
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Uid"
            "swarm-act-history-address":
              $ref: "SwarmCommon.yaml#/components/headers/SwarmActHistoryAddress"
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ReferenceResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "402":
          $ref: "SwarmCommon.yaml#/components/responses/402"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/chunks/stream":
    get:
      summary: "Stream chunks for upload"
      description: "Establishes a WebSocket connection for streaming chunks. Each uploaded chunk receives a binary acknowledgment (`0`). Chunks are sent as binary messages. When a tag is specified, chunks are stored locally and uploaded to the network after the stream closes. Without a tag, chunks are directly uploaded to the network as they arrive."
      tags:
        - Chunk
      parameters:
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
      responses:
        "200":
          description: "Connection established"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        default:
          description: Default response
  "/bzz":
    post:
      summary: "Upload a file or collection of files"
      description:
        "Upload single files or collections of files. To upload a collection, send a multipart request with files in the form data with appropriate headers. Tar files can be uploaded with the `swarm-collection` header to extract and upload the directory structure. Without the `swarm-collection` header, requests are treated as single file uploads. Multipart requests are always treated as collections; use the `swarm-index-document` header to specify a single file to serve."
      tags:
        - BZZ
      parameters:
        - in: query
          name: name
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/FileName"
          required: false
          description: Filename when uploading single file
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmEncryptParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/ContentTypePreserved"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCollection"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmIndexDocumentParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmErrorDocumentParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                file:
                  type: array
                  items:
                    type: string
                    format: binary
          application/octet-stream:
            schema:
              type: string
              format: binary
          application/x-tar:
            schema:
              type: string
              format: binary
      responses:
        "201":
          description: OK
          headers:
            "swarm-tag":
              $ref: "SwarmCommon.yaml#/components/headers/SwarmTag"
            "etag":
              $ref: "SwarmCommon.yaml#/components/headers/ETag"
            "swarm-act-history-address":
              $ref: "SwarmCommon.yaml#/components/headers/SwarmActHistoryAddress"
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ReferenceResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "402":
          $ref: "SwarmCommon.yaml#/components/responses/402"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/bzz/{reference}":
    get:
      summary: "Retrieve a file or index document from a collection"
      tags:
        - BZZ
      parameters:
        - in: path
          name: reference
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference"
          required: true
          description: Swarm address of content
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyStrategyParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
      responses:
        "200":
          description: OK
          # "swarm-feed-index":
          #   $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedIndex"
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            "swarm-feed-resolved-version":
              $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedResolvedVersion"


        "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
    head:
      summary: Retrieve headers with content type and length for the reference
      tags:
        - BZZ
      parameters:
        - in: path
          name: address
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
          required: true
          description: Swarm address of chunk
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
      responses:
        "200":
          description: Chunk exists
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        default:
          description: Default response

  "/bzz/{reference}/{path}":
    get:
      summary: "Retrieve a file from a collection by path"
      tags:
        - BZZ
      parameters:
        - in: path
          name: reference
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference"
          required: true
          description: Swarm address of content
        - in: path
          name: path
          schema:
            type: string
          required: true
          description: Path to the file in the collection.
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyStrategyParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter"
      responses:
        "200":
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            "swarm-feed-resolved-version":
              $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedResolvedVersion"

        "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

  "/tags":
    get:
      summary: Get list of tags
      tags:
        - Tag
      parameters:
        - in: query
          name: offset
          schema:
            type: integer
            minimum: 0
            default: 0
          required: false
          description: The number of items to skip before starting to collect the result set.
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
          required: false
          description: The numbers of items to return.
      responses:
        "200":
          description: List of tags
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/TagsList"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response
    post:
      summary: "Create Tag"
      tags:
        - Tag
      description: Tags can be thought of as upload sessions which can be tracked using the tags endpoint. It will keep track of the chunks that are uploaded as part of the tag and will push them out to the network once a done split is called on the Tag. This happens internally if you use the `Swarm-Deferred-Upload` header.
      responses:
        "201":
          description: New Tag Info
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/NewTagResponse"

        "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/NewTagResponse"
        "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
    delete:
      summary: "Delete Tag information using Uid"
      tags:
        - Tag
      parameters:
        - in: path
          name: uid
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/Uid"
          required: true
          description: Uid
      responses:
        "204":
          $ref: "SwarmCommon.yaml#/components/responses/204"
        "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
    patch:
      summary: "Update Total Count and swarm hash for a tag of an input stream of unknown size using Uid"
      tags:
        - Tag
      parameters:
        - in: path
          name: uid
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/Uid"
          required: true
          description: Uid
      requestBody:
        description: Can contain swarm hash to use for the tag
        required: false
        content:
          application/json:
            schema:
              $ref: "SwarmCommon.yaml#/components/schemas/Address"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Response"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/pins/{reference}":
    parameters:
      - in: path
        name: reference
        schema:
          $ref: "SwarmCommon.yaml#/components/schemas/SwarmOnlyReference"
        required: true
        description: Swarm reference of the root hash
    post:
      summary: Pin a root hash by reference
      tags:
        - Pinning
      responses:
        "200":
          description: Pin already exists
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Response"
        "201":
          description: New pin with root reference was created
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Response"
        "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
    delete:
      summary: Unpin a root hash by reference
      tags:
        - Pinning
      responses:
        "200":
          description: Root hash has been unpinned
          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
    get:
      summary: Get the pinning status of a root hash
      tags:
        - Pinning
      responses:
        "200":
          description: The pinned root hash reference
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/SwarmOnlyReference"
        "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

  "/pins":
    get:
      summary: Get the list of pinned root hash references
      tags:
        - Pinning
      responses:
        "200":
          description: List of pinned root hash references
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/SwarmOnlyReferencesList"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/pins/check":
    get:
      summary: Validate pinned chunks integrity
      tags:
        - Pinning
      parameters:
        - in: query
          name: ref
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmOnlyReference"
          required: false
          description: Optional reference to check; if not provided, all pinned references are checked
      responses:
        "200":
          description: List of checked root hash references
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/PinCheckResponse"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/pss/send/{topic}/{targets}":
    post:
      summary: Send a message using the Postal Service for Swarm
      tags:
        - Postal Service for Swarm
      parameters:
        - in: path
          name: topic
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/PssTopic"
          required: true
          description: Topic name
        - in: path
          name: targets
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/PssTargets"
          required: true
          description: Target message address prefix. If multiple targets are specified, only one would be matched.
        - in: query
          name: recipient
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/PssRecipient"
          required: false
          description: Recipient publickey
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
      responses:
        "201":
          description: Subscribed to topic
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "402":
          $ref: "SwarmCommon.yaml#/components/responses/402"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/pss/subscribe/{topic}":
    get:
      summary: Subscribe to messages on a topic
      tags:
        - Postal Service for Swarm
      parameters:
        - in: path
          name: topic
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/PssTopic"
          required: true
          description: Topic name
      responses:
        "200":
          description: Establishes a WebSocket subscription for incoming messages on the topic
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/gsoc/subscribe/{address}":
    get:
      summary: Subscribe to GSOC payloads
      tags:
        - GSOC
      parameters:
        - in: path
          name: reference
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference"
          required: true
          description: "Single Owner Chunk address (which may have multiple payloads)"
      responses:
        "200":
          description: Establishes a WebSocket subscription for incoming messages on the Single Owner Chunk address
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/soc/{owner}/{id}":
    post:
      summary: Upload a Single Owner Chunk
      tags:
        - Single owner chunk
      parameters:
        - in: path
          name: owner
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress"
          required: true
          description: Ethereum address of the chunk owner
        - in: path
          name: id
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/HexString"
          required: true
          description: Unique identifier for the chunk
        - in: query
          name: sig
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/HexString"
          required: true
          description: Signature
        - in: header
          name: swarm-postage-batch-id
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
          required: true
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageStamp"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
      requestBody:
        required: true
        description: The SOC binary data, composed of the span (8 bytes) and up to 4KB of payload.
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ReferenceResponse"
          headers:
            "swarm-act-history-address":
              $ref: "SwarmCommon.yaml#/components/headers/SwarmActHistoryAddress"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "401":
          $ref: "SwarmCommon.yaml#/components/responses/401"
        "402":
          $ref: "SwarmCommon.yaml#/components/responses/402"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response
    get:
      summary: Retrieve Single Owner Chunk data
      tags:
        - Single owner chunk
      parameters:
        - in: path
          name: owner
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress"
          required: true
          description: Ethereum address of the Owner of the SOC
        - in: path
          name: id
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/HexString"
          required: true
          description: Unique identifier for the chunk data
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmOnlyRootChunkParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyStrategyParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter"
      responses:
        "200":
          description: Related Single Owner Chunk data
          headers:
            "swarm-soc-signature":
              $ref: "SwarmCommon.yaml#/components/headers/SwarmSocSignature"
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "401":
          $ref: "SwarmCommon.yaml#/components/responses/401"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/feeds/{owner}/{topic}":
    post:
      summary: Create a feed root manifest
      tags:
        - Feed
      parameters:
        - in: path
          name: owner
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress"
          required: true
          description: Ethereum address of the feed owner
        - in: path
          name: topic
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/HexString"
          required: true
          description: Topic identifier for the feed
        - in: query
          name: type
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/FeedType"
          required: false
          description: "Feed indexing scheme (default: sequence)"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ReferenceResponse"
          headers:
            "swarm-act-history-address":
              $ref: "SwarmCommon.yaml#/components/headers/SwarmActHistoryAddress"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "401":
          $ref: "SwarmCommon.yaml#/components/responses/401"
        "402":
          $ref: "SwarmCommon.yaml#/components/responses/402"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response
    get:
      summary: Retrieve the latest feed update
      tags:
        - Feed
      parameters:
        - in: path
          name: owner
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress"
          required: true
          description: Ethereum address of the feed owner
        - in: path
          name: topic
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/HexString"
          required: true
          description: Topic identifier for the feed
        - in: query
          name: at
          schema:
            type: integer
          required: false
          description: "Timestamp of the update (default: now)"
        - in: query
          name: after
          schema:
            type: integer
          required: false
          description: "Start index (default: 0)"
        - in: query
          name: type
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/FeedType"
          required: false
          description: "Feed indexing scheme (default: sequence)"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmOnlyRootChunkParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyStrategyParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter"
      responses:
        "200":
          description: Latest feed update
          headers:
            "swarm-soc-signature":
              $ref: "SwarmCommon.yaml#/components/headers/SwarmSocSignature"
            "swarm-feed-index":
              $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedIndex"
            "swarm-feed-index-next":
              $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedIndexNext"
            "swarm-feed-resolved-version":
              $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedResolvedVersion"

          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "401":
          $ref: "SwarmCommon.yaml#/components/responses/401"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/stewardship/{reference}":
    get:
      summary: "Check content availability"
      tags:
        - Stewardship
      parameters:
        - in: path
          name: reference
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference"
          required: true
          description: "Root hash of content (can be of any type: collection, file, chunk)"
      responses:
        "200":
          description: Returns if the content is retrievable
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/IsRetrievableResponse"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response
    put:
      summary: "Re-upload content by reference"
      tags:
        - Stewardship
      parameters:
        - in: path
          name: reference
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference"
          required: true
          description: "Re-uploads content for specified root hash (can be of any type: collection, file, chunk, etc.)"
        - in: header
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
          name: swarm-postage-batch-id
          description: Postage batch to use for re-upload. If none is provided and the file was uploaded on the same node before, it will reuse the same batch. If not found, it will return error. If a new batch is provided, the chunks are stamped again with the new batch.
      responses:
        "200":
          description: OK
        "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

  "/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

  "/health":
    get:
      summary: Get the overall health status of the node
      description: |
        Health Status will indicate node healthiness.

        If node is unhealthy please check node logs for errors.
      tags:
        - Status
      responses:
        "200":
          description: Health Status of node
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/HealthStatus"
        default:
          description: Default response

  "/readiness":
    get:
      summary: Check if the node is ready to accept traffic
      tags:
        - Status
      responses:
        "200":
          description: Indicates that node is ready
          $ref: "SwarmCommon.yaml#/components/responses/200"
        "400":
          description: Indicates that node is not ready
          $ref: "SwarmCommon.yaml#/components/responses/400"
        default:
          description: Default response

  "/balances":
    get:
      summary: Get balances with all known peers
      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 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: Balance with the specific peer
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Balance"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "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/BlockListedPeers"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/consumed":
    get:
      summary: Get 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 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"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/chequebook/address":
    get:
      summary: Get the chequebook contract address
      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: "Retrieve a chunk"
      tags:
        - Chunk
      parameters:
        - in: path
          name: reference
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference"
          required: true
          description: Swarm address of chunk
        - in: header
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache"
          name: swarm-cache
          required: false
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
      responses:
        "200":
          description: Retrieved chunk content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "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
    head:
      summary: Check if a chunk exists locally
      tags:
        - Chunk
      parameters:
        - in: path
          name: address
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress"
          required: true
          description: Swarm address of chunk
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher"
        - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress"
      responses:
        "200":
          description: Chunk exists
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        default:
          description: Default response

  "/envelope/{address}":
    post:
      summary: "Create a postage stamp for a chunk"
      tags:
        - Envelope
      parameters:
        - in: header
          name: swarm-postage-batch-id
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId"
          required: true
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/PostEnvelopeResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "402":
          $ref: "SwarmCommon.yaml#/components/responses/402"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/connect/{multiAddress}":
    post:
      summary: Connect to a peer 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 the 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 the chain state
      tags:
        - Status
      responses:
        "200":
          description: Chain State
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ChainState"
        default:
          description: Default response

  "/node":
    get:
      summary: Get node information
      tags:
        - Status
      responses:
        "200":
          description: Information about the node
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Node"
        default:
          description: Default response

  "/peers":
    get:
      summary: Get the list of connected 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: Disconnect from a 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: Peer has been disconnected
          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/{address}":
    post:
      summary: Ping a peer to measure latency
      tags:
        - Connectivity
      parameters:
        - in: path
          name: address
          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

  "/settlements/{address}":
    get:
      summary: Get settlement amounts sent and received 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: Settlement amounts sent and received with the peer
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/Settlement"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/settlements":
    get:
      summary: Get settlements with all known peers and totals
      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 totals
      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:
      summary: Get the network topology
      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 the 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 the 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/HealthStatus"
        "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 the last cashout status for a 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: Cash out the last cheque for a 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: Cheque has been cashed out
          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 the last cheques for a 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: The last cheques for the peer
          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 the last cheques for all peers
      tags:
        - Chequebook
      responses:
        "200":
          description: The last cheques for all peers
          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 into the 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
      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

  "/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/PendingTransactionsResponse"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/transactions/{txHash}":
    get:
      summary: Retrieve transaction information
      parameters:
        - in: path
          name: txHash
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/TransactionHash"
          required: true
          description: Hash of the transaction
      tags:
        - Transaction
      responses:
        "200":
          description: Transaction information
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/TransactionInfo"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response
    post:
      summary: Rebroadcast a 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 postage stamps for this node
      tags:
        - Postage Stamps
      responses:
        "200":
          description: An array of postage stamps
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/DebugPostageBatchesResponse"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"

        default:
          description: Default response

  "/stamps/{batch_id}":
    parameters:
      - in: path
        name: batch_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"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        default:
          description: Default response

  "/stamps/{batch_id}/buckets":
    parameters:
      - in: path
        name: batch_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"
        "404":
          $ref: "SwarmCommon.yaml#/components/responses/404"
        "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 transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance!
      tags:
        - Postage Stamps
      parameters:
        - in: path
          name: amount
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/BigInt"
          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 (logarithm) specifying the maximum number of chunks this stamp can cover. Must be greater than the 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"
        - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter"
      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/{batch_id}/{amount}":
    patch:
      summary: Top up an existing postage batch.
      description: |
        Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance!
      tags:
        - Postage Stamps
      parameters:
        - in: path
          name: batch_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.
        - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter"
      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/{batch_id}/{depth}":
    patch:
      summary: Dilute an existing postage batch.
      description: |
        Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance!
      tags:
        - Postage Stamps
      parameters:
        - in: path
          name: batch_id
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/BatchID"
          required: true
          description: Batch ID to dilute
        - in: path
          name: depth
          schema:
            type: integer
          required: true
          description: The new batch depth, which must be greater than the current depth
        - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter"
      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

  "/batches":
    get:
      summary: Get all globally available postage batches
      tags:
        - Postage Stamps
      responses:
        "200":
          description: An array of all available and valid postage batches
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/DebugPostageAllBatchesResponse"

        default:
          description: Default response

  "/rchash/{depth}/{anchor1}/{anchor2}":
    get:
      summary: Get reserve commitment hash with sample proofs
      tags:
        - RChash
      parameters:
        - in: path
          name: depth
          schema:
            type: integer
            minimum: 0
            default: 0
          required: true
          description: The storage depth.
        - in: path
          name: anchor1
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/HexString"
          required: true
          description: The first anchor.
        - in: path
          name: anchor2
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/HexString"
          required: true
          description: The second anchor.
      responses:
        "200":
          description: Reserve sample response
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/ApiRCHashResponse"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/accounting":
    get:
      summary: Get accounting values for all known peers
      tags:
        - Balance
      responses:
        "200":
          description: Own accounting associated values with all known peers
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/PeerAccountingData"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/redistributionstate":
    get:
      summary: Get the node's redistribution game status
      tags:
        - RedistributionState
      responses:
        "200":
          description: Redistribution status info
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/RedistributionStatusResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response
  "/wallet":
    get:
      summary: Get wallet balance for BZZ and xDAI
      tags:
        - Wallet
      responses:
        "200":
          description: Wallet balance info
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/WalletResponse"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response
  "/wallet/withdraw/{coin}":
    post:
      summary: Withdraw BZZ or xDAI to a whitelisted address
      tags:
        - Wallet
      parameters:
        - in: query
          name: amount
          required: true
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/BigInt"
        - in: query
          name: address
          required: true
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress"
        - in: path
          name: coin
          required: true
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/WithdrawCoin"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/WalletTxResponse"
          description: OK
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
          description: Amount greater than balance or coin is other than BZZ/xDAI
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/stake/withdrawable":
    get:
      summary: Get the withdrawable staked amount.
      description: This endpoint fetches any amount that is possible to withdraw as surplus.
      tags:
        - Staking
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/GetWithdrawableResponse"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response
    delete:
      summary: Withdraw the extra withdrawable staked amount.
      description: This endpoint withdraws any amount that is possible to withdraw as surplus.
      tags:
        - Staking
      parameters:
        - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/StakeTransactionResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/stake/{amount}":
    post:
      summary: Deposit an amount for staking.
      description: Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance.
      tags:
        - Staking
      parameters:
        - in: path
          name: amount
          schema:
            type: string
          required: true
          description: Amount of BZZ added that will be deposited for staking.
        - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/StakeTransactionResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/stake":
    get:
      summary: Get the staked amount.
      description: This endpoint fetches the total staked amount from the blockchain.
      tags:
        - Staking
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/GetStakeResponse"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response
    delete:
      summary: Withdraw all previously staked amounts.
      description: Be aware, this endpoint can only be called when the contract is paused and undergoing migration to a new contract.
      tags:
        - Staking
      parameters:
        - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/StakeTransactionResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/loggers":
    get:
      summary: Get all available loggers.
      tags:
        - Logging
      responses:
        "200":
          description: Returns an array of all available loggers, also represented in short form in a tree.
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/LoggerResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        default:
          description: Default response

  "/loggers/{exp}":
    get:
      summary: Get all available loggers that match the specified expression.
      parameters:
        - in: path
          name: exp
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/LoggerExp"
          required: true
          description: Regular expression or a subsystem that matches the logger(s).
      tags:
        - Logging
      responses:
        "200":
          description: Returns an array of all available loggers that matches given expression, also represented in short form in a tree.
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/LoggerResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        default:
          description: Default response
    put:
      summary: Set logger(s) verbosity level.
      parameters:
        - in: path
          name: exp
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/LoggerExp"
          required: true
          description: Regular expression or a subsystem that matches the logger(s).
      tags:
        - Logging
      responses:
        "200":
          description: The verbosity was changed successfully.
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        default:
          description: Default response

  "/status":
    get:
      summary: Get the current status snapshot of this node.
      tags:
        - Node Status
      responses:
        "200":
          description: Returns the current node status snapshot.
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/StatusSnapshotResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        default:
          description: Default response.

  "/status/peers":
    get:
      summary: Get the current status snapshot of this node connected peers.
      tags:
        - Node Status
      responses:
        "200":
          description: Returns the status snapshot of this node connected peers
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/StatusPeersResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        default:
          description: Default response.

  "/status/neighborhoods":
    get:
      summary: Get the current neighborhoods status of this node.
      tags:
        - Node Status
      responses:
        "200":
          description: Returns the neighborhoods status of this node
          content:
            application/json:
              schema:
                $ref: "SwarmCommon.yaml#/components/schemas/StatusNeighborhoodsResponse"
        "400":
          $ref: "SwarmCommon.yaml#/components/responses/400"
        default:
          description: Default response.
