openapi/Swarm.yaml

openapi: 3.0.3

info:
  version: 7.3.0
  title: Bee API
  description: "A list of the currently provided Interfaces to interact with the swarm, implementing file operations and sending messages"

security:
  - {}

externalDocs:
  description: Browse the documentation @ 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 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 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 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:
        - 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/SwarmEncryptParameter"
          name: swarm-encrypt
          required: false
        - in: header
          schema:
            $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter"
          name: swarm-redundancy-level
          required: false

      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: "Get referenced data"
      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: Requests the 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 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 that has to have at least 8 bytes.
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "201":
          description: Ok
          headers:
            "swarm-tag":
              description: Tag UID if it was passed to the request `swarm-tag` header.
              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: "Upload stream of chunks"
      description: "Returns a WebSocket connection on which stream of chunks can be uploaded. Each chunk sent is acknowledged using a binary response `0` which serves as confirmation of upload of single chunk. Chunks should be packaged as binary messages for uploading. If a tag is specified, the chunks will be streamed into local storage and then be uploaded to the network once the stream is closed. If a tag is not specified, the chunks will bypass local storage and be directly uploaded to the network through the stream 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 file or a collection of files"
      description:
        "In order to upload a collection, user can send a multipart request with all the files populated in the form data with appropriate headers.\n\n
        User can also upload a tar file along with the swarm-collection header. This will upload the tar file after extracting the entire directory structure.\n\n
        If the swarm-collection header is absent, all requests (including tar files) are considered as single file uploads.\n\n
        A multipart request is treated as a collection regardless of whether the swarm-collection header is present. This means in order to serve single files
        uploaded as a multipart request, the swarm-index-document header should be used with the name of the file."
      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: "Get file or index document from a collection of files"
      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
        "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: Get the headers containing the 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: "Get referenced file from a collection of files"
      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

        "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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "SwarmCommon.yaml#/components/schemas/NewTagRequest"
      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 the root hash with the given reference
      tags:
        - Pinning
      responses:
        "200":
          description: Pin already exists, so no operation
          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 the root hash with the given reference
      tags:
        - Pinning
      responses:
        "200":
          description: Unpinning root hash with reference
          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 pinning status of the root hash with the given reference
      tags:
        - Pinning
      responses:
        "200":
          description: Reference of the pinned root hash
          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 integerity
      tags:
        - Pinning
      parameters:
        - in: query
          name: ref
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/SwarmOnlyReference"
          required: false
          description: The number of items to skip before starting to collect the result set.
      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 to recipient or target with 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 for messages on the given 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: Returns a WebSocket with a subscription for incoming message data on the requested 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: Returns a WebSocket with a subscription for incoming message data on the requested SOC address.
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response

  "/soc/{owner}/{id}":
    post:
      summary: Upload single owner chunk
      tags:
        - Single owner chunk
      parameters:
        - in: path
          name: owner
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress"
          required: true
          description: Owner
        - in: path
          name: id
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/HexString"
          required: true
          description: Id
        - 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 is composed of the span (8 bytes) and the at most 4KB 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: Resolve 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: Arbitrary identifier of the related 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 an initial feed root manifest
      tags:
        - Feed
      parameters:
        - in: path
          name: owner
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress"
          required: true
          description: Owner
        - in: path
          name: topic
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/HexString"
          required: true
          description: Topic
        - 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: Find feed update
      tags:
        - Feed
      parameters:
        - in: path
          name: owner
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress"
          required: true
          description: Owner
        - in: path
          name: topic
          schema:
            $ref: "SwarmCommon.yaml#/components/schemas/HexString"
          required: true
          description: Topic
        - 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"
          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 if content is available"
      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 for specified root hash"
      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 node overall health Status
      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: Readiness endpoint indicates if node is ready to start accepting 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 the balances with all known peers including prepaid services
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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 the past due consumption balances with all known peers
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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 address of the chequebook contract used
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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: "Get 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 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
        - $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 postage stamp signature against given chunk address"
      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 address
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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 information about the node
      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 a list of peers
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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/{address}":
    post:
      summary: Try connection to node
      security:
        - bearerAuth: []
      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 amount of sent and received from settlements with a peer
      security:
        - bearerAuth: []
      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"
        "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 total amount sent or received
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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 topology of known network
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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 last cashout action for the peer
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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: 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/TransactionInfo"
        "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 stamps for this node
      security:
        - bearerAuth: []
      tags:
        - Postage Stamps
      responses:
        "200":
          description: Returns an array of postage batches.
          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
      security:
        - bearerAuth: []
      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
      security:
        - bearerAuth: []
      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.
      security:
        - bearerAuth: []
      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:
            $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 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"
        - $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 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: 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 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: 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: New batch depth. Must be higher than the previous 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 batches that were purchased by all nodes.
      security:
        - bearerAuth: []
      tags:
        - Postage Stamps
      responses:
        "200":
          description: Returns an array of all available and currently 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 all accounting associated values with 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 current status of node in redistribution game
      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: Allows withdrawals of BZZ or xDAI to provided (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/SwarmAddress"
      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":
          $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":
          $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 some amount for staking.
      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:
        - 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":
          $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":
          $ref: "SwarmCommon.yaml#/components/schemas/GetStakeResponse"
        "500":
          $ref: "SwarmCommon.yaml#/components/responses/500"
        default:
          description: Default response
    delete:
      summary: Withdraws all past staked amount back to the wallet.
      description: Be aware, this endpoint can only be called when the contract is paused and is in the process of being migrated to a new contract.
      tags:
        - Staking
      parameters:
        - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter"
        - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter"
      responses:
        "200":
          $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.

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: SecurityToken