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 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: '#/components/schemas/SwarmPostageBatchId' name: swarm-postage-batch-id required: true - in: header schema: $ref: '#/components/schemas/SwarmTagParameter' name: swarm-tag required: false - in: header schema: $ref: '#/components/schemas/SwarmPinParameter' name: swarm-pin required: false - in: header schema: $ref: '#/components/schemas/SwarmDeferredUpload' name: swarm-deferred-upload required: false - in: header schema: $ref: '#/components/schemas/SwarmActHistoryAddress' name: swarm-act-history-address required: false requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ActGranteesCreateRequest' responses: '201': description: OK content: application/json: schema: $ref: '#/components/schemas/ActGranteesOperationResponse' '400': $ref: '#/components/responses/400' '500': $ref: '#/components/responses/500' /grantee/{reference}: get: summary: Get grantee list tags: - ACT parameters: - in: path name: reference schema: $ref: '#/components/schemas/SwarmEncryptedReference' required: true description: Grantee list reference responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/PublicKey' '404': $ref: '#/components/responses/404' '500': $ref: '#/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: '#/components/schemas/SwarmEncryptedReference' required: true description: Grantee list reference - in: header schema: $ref: '#/components/schemas/SwarmActHistoryAddress' name: swarm-act-history-address required: true - in: header schema: $ref: '#/components/schemas/SwarmPostageBatchId' name: swarm-postage-batch-id required: true - in: header schema: $ref: '#/components/schemas/SwarmTagParameter' name: swarm-tag required: false - in: header schema: $ref: '#/components/schemas/SwarmPinParameter' name: swarm-pin required: false - in: header schema: $ref: '#/components/schemas/SwarmDeferredUpload' name: swarm-deferred-upload required: false requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ActGranteesPatchRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ActGranteesOperationResponse' '400': $ref: '#/components/responses/400' '500': $ref: '#/components/responses/500' /bytes: post: summary: Upload data tags: - Bytes parameters: - in: header schema: $ref: '#/components/schemas/SwarmPostageBatchId' name: swarm-postage-batch-id required: true - in: header schema: $ref: '#/components/schemas/SwarmTagParameter' name: swarm-tag required: false - in: header schema: $ref: '#/components/schemas/SwarmPinParameter' name: swarm-pin required: false - in: header schema: $ref: '#/components/schemas/SwarmDeferredUpload' name: swarm-deferred-upload required: false - in: header schema: $ref: '#/components/schemas/SwarmEncryptParameter' name: swarm-encrypt required: false - in: header schema: $ref: '#/components/schemas/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: '#/components/headers/SwarmTag' content: application/json: schema: $ref: '#/components/schemas/ReferenceResponse' '400': $ref: '#/components/responses/400' '402': $ref: '#/components/responses/402' '500': $ref: '#/components/responses/500' default: description: Default response /bytes/{reference}: get: summary: Get referenced data tags: - Bytes parameters: - in: path name: reference schema: $ref: '#/components/schemas/SwarmReference' required: true description: Swarm address reference to content - $ref: '#/components/parameters/SwarmCache' - $ref: '#/components/parameters/SwarmRedundancyStrategyParameter' - $ref: '#/components/parameters/SwarmRedundancyFallbackModeParameter' - $ref: '#/components/parameters/SwarmRedundancyLevelParameter' - $ref: '#/components/parameters/SwarmChunkRetrievalTimeoutParameter' - $ref: '#/components/parameters/SwarmActTimestamp' - $ref: '#/components/parameters/SwarmActPublisher' - $ref: '#/components/parameters/SwarmActHistoryAddress' responses: '200': description: Retrieved content specified by reference content: application/octet-stream: schema: type: string format: binary '400': $ref: '#/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: '#/components/schemas/SwarmAddress' required: true description: Swarm address of chunk - $ref: '#/components/parameters/SwarmActTimestamp' - $ref: '#/components/parameters/SwarmActPublisher' - $ref: '#/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: '#/components/responses/400' '404': $ref: '#/components/responses/404' default: description: Default response /chunks: post: summary: Upload chunk tags: - Chunk parameters: - $ref: '#/components/parameters/SwarmTagParameter' - in: header name: swarm-postage-batch-id schema: $ref: '#/components/schemas/SwarmPostageBatchId' required: false - $ref: '#/components/parameters/SwarmPostageStamp' - $ref: '#/components/parameters/SwarmAct' - $ref: '#/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: '#/components/schemas/Uid' swarm-act-history-address: $ref: '#/components/headers/SwarmActHistoryAddress' content: application/json: schema: $ref: '#/components/schemas/ReferenceResponse' '400': $ref: '#/components/responses/400' '402': $ref: '#/components/responses/402' '500': $ref: '#/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: '#/components/parameters/SwarmTagParameter' - $ref: '#/components/parameters/SwarmPostageBatchId' responses: '200': description: Connection established '400': $ref: '#/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. 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. If the swarm-collection header is absent, all requests (including tar files) are considered as single file uploads. 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: '#/components/schemas/FileName' required: false description: Filename when uploading single file - $ref: '#/components/parameters/SwarmTagParameter' - $ref: '#/components/parameters/SwarmPinParameter' - $ref: '#/components/parameters/SwarmEncryptParameter' - $ref: '#/components/parameters/ContentTypePreserved' - $ref: '#/components/parameters/SwarmCollection' - $ref: '#/components/parameters/SwarmIndexDocumentParameter' - $ref: '#/components/parameters/SwarmErrorDocumentParameter' - $ref: '#/components/parameters/SwarmPostageBatchId' - $ref: '#/components/parameters/SwarmDeferredUpload' - $ref: '#/components/parameters/SwarmRedundancyLevelParameter' - $ref: '#/components/parameters/SwarmAct' - $ref: '#/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: '#/components/headers/SwarmTag' etag: $ref: '#/components/headers/ETag' swarm-act-history-address: $ref: '#/components/headers/SwarmActHistoryAddress' content: application/json: schema: $ref: '#/components/schemas/ReferenceResponse' '400': $ref: '#/components/responses/400' '402': $ref: '#/components/responses/402' '500': $ref: '#/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: '#/components/schemas/SwarmReference' required: true description: Swarm address of content - $ref: '#/components/parameters/SwarmCache' - $ref: '#/components/parameters/SwarmRedundancyStrategyParameter' - $ref: '#/components/parameters/SwarmRedundancyFallbackModeParameter' - $ref: '#/components/parameters/SwarmRedundancyLevelParameter' - $ref: '#/components/parameters/SwarmChunkRetrievalTimeoutParameter' - $ref: '#/components/parameters/SwarmActTimestamp' - $ref: '#/components/parameters/SwarmActPublisher' - $ref: '#/components/parameters/SwarmActHistoryAddress' responses: '200': description: OK content: application/octet-stream: schema: type: string format: binary '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' '500': $ref: '#/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: '#/components/schemas/SwarmAddress' required: true description: Swarm address of chunk - $ref: '#/components/parameters/SwarmActTimestamp' - $ref: '#/components/parameters/SwarmActPublisher' - $ref: '#/components/parameters/SwarmActHistoryAddress' responses: '200': description: Chunk exists '400': $ref: '#/components/responses/400' '404': $ref: '#/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: '#/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: '#/components/parameters/SwarmRedundancyStrategyParameter' - $ref: '#/components/parameters/SwarmRedundancyFallbackModeParameter' - $ref: '#/components/parameters/SwarmChunkRetrievalTimeoutParameter' responses: '200': description: OK content: application/octet-stream: schema: type: string format: binary '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' '500': $ref: '#/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: '#/components/schemas/TagsList' '500': $ref: '#/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: '#/components/schemas/NewTagRequest' responses: '201': description: New Tag Info content: application/json: schema: $ref: '#/components/schemas/NewTagResponse' '500': $ref: '#/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: '#/components/schemas/Uid' required: true description: Uid responses: '200': description: Tag info content: application/json: schema: $ref: '#/components/schemas/NewTagResponse' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' default: description: Default response delete: summary: Delete Tag information using Uid tags: - Tag parameters: - in: path name: uid schema: $ref: '#/components/schemas/Uid' required: true description: Uid responses: '204': $ref: '#/components/responses/204' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' '500': $ref: '#/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: '#/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: '#/components/schemas/Address' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Response' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' default: description: Default response /pins/{reference}: parameters: - in: path name: reference schema: $ref: '#/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: '#/components/schemas/Response' '201': description: New pin with root reference was created content: application/json: schema: $ref: '#/components/schemas/Response' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' '500': $ref: '#/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: '#/components/schemas/Response' '400': $ref: '#/components/responses/400' '500': $ref: '#/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: '#/components/schemas/SwarmOnlyReference' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' '500': $ref: '#/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: '#/components/schemas/SwarmOnlyReferencesList' '500': $ref: '#/components/responses/500' default: description: Default response /pins/check: get: summary: Validate pinned chunks integerity tags: - Pinning parameters: - in: query name: ref schema: $ref: '#/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: '#/components/schemas/PinCheckResponse' '500': $ref: '#/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: '#/components/schemas/PssTopic' required: true description: Topic name - in: path name: targets schema: $ref: '#/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: '#/components/schemas/PssRecipient' required: false description: Recipient publickey - $ref: '#/components/parameters/SwarmPostageBatchId' responses: '201': description: Subscribed to topic '400': $ref: '#/components/responses/400' '402': $ref: '#/components/responses/402' '500': $ref: '#/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: '#/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: '#/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: '#/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: '#/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: '#/components/schemas/EthereumAddress' required: true description: Owner - in: path name: id schema: $ref: '#/components/schemas/HexString' required: true description: Id - in: query name: sig schema: $ref: '#/components/schemas/HexString' required: true description: Signature - in: header name: swarm-postage-batch-id schema: $ref: '#/components/schemas/SwarmPostageBatchId' required: true - $ref: '#/components/parameters/SwarmPostageStamp' - $ref: '#/components/parameters/SwarmAct' - $ref: '#/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: '#/components/schemas/ReferenceResponse' headers: swarm-act-history-address: $ref: '#/components/headers/SwarmActHistoryAddress' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '402': $ref: '#/components/responses/402' '500': $ref: '#/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: '#/components/schemas/EthereumAddress' required: true description: Ethereum address of the Owner of the SOC - in: path name: id schema: $ref: '#/components/schemas/HexString' required: true description: Arbitrary identifier of the related data - $ref: '#/components/parameters/SwarmOnlyRootChunkParameter' - $ref: '#/components/parameters/SwarmCache' - $ref: '#/components/parameters/SwarmRedundancyStrategyParameter' - $ref: '#/components/parameters/SwarmRedundancyFallbackModeParameter' - $ref: '#/components/parameters/SwarmChunkRetrievalTimeoutParameter' responses: '200': description: Related Single Owner Chunk data headers: swarm-soc-signature: $ref: '#/components/headers/SwarmSocSignature' content: application/octet-stream: schema: type: string format: binary '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '500': $ref: '#/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: '#/components/schemas/EthereumAddress' required: true description: Owner - in: path name: topic schema: $ref: '#/components/schemas/HexString' required: true description: Topic - in: query name: type schema: $ref: '#/components/schemas/FeedType' required: false description: 'Feed indexing scheme (default: sequence)' - $ref: '#/components/parameters/SwarmPinParameter' - $ref: '#/components/parameters/SwarmPostageBatchId' - $ref: '#/components/parameters/SwarmAct' - $ref: '#/components/parameters/SwarmActHistoryAddress' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/ReferenceResponse' headers: swarm-act-history-address: $ref: '#/components/headers/SwarmActHistoryAddress' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '402': $ref: '#/components/responses/402' '500': $ref: '#/components/responses/500' default: description: Default response get: summary: Find feed update tags: - Feed parameters: - in: path name: owner schema: $ref: '#/components/schemas/EthereumAddress' required: true description: Owner - in: path name: topic schema: $ref: '#/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: '#/components/schemas/FeedType' required: false description: 'Feed indexing scheme (default: sequence)' - $ref: '#/components/parameters/SwarmOnlyRootChunkParameter' - $ref: '#/components/parameters/SwarmCache' - $ref: '#/components/parameters/SwarmRedundancyStrategyParameter' - $ref: '#/components/parameters/SwarmRedundancyFallbackModeParameter' - $ref: '#/components/parameters/SwarmChunkRetrievalTimeoutParameter' responses: '200': description: Latest feed update headers: swarm-soc-signature: $ref: '#/components/headers/SwarmSocSignature' swarm-feed-index: $ref: '#/components/headers/SwarmFeedIndex' swarm-feed-index-next: $ref: '#/components/headers/SwarmFeedIndexNext' content: application/octet-stream: schema: type: string format: binary '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '500': $ref: '#/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: '#/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: '#/components/schemas/IsRetrievableResponse' '404': $ref: '#/components/responses/404' '500': $ref: '#/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: '#/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: '#/components/schemas/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: '#/components/responses/400' '404': $ref: '#/components/responses/404' '500': $ref: '#/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: '#/components/schemas/Addresses' '500': $ref: '#/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: '#/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: '#/components/responses/200' '400': description: Indicates that node is not ready $ref: '#/components/responses/400' default: description: Default response /balances: get: summary: Get the balances with all known peers including prepaid services tags: - Balance responses: '200': description: Own balances with all known peers content: application/json: schema: $ref: '#/components/schemas/Balances' '500': $ref: '#/components/responses/500' default: description: Default response /balances/{address}: get: summary: Get the balances with a specific peer including prepaid services tags: - Balance parameters: - in: path name: address schema: $ref: '#/components/schemas/SwarmAddress' required: true description: Swarm address of peer responses: '200': description: Balance with the specific peer content: application/json: schema: $ref: '#/components/schemas/Balance' '400': $ref: '#/components/responses/400' '500': $ref: '#/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: '#/components/schemas/BlockListedPeers' '500': $ref: '#/components/responses/500' default: description: Default response /consumed: get: summary: Get the past due consumption balances with all known peers tags: - Balance responses: '200': description: Own past due consumption balances with all known peers content: application/json: schema: $ref: '#/components/schemas/Balances' '500': $ref: '#/components/responses/500' default: description: Default response /consumed/{address}: get: summary: Get the past due consumption balance with a specific peer tags: - Balance parameters: - in: path name: address schema: $ref: '#/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: '#/components/schemas/Balance' '400': $ref: '#/components/responses/400' '500': $ref: '#/components/responses/500' default: description: Default response /chequebook/address: get: summary: Get the address of the chequebook contract used tags: - Chequebook responses: '200': description: Ethereum address of chequebook contract content: application/json: schema: $ref: '#/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: '#/components/schemas/ChequebookBalance' '500': $ref: '#/components/responses/500' default: description: Default response /chunks/{address}: get: summary: Get chunk tags: - Chunk parameters: - in: path name: reference schema: $ref: '#/components/schemas/SwarmReference' required: true description: Swarm address of chunk - in: header schema: $ref: '#/components/schemas/SwarmCache' name: swarm-cache required: false - $ref: '#/components/parameters/SwarmActTimestamp' - $ref: '#/components/parameters/SwarmActPublisher' - $ref: '#/components/parameters/SwarmActHistoryAddress' responses: '200': description: Retrieved chunk content content: application/octet-stream: schema: type: string format: binary '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' '500': $ref: '#/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: '#/components/schemas/SwarmAddress' required: true description: Swarm address of chunk - $ref: '#/components/parameters/SwarmActTimestamp' - $ref: '#/components/parameters/SwarmActPublisher' - $ref: '#/components/parameters/SwarmActHistoryAddress' responses: '200': description: Chunk exists '400': $ref: '#/components/responses/400' '404': $ref: '#/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: '#/components/schemas/SwarmPostageBatchId' required: true responses: '201': description: OK content: application/json: schema: $ref: '#/components/schemas/PostEnvelopeResponse' '400': $ref: '#/components/responses/400' '402': $ref: '#/components/responses/402' '500': $ref: '#/components/responses/500' default: description: Default response /connect/{multiAddress}: post: summary: Connect to address tags: - Connectivity parameters: - in: path allowReserved: true name: multiAddress schema: $ref: '#/components/schemas/MultiAddress' required: true description: Underlay address of peer responses: '200': description: Returns overlay address of connected peer content: application/json: schema: $ref: '#/components/schemas/Address' '400': $ref: '#/components/responses/400' '500': $ref: '#/components/responses/500' default: description: Default response /reservestate: get: summary: Get reserve state tags: - Status responses: '200': description: Reserve State content: application/json: schema: $ref: '#/components/schemas/ReserveState' default: description: Default response /chainstate: get: summary: Get chain state tags: - Status responses: '200': description: Chain State content: application/json: schema: $ref: '#/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: '#/components/schemas/Node' default: description: Default response /peers: get: summary: Get a list of peers tags: - Connectivity responses: '200': description: Returns overlay addresses of connected peers content: application/json: schema: $ref: '#/components/schemas/Peers' default: description: Default response /peers/{address}: delete: summary: Remove peer tags: - Connectivity parameters: - in: path name: address schema: $ref: '#/components/schemas/SwarmAddress' required: true description: Swarm address of peer responses: '200': description: Disconnected peer content: application/json: schema: $ref: '#/components/schemas/Response' '400': $ref: '#/components/responses/400' '500': $ref: '#/components/responses/500' default: description: Default response /pingpong/{address}: post: summary: Try connection to node tags: - Connectivity parameters: - in: path name: address schema: $ref: '#/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: '#/components/schemas/RttMs' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' default: description: Default response /settlements/{address}: get: summary: Get amount of sent and received from settlements with a peer tags: - Settlements parameters: - in: path name: address schema: $ref: '#/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: '#/components/schemas/Settlement' '400': $ref: '#/components/responses/400' '500': $ref: '#/components/responses/500' default: description: Default response /settlements: get: summary: Get settlements with all known peers and total amount sent or received tags: - Settlements responses: '200': description: Settlements with all known peers and total amount sent or received content: application/json: schema: $ref: '#/components/schemas/Settlements' '500': $ref: '#/components/responses/500' default: description: Default response /timesettlements: get: summary: >- Get time based settlements with all known peers and total amount sent or received tags: - Settlements responses: '200': description: >- Time based settlements with all known peers and total amount sent or received content: application/json: schema: $ref: '#/components/schemas/Settlements' '500': $ref: '#/components/responses/500' default: description: Default response /topology: get: summary: Get topology of known network tags: - Connectivity responses: '200': description: Swarm topology of the bee node content: application/json: schema: $ref: '#/components/schemas/BzzTopology' /welcome-message: get: summary: Get configured P2P welcome message tags: - Connectivity responses: '200': description: Welcome message content: application/json: schema: $ref: '#/components/schemas/WelcomeMessage' '500': $ref: '#/components/responses/500' default: description: Default response post: summary: Set P2P welcome message tags: - Connectivity requestBody: content: application/json: schema: $ref: '#/components/schemas/WelcomeMessage' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/HealthStatus' '400': $ref: '#/components/responses/400' '500': $ref: '#/components/responses/500' default: description: Default response /chequebook/cashout/{peer-id}: get: summary: Get last cashout action for the peer parameters: - in: path name: peer-id schema: $ref: '#/components/schemas/SwarmAddress' required: true description: Swarm address of peer tags: - Chequebook responses: '200': description: Cashout status content: application/json: schema: $ref: '#/components/schemas/SwapCashoutStatus' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' default: description: Default response post: summary: Cashout the last cheque for the peer parameters: - in: path name: peer-id schema: $ref: '#/components/schemas/SwarmAddress' required: true description: Swarm address of peer - $ref: '#/components/parameters/GasPriceParameter' - $ref: '#/components/parameters/GasLimitParameter' tags: - Chequebook responses: '201': description: OK content: application/json: schema: $ref: '#/components/schemas/TransactionResponse' '404': $ref: '#/components/responses/404' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' default: description: Default response /chequebook/cheque/{peer-id}: get: summary: Get last cheques for the peer parameters: - in: path name: peer-id schema: $ref: '#/components/schemas/SwarmAddress' required: true description: Swarm address of peer tags: - Chequebook responses: '200': description: Last cheques content: application/json: schema: $ref: '#/components/schemas/ChequePeerResponse' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' default: description: Default response /chequebook/cheque: get: summary: Get last cheques for all peers tags: - Chequebook responses: '200': description: Last cheques content: application/json: schema: $ref: '#/components/schemas/ChequeAllPeersResponse' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' default: description: Default response /chequebook/deposit: post: summary: Deposit tokens from overlay address into chequebook parameters: - in: query name: amount schema: type: integer required: true description: amount of tokens to deposit - $ref: '#/components/parameters/GasPriceParameter' tags: - Chequebook responses: '201': description: Transaction hash of the deposit transaction content: application/json: schema: $ref: '#/components/schemas/TransactionResponse' '400': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' default: description: Default response /chequebook/withdraw: post: summary: Withdraw tokens from the chequebook to the overlay address parameters: - in: query name: amount schema: type: integer required: true description: amount of tokens to withdraw - $ref: '#/components/parameters/GasPriceParameter' tags: - Chequebook responses: '201': description: Transaction hash of the withdraw transaction content: application/json: schema: $ref: '#/components/schemas/TransactionResponse' '400': $ref: '#/components/responses/404' '500': $ref: '#/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: '#/components/schemas/PendingTransactionsResponse' '500': $ref: '#/components/responses/500' default: description: Default response /transactions/{txHash}: get: summary: Get information about a sent transaction parameters: - in: path name: txHash schema: $ref: '#/components/schemas/TransactionHash' required: true description: Hash of the transaction tags: - Transaction responses: '200': description: Get info about transaction content: application/json: schema: $ref: '#/components/schemas/TransactionInfo' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' default: description: Default response post: summary: Rebroadcast existing transaction parameters: - in: path name: txHash schema: $ref: '#/components/schemas/TransactionHash' required: true description: Hash of the transaction tags: - Transaction responses: '200': description: Hash of the transaction content: application/json: schema: $ref: '#/components/schemas/TransactionResponse' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' default: description: Default response delete: summary: Cancel existing transaction parameters: - in: path name: txHash schema: $ref: '#/components/schemas/TransactionHash' required: true description: Hash of the transaction - $ref: '#/components/parameters/GasPriceParameter' tags: - Transaction responses: '200': description: Hash of the transaction content: application/json: schema: $ref: '#/components/schemas/TransactionResponse' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' default: description: Default response /stamps: get: summary: Get stamps for this node tags: - Postage Stamps responses: '200': description: Returns an array of postage batches. content: application/json: schema: $ref: '#/components/schemas/DebugPostageBatchesResponse' '404': $ref: '#/components/responses/404' default: description: Default response /stamps/{batch_id}: parameters: - in: path name: batch_id schema: $ref: '#/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: '#/components/schemas/DebugPostageBatch' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' default: description: Default response /stamps/{batch_id}/buckets: parameters: - in: path name: batch_id schema: $ref: '#/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: '#/components/schemas/PostageStampBuckets' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' default: description: Default response /stamps/{amount}/{depth}: post: summary: Buy a new postage batch. description: > Be aware, this endpoint creates an on-chain transactions and transfers BZZ from the node's Ethereum account and hence directly manipulates the wallet balance! tags: - Postage Stamps parameters: - in: path name: amount schema: $ref: '#/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: '#/components/parameters/GasPriceParameter' - $ref: '#/components/parameters/GasLimitParameter' responses: '201': description: Returns the newly created postage batch ID content: application/json: schema: $ref: '#/components/schemas/BatchIDResponse' '400': $ref: '#/components/responses/400' '429': $ref: '#/components/responses/429' '500': $ref: '#/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: '#/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: '#/components/parameters/GasPriceParameter' - $ref: '#/components/parameters/GasLimitParameter' responses: '202': description: Returns the postage batch ID that was topped up content: application/json: schema: $ref: '#/components/schemas/BatchIDResponse' '400': $ref: '#/components/responses/400' '402': $ref: '#/components/responses/402' '429': $ref: '#/components/responses/429' '500': $ref: '#/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: '#/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: '#/components/parameters/GasPriceParameter' - $ref: '#/components/parameters/GasLimitParameter' responses: '202': description: Returns the postage batch ID that was diluted. content: application/json: schema: $ref: '#/components/schemas/BatchIDResponse' '400': $ref: '#/components/responses/400' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' default: description: Default response /batches: get: summary: Get all globally available batches that were purchased by all nodes. tags: - Postage Stamps responses: '200': description: >- Returns an array of all available and currently valid postage batches. content: application/json: schema: $ref: '#/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: '#/components/schemas/HexString' required: true description: The first anchor. - in: path name: anchor2 schema: $ref: '#/components/schemas/HexString' required: true description: The second anchor. responses: '200': description: Reserve sample response content: application/json: schema: $ref: '#/components/schemas/ApiRCHashResponse' '500': $ref: '#/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: '#/components/schemas/PeerAccountingData' '500': $ref: '#/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: '#/components/schemas/RedistributionStatusResponse' '400': $ref: '#/components/responses/400' '500': $ref: '#/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: '#/components/schemas/WalletResponse' '500': $ref: '#/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: '#/components/schemas/BigInt' - in: query name: address required: true schema: $ref: '#/components/schemas/EthereumAddress' - in: path name: coin required: true schema: $ref: '#/components/schemas/SwarmAddress' responses: '200': content: application/json: schema: $ref: '#/components/schemas/WalletTxResponse' description: OK '400': $ref: '#/components/responses/400' description: Amount greater than balance or coin is other than BZZ/xDAI '500': $ref: '#/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: '#/components/schemas/GetWithdrawableResponse' '500': $ref: '#/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: '#/components/parameters/GasPriceParameter' - $ref: '#/components/parameters/GasLimitParameter' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/StakeTransactionResponse' '400': $ref: '#/components/responses/400' '500': $ref: '#/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: '#/components/parameters/GasPriceParameter' - $ref: '#/components/parameters/GasLimitParameter' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/StakeTransactionResponse' '400': $ref: '#/components/responses/400' '500': $ref: '#/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: '#/components/schemas/GetStakeResponse' '500': $ref: '#/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: '#/components/parameters/GasPriceParameter' - $ref: '#/components/parameters/GasLimitParameter' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/StakeTransactionResponse' '400': $ref: '#/components/responses/400' '500': $ref: '#/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: '#/components/schemas/LoggerResponse' '400': $ref: '#/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: '#/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: '#/components/schemas/LoggerResponse' '400': $ref: '#/components/responses/400' default: description: Default response put: summary: Set logger(s) verbosity level. parameters: - in: path name: exp schema: $ref: '#/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: '#/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: '#/components/schemas/StatusSnapshotResponse' '400': $ref: '#/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: '#/components/schemas/StatusPeersResponse' '400': $ref: '#/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: '#/components/schemas/StatusNeighborhoodsResponse' '400': $ref: '#/components/responses/400' default: description: Default response. components: schemas: SwarmPostageBatchId: &ref_4 in: header name: swarm-postage-batch-id description: ID of Postage Batch that is used to upload data with required: true schema: $ref: '#/components/schemas/SwarmAddress' SwarmTagParameter: &ref_3 in: header name: swarm-tag schema: $ref: '#/components/schemas/Uid' required: false description: Associate upload with an existing Tag UID SwarmPinParameter: &ref_5 in: header name: swarm-pin schema: type: boolean required: false description: > Represents if the uploaded data should be also locally pinned on the node. SwarmDeferredUpload: &ref_7 in: header name: swarm-deferred-upload schema: type: boolean default: 'true' required: false description: > Determines if the uploaded data should be sent to the network immediately or in a deferred fashion. By default the upload will be deferred. SwarmActHistoryAddress: &ref_2 in: header name: swarm-act-history-address schema: $ref: '#/components/schemas/SwarmAddress' required: false description: ACT history reference address PublicKey: type: string pattern: ^[A-Fa-f0-9]{66}$ example: 02ab7473879005929d10ce7d4f626412dad9fe56b0a6622038931d26bd79abf0a4 ActGranteesCreateRequest: type: object properties: grantees: type: array items: $ref: '#/components/schemas/PublicKey' SwarmEncryptedReference: type: string pattern: ^[A-Fa-f0-9]{128}$ example: >- 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f2d2810619d29b5dbefd5d74abce25d58b81b251baddb9c3871cf0d6967deaae2 ActGranteesOperationResponse: type: object properties: ref: $ref: '#/components/schemas/SwarmEncryptedReference' historyref: $ref: '#/components/schemas/SwarmEncryptedReference' ProblemDetails: type: object properties: code: type: integer message: type: string reasons: type: array nullable: true description: List of reasons for the error message. items: type: string ActGranteesPatchRequest: type: object properties: add: type: array items: $ref: '#/components/schemas/PublicKey' description: List of grantees to add revoke: type: array items: $ref: '#/components/schemas/PublicKey' description: List of grantees to revoke future access from SwarmEncryptParameter: &ref_6 in: header name: swarm-encrypt schema: type: boolean required: false description: | Represents the encrypting state of the file SwarmRedundancyLevelParameter: &ref_1 in: header name: swarm-redundancy-level schema: type: integer enum: - 0 - 1 - 2 - 3 - 4 required: false description: > Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file. Uid: type: integer SwarmAddress: type: string pattern: ^[A-Fa-f0-9]{64}$ example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f DomainName: type: string pattern: ^[A-Za-z0-9]+\.[A-Za-z0-9]+$ example: swarm.eth SwarmReference: oneOf: - $ref: '#/components/schemas/SwarmAddress' - $ref: '#/components/schemas/SwarmEncryptedReference' - $ref: '#/components/schemas/DomainName' ReferenceResponse: type: object properties: reference: $ref: '#/components/schemas/SwarmReference' Duration: description: Go time.Duration format type: string example: 5.0018ms HexString: type: string pattern: ^([A-Fa-f0-9]+)$ example: cf880b8eeac5093fa27b0825906c600685 FileName: type: string DateTime: type: string format: date-time example: '2020-06-11T11:26:42.6969797+02:00' NewTagResponse: type: object properties: uid: $ref: '#/components/schemas/Uid' startedAt: $ref: '#/components/schemas/DateTime' split: type: integer description: Number of chunks created by the splitter. seen: type: integer description: >- Number of chunks that are already uploaded with same reference and same postage batch. These don't need to be synced again. stored: type: integer description: >- Number of chunks that were stored locally as they lie in the uploader node's neighborhood. This is only applicable for full nodes. sent: type: integer description: >- Number of chunks sent on the network to peers as a part of the upload. Chunks could be sent multiple times because of failures or replication. synced: type: integer description: >- Number of chunks that were pushed with a valid receipt. The receipt will also show if they were stored at the correct depth. TagsList: type: object properties: tags: type: array nullable: true items: $ref: '#/components/schemas/NewTagResponse' NewTagRequest: type: object properties: address: $ref: '#/components/schemas/SwarmAddress' Address: type: object properties: address: $ref: '#/components/schemas/SwarmAddress' Response: type: object properties: message: type: string code: type: integer SwarmOnlyReference: oneOf: - $ref: '#/components/schemas/SwarmAddress' - $ref: '#/components/schemas/SwarmEncryptedReference' SwarmOnlyReferencesList: type: object properties: reference: type: array nullable: false items: $ref: '#/components/schemas/SwarmOnlyReference' PinCheckResponse: type: object properties: reference: $ref: '#/components/schemas/SwarmOnlyReference' total: type: integer missing: type: integer invalid: type: integer PssTopic: type: string PssTargets: pattern: ^[0-9a-fA-F]{1,6}(,[0-9a-fA-F]{1,6})*$ description: >- List of hex string targets that are comma separated and can have maximum length of 6 type: string PssRecipient: type: string EthereumAddress: type: string pattern: ^[A-Fa-f0-9]{40}$ example: 36b7efd913ca4cf880b8eeac5093fa27b0825906 FeedType: type: string pattern: ^(sequence|epoch)$ IsRetrievableResponse: type: object properties: isRetrievable: type: boolean P2PUnderlay: type: string example: >- /ip4/127.0.0.1/tcp/1634/p2p/16Uiu2HAmTm17toLDaPYzRyjKn27iCB76yjKnJ5DjQXneFmifFvaX Addresses: type: object properties: overlay: $ref: '#/components/schemas/SwarmAddress' underlay: type: array items: $ref: '#/components/schemas/P2PUnderlay' ethereum: $ref: '#/components/schemas/EthereumAddress' chain_address: $ref: '#/components/schemas/EthereumAddress' publicKey: $ref: '#/components/schemas/PublicKey' pssPublicKey: $ref: '#/components/schemas/PublicKey' HealthStatus: type: object properties: status: type: string enum: - ok - nok - unknown description: > Indicates health state of node * `ok` - node is healthy * `nok` - node is not healthy * `unknown` - health status is unknown version: type: string apiVersion: type: string default: 0.0.0 description: >- The default value is set in case the bee binary was not build correctly. BigInt: description: >- Numeric string that represents integer which might exceed `Number.MAX_SAFE_INTEGER` limit (2^53-1) type: string example: '1000000000000000000' Balance: type: object properties: peer: $ref: '#/components/schemas/SwarmAddress' balance: $ref: '#/components/schemas/BigInt' Balances: type: object properties: balances: type: array items: $ref: '#/components/schemas/Balance' BlockListedPeers: type: array items: type: object properties: address: $ref: '#/components/schemas/Address' fullNode: type: boolean reason: type: string duration: type: integer ChequebookAddress: type: object properties: chequebookAddress: $ref: '#/components/schemas/EthereumAddress' ChequebookBalance: type: object properties: totalBalance: $ref: '#/components/schemas/BigInt' availableBalance: $ref: '#/components/schemas/BigInt' SwarmCache: &ref_0 in: header name: swarm-cache schema: type: boolean default: 'true' required: false description: >- Determines if the download data should be cached on the node. By default the download will be cached Hex8Bytes: description: Hexadecimal string representation of 8 bytes type: string pattern: ^([0-9a-fA-F]{16})$ example: 1a2b3c4d5e6f7a8b Signature: description: Hexadecimal string representation of cryptographic signature type: string pattern: ^([0-9a-fA-F]{130})$ example: >- 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e PostEnvelopeResponse: type: object properties: issuer: $ref: '#/components/schemas/EthereumAddress' index: $ref: '#/components/schemas/Hex8Bytes' timestamp: $ref: '#/components/schemas/Hex8Bytes' signature: $ref: '#/components/schemas/Signature' MultiAddress: type: string ReserveState: type: object properties: radius: type: integer storageRadius: type: integer commitment: type: integer ChainState: type: object properties: chainTip: type: integer block: type: integer totalAmount: $ref: '#/components/schemas/BigInt' currentPrice: $ref: '#/components/schemas/BigInt' Node: type: object properties: beeMode: type: string enum: - light - full - dev - ultra-light - unknown description: > Gives back in what mode the Bee client has been started. The modes are mutually exclusive * `light` - light node; does not participate in forwarding or storing chunks * `full` - full node * `dev` - development mode; Bee client for development purposes, blockchain operations are mocked * `ultra-light` - ultra-light node; a light node with chain disabled * `unknown` - unknown mode chequebookEnabled: type: boolean swapEnabled: type: boolean Peers: type: object properties: peers: type: array nullable: false items: $ref: '#/components/schemas/Address' RttMs: type: object properties: rtt: $ref: '#/components/schemas/Duration' Settlement: type: object properties: peer: $ref: '#/components/schemas/SwarmAddress' received: type: integer sent: type: integer Settlements: type: object properties: totalReceived: type: integer totalSent: type: integer settlements: type: array nullable: false items: $ref: '#/components/schemas/Settlement' PeerMetricsView: type: object properties: lastSeenTimestamp: type: integer nullable: false sessionConnectionRetry: type: integer nullable: false connectionTotalDuration: type: number nullable: false sessionConnectionDuration: type: number nullable: false sessionConnectionDirection: type: string nullable: false latencyEWMA: type: integer nullable: false reachability: type: string healthy: type: boolean BzzTopology: type: object properties: baseAddr: $ref: '#/components/schemas/SwarmAddress' population: type: integer connected: type: integer timestamp: type: string nnLowWatermark: type: integer depth: type: integer reachability: type: string enum: - Unknown - Public - Private networkAvailability: type: string enum: - Unknown - Available - Unavailable bins: type: object additionalProperties: type: object properties: population: type: integer connected: type: integer disconnectedPeers: type: array items: type: object properties: address: $ref: '#/components/schemas/SwarmAddress' metrics: $ref: '#/components/schemas/PeerMetricsView' connectedPeers: type: array items: type: object properties: address: $ref: '#/components/schemas/SwarmAddress' metrics: $ref: '#/components/schemas/PeerMetricsView' WelcomeMessage: type: object properties: welcomeMessage: type: string Cheque: type: object properties: beneficiary: $ref: '#/components/schemas/EthereumAddress' chequebook: $ref: '#/components/schemas/EthereumAddress' payout: $ref: '#/components/schemas/BigInt' TransactionHash: type: string pattern: ^0x[A-Fa-f0-9]{64}$ example: '0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a' SwapCashoutResult: type: object properties: recipient: $ref: '#/components/schemas/EthereumAddress' lastPayout: $ref: '#/components/schemas/BigInt' bounced: type: boolean SwapCashoutStatus: type: object properties: peer: $ref: '#/components/schemas/SwarmAddress' lastCashedCheque: $ref: '#/components/schemas/Cheque' transactionHash: $ref: '#/components/schemas/TransactionHash' result: $ref: '#/components/schemas/SwapCashoutResult' uncashedAmount: $ref: '#/components/schemas/BigInt' GasPrice: description: >- Gas price refers to the amount you’re willing to pay for every unit of gas. type: integer GasLimit: description: >- Gas limit refers to the maximum amount of gas you’re willing to spend on a particular transaction. type: integer minimum: 0 maximum: 18446744073709552000 TransactionResponse: type: object properties: transactionHash: $ref: '#/components/schemas/TransactionHash' ChequePeerResponse: type: object properties: peer: $ref: '#/components/schemas/SwarmAddress' lastreceived: $ref: '#/components/schemas/Cheque' lastsent: $ref: '#/components/schemas/Cheque' ChequeAllPeersResponse: type: object properties: lastcheques: type: array nullable: false items: $ref: '#/components/schemas/ChequePeerResponse' TransactionInfo: type: object properties: transactionHash: $ref: '#/components/schemas/TransactionHash' to: $ref: '#/components/schemas/EthereumAddress' nonce: type: integer gasPrice: $ref: '#/components/schemas/BigInt' gasLimit: type: integer gasTipCap: $ref: '#/components/schemas/BigInt' gasTipBoost: type: integer gasFeeCap: $ref: '#/components/schemas/BigInt' data: type: string created: $ref: '#/components/schemas/DateTime' description: type: string value: $ref: '#/components/schemas/BigInt' PendingTransactionsResponse: type: object properties: pendingTransactions: type: array nullable: false items: $ref: '#/components/schemas/TransactionInfo' BatchID: type: string pattern: ^[A-Fa-f0-9]{64}$ example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f PostageBatch: type: object properties: batchID: $ref: '#/components/schemas/BatchID' utilization: type: integer usable: description: >- Indicate that the batch was discovered by the Bee node, but it awaits enough on-chain confirmations before declaring the batch as usable. type: boolean label: type: string depth: type: integer amount: $ref: '#/components/schemas/BigInt' bucketDepth: type: integer blockNumber: type: integer immutableFlag: type: boolean exists: type: boolean batchTTL: type: integer PostageBatchNoIssuer: type: object properties: batchID: $ref: '#/components/schemas/BatchID' exists: type: boolean batchTTL: type: integer DebugPostageBatch: anyOf: - $ref: '#/components/schemas/PostageBatch' - $ref: '#/components/schemas/PostageBatchNoIssuer' DebugPostageBatchesResponse: type: object properties: stamps: type: array nullable: false items: $ref: '#/components/schemas/DebugPostageBatch' StampBucketData: type: object properties: bucketID: type: integer collisions: type: integer PostageStampBuckets: type: object properties: depth: type: integer bucketDepth: type: integer bucketUpperBound: type: integer buckets: type: array nullable: false items: $ref: '#/components/schemas/StampBucketData' BatchIDResponse: type: object properties: batchID: $ref: '#/components/schemas/BatchID' txHash: $ref: '#/components/schemas/TransactionHash' PostageBatchShort: type: object properties: batchID: $ref: '#/components/schemas/BatchID' value: $ref: '#/components/schemas/BigInt' start: type: integer depth: type: integer bucketDepth: type: integer immutableFlag: type: boolean batchTTL: type: integer owner: $ref: '#/components/schemas/EthereumAddress' storageRadius: type: integer DebugPostageAllBatchesResponse: type: object properties: batches: type: array nullable: false items: $ref: '#/components/schemas/PostageBatchShort' Seconds: description: Go time.Duration format in seconds type: number example: 30.5 ApiPostageProof: type: object properties: index: type: string postageId: type: string signature: type: string timeStamp: type: string ApiSOCProof: type: object properties: chunkAddr: type: string identifier: type: string signature: type: string signer: type: string ApiChunkInclusionProof: type: object properties: chunkSpan: minimum: 0 type: integer postageProof: $ref: '#/components/schemas/ApiPostageProof' proofSegments: items: type: string nullable: true type: array proofSegments2: items: type: string nullable: true type: array proofSegments3: items: type: string nullable: true type: array proveSegment: type: string proveSegment2: type: string socProof: items: $ref: '#/components/schemas/ApiSOCProof' nullable: true type: array ApiChunkInclusionProofs: type: object properties: proof1: $ref: '#/components/schemas/ApiChunkInclusionProof' proof2: $ref: '#/components/schemas/ApiChunkInclusionProof' proofLast: $ref: '#/components/schemas/ApiChunkInclusionProof' ApiRCHashResponse: type: object properties: durationSeconds: $ref: '#/components/schemas/Seconds' hash: $ref: '#/components/schemas/SwarmAddress' proofs: $ref: '#/components/schemas/ApiChunkInclusionProofs' AccountingInfo: type: object properties: balance: $ref: '#/components/schemas/BigInt' thresholdReceived: $ref: '#/components/schemas/BigInt' thresholdGiven: $ref: '#/components/schemas/BigInt' surplusBalance: $ref: '#/components/schemas/BigInt' reservedBalance: $ref: '#/components/schemas/BigInt' shadowReservedBalance: $ref: '#/components/schemas/BigInt' ghostBalance: $ref: '#/components/schemas/BigInt' PeerAccountingData: type: object properties: peerData: type: object additionalProperties: $ref: '#/components/schemas/AccountingInfo' RedistributionStatusResponse: type: object properties: minimumGasFunds: $ref: '#/components/schemas/BigInt' hasSufficientFunds: type: boolean isFrozen: type: boolean isFullySynced: type: boolean isHealthy: type: boolean phase: type: string round: type: integer lastWonRound: type: integer lastPlayedRound: type: integer lastFrozenRound: type: integer lastSelectedRound: type: integer lastSampleDurationSeconds: type: number block: type: integer reward: $ref: '#/components/schemas/BigInt' fees: $ref: '#/components/schemas/BigInt' WalletResponse: type: object properties: bzzBalance: $ref: '#/components/schemas/BigInt' nativeTokenBalance: $ref: '#/components/schemas/BigInt' chainID: type: integer chequebookContractAddress: $ref: '#/components/schemas/EthereumAddress' walletAddress: $ref: '#/components/schemas/EthereumAddress' WalletTxResponse: type: object properties: transactionHash: $ref: '#/components/schemas/TransactionHash' GetWithdrawableResponse: type: object properties: withdrawableAmount: $ref: '#/components/schemas/BigInt' StakeTransactionResponse: type: object properties: txHash: $ref: '#/components/schemas/TransactionHash' GetStakeResponse: type: object properties: stakedAmount: $ref: '#/components/schemas/BigInt' LoggerTreeNode: type: object additionalProperties: $ref: '#/components/schemas/LoggerTreeData' LoggerTreeData: type: object nullable: true properties: /: $ref: '#/components/schemas/LoggerTreeNode' +: type: array items: type: string description: >- The combination of the logger verbosity and its subsystem separated by |. example: warning|one/name[0][]>>824634860360 Logger: type: object properties: logger: type: string verbosity: type: string subsystem: type: string id: type: string LoggerResponse: type: object properties: tree: $ref: '#/components/schemas/LoggerTreeNode' loggers: type: array items: $ref: '#/components/schemas/Logger' LoggerExp: type: string description: Base 64 encoded regular expression or subsystem string. pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ example: b25lL25hbWU= StatusSnapshotResponse: type: object properties: overlay: $ref: '#/components/schemas/SwarmAddress' proximity: type: integer beeMode: type: string enum: - light - full - dev - ultra-light - unknown reserveSize: type: integer reserveSizeWithinRadius: type: integer pullsyncRate: type: number storageRadius: type: integer connectedPeers: type: integer neighborhoodSize: type: integer requestFailed: nullable: true type: boolean batchCommitment: type: integer isReachable: type: boolean lastSyncedBlock: type: integer committedDepth: type: integer StatusPeersResponse: type: object properties: snapshots: type: array nullable: false items: $ref: '#/components/schemas/StatusSnapshotResponse' Neighborhood: type: string description: >- Swarm address of a neighborhood in string binary format, usually limited to as many bits as the current storage radius. example: '011010111' StatusNeighborhoodResponse: type: object properties: neighborhood: $ref: '#/components/schemas/Neighborhood' reserveSizeWithinRadius: type: integer proximity: type: integer StatusNeighborhoodsResponse: type: object properties: neighborhoods: type: array nullable: false items: $ref: '#/components/schemas/StatusNeighborhoodResponse' responses: '200': description: OK. '204': description: The resource was deleted successfully. '400': description: Bad request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '402': description: Payment Required content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '404': description: Not Found content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '429': description: Too many requests content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' '500': description: Internal Server Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: SwarmTag: description: Tag UID schema: $ref: '#/components/schemas/Uid' SwarmActHistoryAddress: description: Swarm address reference to the new ACT history entry schema: $ref: '#/components/schemas/SwarmAddress' required: false ETag: description: | The RFC7232 ETag header field in a response provides the current entity- tag for the selected resource. An entity-tag is an opaque identifier for different versions of a resource over time, regardless whether multiple versions are valid at the same time. An entity-tag consists of an opaque quoted string, possibly prefixed by a weakness indicator. schema: type: string SwarmSocSignature: description: Attached digital signature of the Single Owner Chunk schema: $ref: '#/components/schemas/HexString' SwarmFeedIndex: description: The index of the found update schema: $ref: '#/components/schemas/HexString' SwarmFeedIndexNext: description: The index of the next possible update schema: $ref: '#/components/schemas/HexString' parameters: SwarmCache: *ref_0 SwarmRedundancyStrategyParameter: in: header name: swarm-redundancy-strategy schema: type: integer enum: - 0 - 1 - 2 - 3 required: false description: > Specify the retrieve strategy on redundant data. The numbers stand for NONE, DATA, PROX and RACE, respectively. Strategy NONE means no prefetching takes place. Strategy DATA means only data chunks are prefetched. Strategy PROX means only chunks that are close to the node are prefetched. Strategy RACE means all chunks are prefetched: n data chunks and k parity chunks. The first n chunks to arrive are used to reconstruct the file. Multiple strategies can be used in a fallback cascade if the swarm redundancy fallback mode is set to true. The default strategy is NONE, DATA, falling back to PROX, falling back to RACE SwarmRedundancyFallbackModeParameter: in: header name: swarm-redundancy-fallback-mode schema: type: boolean required: false description: > Specify if the retrieve strategies (chunk prefetching on redundant data) are used in a fallback cascade. The default is true. SwarmRedundancyLevelParameter: *ref_1 SwarmChunkRetrievalTimeoutParameter: in: header name: swarm-chunk-retrieval-timeout schema: $ref: '#/components/schemas/Duration' required: false description: | Specify the timeout for chunk retrieval. The default is 30 seconds. SwarmActTimestamp: in: header name: swarm-act-timestamp schema: type: integer format: int64 required: false description: ACT history Unix timestamp SwarmActPublisher: in: header name: swarm-act-publisher schema: $ref: '#/components/schemas/PublicKey' required: false description: ACT content publisher's public key SwarmActHistoryAddress: *ref_2 SwarmTagParameter: *ref_3 SwarmPostageStamp: in: header name: swarm-postage-stamp description: | Postage stamp for the corresponding chunk in the request. \ It is required if Swarm-Postage-Batch-Id header is missing \ It consists of: \ - batch ID - 0:32 bytes \ - postage index (bucket and bucket index) - 32:40 bytes \ - timestamp - 40:48 bytes \ - signature - 48:113 bytes schema: $ref: '#/components/schemas/HexString' SwarmAct: in: header name: swarm-act schema: type: boolean default: 'false' required: false description: Determines if the uploaded data should be treated as ACT content SwarmPostageBatchId: *ref_4 SwarmPinParameter: *ref_5 SwarmEncryptParameter: *ref_6 ContentTypePreserved: in: header name: Content-Type schema: type: string description: The specified content-type is preserved for download of the asset SwarmCollection: in: header name: swarm-collection schema: type: boolean required: false description: Upload file/files as a collection SwarmIndexDocumentParameter: in: header name: swarm-index-document schema: type: string example: index.html required: false description: Default file to be referenced on path, if exists under that path SwarmErrorDocumentParameter: in: header name: swarm-error-document schema: type: string example: error.html required: false description: >- Configure custom error document to be returned when a specified path can not be found in collection SwarmDeferredUpload: *ref_7 SwarmOnlyRootChunkParameter: in: header name: swarm-only-root-chunk schema: type: boolean required: false description: Returns only the root chunk of the content GasPriceParameter: in: header name: gas-price schema: $ref: '#/components/schemas/GasPrice' required: false description: Gas price for transaction GasLimitParameter: in: header name: gas-limit schema: $ref: '#/components/schemas/GasLimit' required: false description: Gas limit for transaction