openapi: 3.0.3 info: version: 8.1.0 title: Bee API description: "API endpoints for interacting with the Swarm network, supporting file operations, messaging, and node management" externalDocs: description: Browse the documentation at the Swarm Docs url: "https://docs.ethswarm.org" servers: - url: "http://{apiRoot}:{port}/v1" variables: apiRoot: default: "localhost" description: Base address of the local bee node main API port: default: "1633" description: Service port provided in bee node config - url: "http://{apiRoot}:{port}" variables: apiRoot: default: "localhost" description: Base address of the local bee node main API port: default: "1633" description: Service port provided in bee node config paths: "/grantee": post: summary: "Create a grantee list" tags: - ACT parameters: - in: header schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" name: swarm-postage-batch-id required: true - in: header schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter" name: swarm-tag required: false - in: header schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter" name: swarm-pin required: false - in: header schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload" name: swarm-deferred-upload required: false - in: header schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" name: swarm-act-history-address required: false - in: header schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" name: swarm-redundancy-level 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/{address}": get: summary: "Get the grantee list" tags: - ACT parameters: - in: path name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmEncryptedReference" required: true description: Grantee list reference - in: header schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" name: swarm-redundancy-level required: false responses: "200": description: OK content: application/json: schema: type: array items: $ref: "SwarmCommon.yaml#/components/schemas/PublicKey" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" patch: summary: "Update the grantee list" description: "Add or remove grantees from an existing grantee list" tags: - ACT parameters: - in: path name: address 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 - in: header schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" name: swarm-redundancy-level required: false requestBody: required: true content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/ActGranteesPatchRequest" responses: "200": description: OK content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/ActGranteesOperationResponse" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" "/bytes": post: summary: "Upload data" tags: - Bytes parameters: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmEncryptParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" 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/{address}": get: summary: "Retrieve data by reference" tags: - Bytes parameters: - in: path name: address 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/SwarmLookaheadBufferSizeParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" responses: "200": description: Retrieved content specified by reference content: application/octet-stream: schema: type: string format: binary "400": $ref: "SwarmCommon.yaml#/components/responses/400" default: description: Default response head: summary: Retrieve headers containing the content type and length for the reference tags: - Bytes parameters: - in: path name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: Swarm address of chunk - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" responses: "200": description: The chunk exists. headers: Content-Type: description: The MIME type of the resource (e.g., application/octet-stream). schema: type: string example: application/octet-stream Content-Length: description: The size of the chunk in bytes. schema: type: integer example: 1024 Access-Control-Expose-Headers: description: Headers exposed for CORS. schema: type: string example: Accept-Ranges, Content-Encoding "400": $ref: "SwarmCommon.yaml#/components/responses/400" "404": $ref: "SwarmCommon.yaml#/components/responses/404" default: description: Default response "/chunks": post: summary: "Upload a chunk" tags: - Chunk parameters: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter" - in: header name: swarm-postage-batch-id schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" required: false - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageStamp" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" requestBody: description: Chunk binary data containing at least 8 bytes. content: application/octet-stream: schema: type: string format: binary responses: "201": description: OK headers: "swarm-tag": description: Tag UID from the request `swarm-tag` header if provided. schema: $ref: "SwarmCommon.yaml#/components/schemas/Uid" "swarm-act-history-address": $ref: "SwarmCommon.yaml#/components/headers/SwarmActHistoryAddress" content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/ReferenceResponse" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "402": $ref: "SwarmCommon.yaml#/components/responses/402" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/chunks/stream": get: summary: "Stream chunks for upload" description: "Establishes a WebSocket connection for streaming chunks. Each uploaded chunk receives a binary acknowledgment (`0`). Chunks are sent as binary messages. When a tag is specified, chunks are stored locally and uploaded to the network after the stream closes. Without a tag, chunks are directly uploaded to the network as they arrive." tags: - Chunk parameters: - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter" - in: query name: swarm-tag schema: $ref: "SwarmCommon.yaml#/components/schemas/Uid" required: false description: "Associate upload with an existing Tag UID (use when WebSocket client cannot set custom headers)" - in: header name: swarm-postage-batch-id description: "ID of Postage Batch that is used to upload data with. Optional when chunks include pre-signed postage stamps." required: false schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" responses: "200": description: "Connection established" "400": $ref: "SwarmCommon.yaml#/components/responses/400" default: description: Default response "/bzz": post: summary: "Upload a file or collection of files" description: "Upload single files or collections of files. For a single file, `Content-Type` is optional: when present it is stored as metadata as-is; when absent the server infers a type from the start of the body. To upload a collection, send a multipart request with files in the form data with appropriate headers. Tar files can be uploaded with the `swarm-collection` header to extract and upload the directory structure. Without the `swarm-collection` header, requests are treated as single file uploads. Multipart requests are always treated as collections; use the `swarm-index-document` header to specify a single file to serve." tags: - BZZ parameters: - in: query name: name schema: $ref: "SwarmCommon.yaml#/components/schemas/FileName" required: false description: Filename when uploading single file - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmEncryptParameter" - $ref: "SwarmCommon.yaml#/components/parameters/ContentTypePreserved" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCollection" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmIndexDocumentParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmErrorDocumentParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" requestBody: content: multipart/form-data: schema: properties: file: type: array items: type: string format: binary application/octet-stream: schema: type: string format: binary application/x-tar: schema: type: string format: binary responses: "201": description: OK headers: "swarm-tag": $ref: "SwarmCommon.yaml#/components/headers/SwarmTag" "etag": $ref: "SwarmCommon.yaml#/components/headers/ETag" "swarm-act-history-address": $ref: "SwarmCommon.yaml#/components/headers/SwarmActHistoryAddress" content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/ReferenceResponse" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "402": $ref: "SwarmCommon.yaml#/components/responses/402" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/bzz/{address}": get: summary: "Retrieve a file or index document from a collection" tags: - BZZ parameters: - in: path name: address 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/SwarmLookaheadBufferSizeParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" responses: "200": description: OK # "swarm-feed-index": # $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedIndex" content: application/octet-stream: schema: type: string format: binary headers: "swarm-feed-resolved-version": $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedResolvedVersion" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response head: summary: Retrieve headers with content type and length for the reference tags: - BZZ parameters: - in: path name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: Swarm address of chunk - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" responses: "200": description: Chunk exists "400": $ref: "SwarmCommon.yaml#/components/responses/400" "404": $ref: "SwarmCommon.yaml#/components/responses/404" default: description: Default response "/bzz/{address}/{path}": get: summary: "Retrieve a file from a collection by path" tags: - BZZ parameters: - in: path name: address 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" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmLookaheadBufferSizeParameter" responses: "200": description: OK content: application/octet-stream: schema: type: string format: binary headers: "swarm-feed-resolved-version": $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedResolvedVersion" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/tags": get: summary: Get list of tags tags: - Tag parameters: - in: query name: offset schema: type: integer minimum: 0 default: 0 required: false description: The number of items to skip before starting to collect the result set. - in: query name: limit schema: type: integer minimum: 1 maximum: 1000 default: 100 required: false description: The numbers of items to return. responses: "200": description: List of tags content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/TagsList" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response post: summary: "Create Tag" tags: - Tag description: Tags can be thought of as upload sessions which can be tracked using the tags endpoint. It will keep track of the chunks that are uploaded as part of the tag and will push them out to the network once a done split is called on the Tag. This happens internally if you use the `Swarm-Deferred-Upload` header. responses: "201": description: New Tag Info content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/NewTagResponse" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/tags/{id}": get: summary: "Get Tag information using Uid" tags: - Tag parameters: - in: path name: id 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: id 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: id schema: $ref: "SwarmCommon.yaml#/components/schemas/Uid" required: true description: Uid requestBody: description: Can contain swarm hash to use for the tag required: false content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Address" responses: "200": description: OK content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Response" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/pins/{reference}": parameters: - in: path name: reference schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmOnlyReference" required: true description: Swarm reference of the root hash post: summary: Pin a root hash by reference tags: - Pinning parameters: - in: header schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" name: swarm-redundancy-level required: false responses: "200": description: Pin already exists content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Response" "201": description: New pin with root reference was created content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Response" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response delete: summary: Unpin a root hash by reference tags: - Pinning responses: "200": description: Root hash has been unpinned content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Response" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response get: summary: Get the pinning status of a root hash tags: - Pinning responses: "200": description: The pinned root hash reference content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmOnlyReference" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/pins": get: summary: Get the list of pinned root hash references tags: - Pinning responses: "200": description: List of pinned root hash references content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmOnlyReferencesList" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/pins/check": get: summary: Validate pinned chunks integrity description: | Returns a stream of newline-delimited JSON objects (NDJSON), one per pinned reference checked. The response uses chunked transfer encoding; clients should parse each line as an independent `PinIntegrityResponse` object rather than buffering the body into a single JSON value. tags: - Pinning parameters: - in: query name: ref schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmOnlyReference" required: false description: Optional reference to check; if not provided, all pinned references are checked responses: "200": description: NDJSON stream of integrity results, one object per line content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/PinCheckResponse" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/pss/send/{topic}/{targets}": post: summary: Send a message using the Postal Service for Swarm tags: - Postal Service for Swarm parameters: - in: path name: topic schema: $ref: "SwarmCommon.yaml#/components/schemas/PssTopic" required: true description: Topic name - in: path name: targets schema: $ref: "SwarmCommon.yaml#/components/schemas/PssTargets" required: true description: Target message address prefix. If multiple targets are specified, only one would be matched. - in: query name: recipient schema: $ref: "SwarmCommon.yaml#/components/schemas/PssRecipient" required: false description: Recipient publickey - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" responses: "201": description: Subscribed to topic "400": $ref: "SwarmCommon.yaml#/components/responses/400" "402": $ref: "SwarmCommon.yaml#/components/responses/402" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/pss/subscribe/{topic}": get: summary: Subscribe to messages on a topic tags: - Postal Service for Swarm parameters: - in: path name: topic schema: $ref: "SwarmCommon.yaml#/components/schemas/PssTopic" required: true description: Topic name responses: "200": description: Establishes a WebSocket subscription for incoming messages on the topic "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/gsoc/subscribe/{address}": get: summary: Subscribe to GSOC payloads tags: - GSOC parameters: - in: path name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: "Single Owner Chunk address (which may have multiple payloads)" responses: "200": description: Establishes a WebSocket subscription for incoming messages on the Single Owner Chunk address "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/soc/{owner}/{id}": post: summary: Upload a Single Owner Chunk tags: - Single owner chunk parameters: - in: path name: owner schema: $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress" required: true description: Ethereum address of the chunk owner - in: path name: id schema: $ref: "SwarmCommon.yaml#/components/schemas/HexString" required: true description: Unique identifier for the chunk - in: query name: sig schema: $ref: "SwarmCommon.yaml#/components/schemas/HexString" required: true description: Signature - in: header name: swarm-postage-batch-id schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" required: false description: ID of the postage batch to use. Either this or `swarm-postage-stamp` must be supplied. - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageStamp" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmTagParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmDeferredUpload" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" requestBody: required: true description: The SOC binary data, composed of the span (8 bytes) and up to 4KB of payload. content: application/octet-stream: schema: type: string format: binary responses: "201": description: Created content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/ReferenceResponse" headers: "swarm-tag": description: Tag UID, returned when an upload session is in use (either because `swarm-tag` was supplied, `swarm-deferred-upload` requested deferred mode, or `swarm-pin` was set). schema: $ref: "SwarmCommon.yaml#/components/schemas/Uid" "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" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response get: summary: Retrieve Single Owner Chunk data tags: - Single owner chunk parameters: - in: path name: owner schema: $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress" required: true description: Ethereum address of the Owner of the SOC - in: path name: id schema: $ref: "SwarmCommon.yaml#/components/schemas/HexString" required: true description: Unique identifier for the chunk data - $ref: "SwarmCommon.yaml#/components/parameters/SwarmOnlyRootChunkParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyStrategyParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter" responses: "200": description: Related Single Owner Chunk data headers: "swarm-soc-signature": $ref: "SwarmCommon.yaml#/components/headers/SwarmSocSignature" content: application/octet-stream: schema: type: string format: binary "400": $ref: "SwarmCommon.yaml#/components/responses/400" "401": $ref: "SwarmCommon.yaml#/components/responses/401" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/feeds/{owner}/{topic}": post: summary: Create a feed root manifest tags: - Feed parameters: - in: path name: owner schema: $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress" required: true description: Ethereum address of the feed owner - in: path name: topic schema: $ref: "SwarmCommon.yaml#/components/schemas/HexString" required: true description: Topic identifier for the feed - in: query name: type schema: $ref: "SwarmCommon.yaml#/components/schemas/FeedType" required: false description: "Feed indexing scheme (default: sequence)" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPinParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmPostageBatchId" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmAct" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" - in: header schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" name: swarm-redundancy-level required: false description: Redundancy level for the feed manifest upload pipeline and ACT encryption responses: "201": description: Created content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/ReferenceResponse" headers: "swarm-act-history-address": $ref: "SwarmCommon.yaml#/components/headers/SwarmActHistoryAddress" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "401": $ref: "SwarmCommon.yaml#/components/responses/401" "402": $ref: "SwarmCommon.yaml#/components/responses/402" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response get: summary: Retrieve the latest feed update tags: - Feed parameters: - in: path name: owner schema: $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress" required: true description: Ethereum address of the feed owner - in: path name: topic schema: $ref: "SwarmCommon.yaml#/components/schemas/HexString" required: true description: Topic identifier for the feed - in: query name: at schema: type: integer required: false description: "Timestamp of the update (default: now)" - in: query name: after schema: type: integer required: false description: "Start index (default: 0)" - in: query name: type schema: $ref: "SwarmCommon.yaml#/components/schemas/FeedType" required: false description: "Feed indexing scheme (default: sequence)" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmOnlyRootChunkParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyStrategyParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyFallbackModeParameter" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmChunkRetrievalTimeoutParameter" responses: "200": description: Latest feed update headers: "swarm-soc-signature": $ref: "SwarmCommon.yaml#/components/headers/SwarmSocSignature" "swarm-feed-index": $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedIndex" "swarm-feed-index-next": $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedIndexNext" "swarm-feed-resolved-version": $ref: "SwarmCommon.yaml#/components/headers/SwarmFeedResolvedVersion" content: application/octet-stream: schema: type: string format: binary "400": $ref: "SwarmCommon.yaml#/components/responses/400" "401": $ref: "SwarmCommon.yaml#/components/responses/401" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/stewardship/{address}": get: summary: "Check content availability" tags: - Stewardship parameters: - in: path name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference" required: true description: "Root hash of content (can be of any type: collection, file, chunk)" - in: header schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" name: swarm-redundancy-level required: false responses: "200": description: Returns if the content is retrievable content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/IsRetrievableResponse" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response put: summary: "Re-upload content by reference" tags: - Stewardship parameters: - in: path name: address 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 required: true description: Postage batch to use for re-upload. The chunks are re-stamped with this batch. - in: header schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmRedundancyLevelParameter" name: swarm-redundancy-level required: false responses: "200": description: OK "400": $ref: "SwarmCommon.yaml#/components/responses/400" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/addresses": get: summary: Get overlay and underlay addresses of the node tags: - Connectivity responses: "200": description: Own node underlay and overlay addresses content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Addresses" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/health": get: summary: Get the overall health status of the node description: | Health Status will indicate node healthiness. If node is unhealthy please check node logs for errors. tags: - Status responses: "200": description: Health Status of node content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/HealthStatus" default: description: Default response "/readiness": get: summary: Check if the node is ready to accept traffic tags: - Status responses: "200": description: Indicates that node is ready $ref: "SwarmCommon.yaml#/components/responses/200" "400": description: Indicates that node is not ready $ref: "SwarmCommon.yaml#/components/responses/400" default: description: Default response "/balances": get: summary: Get balances with all known peers tags: - Balance responses: "200": description: Own balances with all known peers content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Balances" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/balances/{peer}": get: summary: Get the balance with a specific peer tags: - Balance parameters: - in: path name: peer schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: Swarm address of peer responses: "200": description: Balance with the specific peer content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Balance" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/blocklist": get: summary: Get a list of blocklisted peers tags: - Connectivity responses: "200": description: Returns overlay addresses of blocklisted peers content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/BlockListedPeers" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/consumed": get: summary: Get past due consumption balances with all known peers tags: - Balance responses: "200": description: Own past due consumption balances with all known peers content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Balances" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/consumed/{peer}": get: summary: Get past due consumption balance with a specific peer tags: - Balance parameters: - in: path name: peer schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: Swarm address of peer responses: "200": description: Past-due consumption balance with the specific peer content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Balance" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/chequebook/address": get: summary: Get the chequebook contract address tags: - Chequebook responses: "200": description: Ethereum address of chequebook contract content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/ChequebookAddress" "/chequebook/balance": get: summary: Get the balance of the chequebook tags: - Chequebook responses: "200": description: Balance of the chequebook content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/ChequebookBalance" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/chunks/{address}": get: summary: "Retrieve a chunk" tags: - Chunk parameters: - in: path name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmReference" required: true description: Swarm address of chunk - in: header schema: $ref: "SwarmCommon.yaml#/components/parameters/SwarmCache" name: swarm-cache required: false - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" responses: "200": description: Retrieved chunk content content: application/octet-stream: schema: type: string format: binary "400": $ref: "SwarmCommon.yaml#/components/responses/400" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response head: summary: Check if a chunk exists locally tags: - Chunk parameters: - in: path name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: Swarm address of chunk - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActTimestamp" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActPublisher" - $ref: "SwarmCommon.yaml#/components/parameters/SwarmActHistoryAddress" responses: "200": description: Chunk exists "400": $ref: "SwarmCommon.yaml#/components/responses/400" "404": $ref: "SwarmCommon.yaml#/components/responses/404" default: description: Default response "/envelope/{address}": post: summary: "Create a postage stamp for a chunk" tags: - Envelope parameters: - in: path name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: Swarm address of the chunk to stamp - 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/{multi-address}": post: summary: Connect to a peer address tags: - Connectivity parameters: - in: path allowReserved: true name: multi-address schema: $ref: "SwarmCommon.yaml#/components/schemas/MultiAddress" required: true description: Underlay address of peer responses: "200": description: Returns overlay address of connected peer content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Address" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/reservestate": get: summary: Get the reserve state tags: - Status responses: "200": description: Reserve State content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/ReserveState" default: description: Default response "/chainstate": get: summary: Get the chain state tags: - Status responses: "200": description: Chain State content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/ChainState" default: description: Default response "/debugstore": get: summary: Get a snapshot of local storage debug info tags: - Status responses: "200": description: Local storage debug info content: application/json: schema: type: object properties: Upload: type: object properties: TotalUploaded: { type: integer } TotalSynced: { type: integer } PendingUpload: { type: integer } Pinning: type: object properties: TotalCollections: { type: integer } TotalChunks: { type: integer } Cache: type: object properties: Size: { type: integer } Capacity: { type: integer } Reserve: type: object properties: SizeWithinRadius: { type: integer } TotalSize: { type: integer } Capacity: { type: integer } LastBinIDs: type: array items: { type: integer } Epoch: { type: integer } ChunkStore: type: object properties: TotalChunks: { type: integer } SharedSlots: { type: integer } ReferenceCount: { type: integer } "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/node": get: summary: Get node information tags: - Status responses: "200": description: Information about the node content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Node" default: description: Default response "/peers": get: summary: Get the list of connected peers tags: - Connectivity responses: "200": description: Returns overlay addresses of connected peers content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Peers" default: description: Default response "/peers/{address}": delete: summary: Disconnect from a peer tags: - Connectivity parameters: - in: path name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: Swarm address of peer responses: "200": description: Peer has been disconnected content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Response" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/pingpong/{address}": post: summary: Ping a peer to measure latency tags: - Connectivity parameters: - in: path name: address schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: Swarm address of peer responses: "200": description: Returns round trip time for given peer content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/RttMs" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/settlements/{peer}": get: summary: Get settlement amounts sent and received with a peer tags: - Settlements parameters: - in: path name: peer schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: Swarm address of peer responses: "200": description: Settlement amounts sent and received with the peer content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Settlement" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/settlements": get: summary: Get settlements with all known peers and totals tags: - Settlements responses: "200": description: Settlements with all known peers and total amount sent or received content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Settlements" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/timesettlements": get: summary: Get time-based settlements with all known peers and totals tags: - Settlements responses: "200": description: Time based settlements with all known peers and total amount sent or received content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/Settlements" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/topology": get: summary: Get the network topology tags: - Connectivity responses: "200": description: Swarm topology of the bee node content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/BzzTopology" "/welcome-message": get: summary: Get the P2P welcome message tags: - Connectivity responses: "200": description: Welcome message content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/WelcomeMessage" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response post: summary: Set the P2P welcome message tags: - Connectivity requestBody: content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/WelcomeMessage" responses: "200": description: OK content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/HealthStatus" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/chequebook/cashout/{peer}": get: summary: Get the last cashout status for a peer parameters: - in: path name: peer schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: Swarm address of peer tags: - Chequebook responses: "200": description: Cashout status content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/SwapCashoutStatus" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response post: summary: Cash out the last cheque for a peer parameters: - in: path name: peer schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: Swarm address of peer - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter" tags: - Chequebook responses: "201": description: Cheque has been cashed out content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/TransactionResponse" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "429": $ref: "SwarmCommon.yaml#/components/responses/429" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/chequebook/cheque/{peer}": get: summary: Get the last cheques for a peer parameters: - in: path name: peer schema: $ref: "SwarmCommon.yaml#/components/schemas/SwarmAddress" required: true description: Swarm address of peer tags: - Chequebook responses: "200": description: The last cheques for the peer content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/ChequePeerResponse" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/chequebook/cheque": get: summary: Get the last cheques for all peers tags: - Chequebook responses: "200": description: The last cheques for all peers content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/ChequeAllPeersResponse" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/chequebook/deposit": post: summary: Deposit tokens into the chequebook parameters: - in: query name: amount schema: type: integer required: true description: Amount of tokens to deposit - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" tags: - Chequebook responses: "200": description: Transaction hash of the deposit transaction content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/TransactionResponse" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/chequebook/withdraw": post: summary: Withdraw tokens from the chequebook parameters: - in: query name: amount schema: type: integer required: true description: Amount of tokens to withdraw - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" tags: - Chequebook responses: "200": description: Transaction hash of the withdraw transaction content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/TransactionResponse" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/transactions": get: summary: Get list of pending transactions tags: - Transaction responses: "200": description: List of pending transactions content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/PendingTransactionsResponse" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/transactions/{hash}": get: summary: Retrieve transaction information parameters: - in: path name: hash schema: $ref: "SwarmCommon.yaml#/components/schemas/TransactionHash" required: true description: Hash of the transaction tags: - Transaction responses: "200": description: Transaction information content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/TransactionInfo" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response post: summary: Rebroadcast a transaction parameters: - in: path name: hash 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: hash schema: $ref: "SwarmCommon.yaml#/components/schemas/TransactionHash" required: true description: Hash of the transaction - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" tags: - Transaction responses: "200": description: Hash of the transaction content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/TransactionResponse" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/stamps": get: summary: Get postage stamps for this node tags: - Postage Stamps responses: "200": description: An array of postage stamps content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/DebugPostageBatchesResponse" "404": $ref: "SwarmCommon.yaml#/components/responses/404" default: description: Default response "/stamps/{batch_id}": parameters: - in: path name: batch_id schema: $ref: "SwarmCommon.yaml#/components/schemas/BatchID" required: true description: Swarm address of the stamp get: summary: Get an individual postage batch status tags: - Postage Stamps responses: "200": description: Returns an individual postage batch state content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/DebugPostageBatch" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "400": $ref: "SwarmCommon.yaml#/components/responses/400" default: description: Default response patch: summary: Update the label of an existing postage batch tags: - Postage Stamps requestBody: required: true content: application/json: schema: type: object properties: label: type: string description: New label for the postage batch required: - label responses: "200": description: Label updated successfully 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 "/stamps/{batch_id}/buckets": parameters: - in: path name: batch_id schema: $ref: "SwarmCommon.yaml#/components/schemas/BatchID" required: true description: Swarm address of the stamp get: summary: Get extended bucket data of a batch tags: - Postage Stamps responses: "200": description: Returns extended bucket data of the provided batch ID content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/PostageStampBuckets" "404": $ref: "SwarmCommon.yaml#/components/responses/404" "400": $ref: "SwarmCommon.yaml#/components/responses/400" default: description: Default response "/stamps/{amount}/{depth}": post: summary: Buy a new postage batch. description: | Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance! tags: - Postage Stamps parameters: - in: path name: amount schema: $ref: "SwarmCommon.yaml#/components/schemas/BigInt" required: true description: Amount of BZZ added that the postage batch will have. - in: path name: depth schema: type: integer required: true description: Batch depth (logarithm) specifying the maximum number of chunks this stamp can cover. Must be greater than the default bucket depth (16) - in: query name: label schema: type: string required: false description: An optional label for this batch - in: header name: immutable schema: type: boolean required: false - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter" responses: "201": description: Returns the newly created postage batch ID content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/BatchIDResponse" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "429": $ref: "SwarmCommon.yaml#/components/responses/429" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/stamps/topup/{batch_id}/{amount}": patch: summary: Top up an existing postage batch. description: | Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance! tags: - Postage Stamps parameters: - in: path name: batch_id schema: $ref: "SwarmCommon.yaml#/components/schemas/BatchID" required: true description: Batch ID to top up - in: path name: amount schema: type: integer required: true description: Amount of BZZ per chunk to top up to an existing postage batch. - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter" responses: "202": description: Returns the postage batch ID that was topped up content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/BatchIDResponse" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "429": $ref: "SwarmCommon.yaml#/components/responses/429" "402": $ref: "SwarmCommon.yaml#/components/responses/402" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/stamps/dilute/{batch_id}/{depth}": patch: summary: Dilute an existing postage batch. description: | Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance! tags: - Postage Stamps parameters: - in: path name: batch_id schema: $ref: "SwarmCommon.yaml#/components/schemas/BatchID" required: true description: Batch ID to dilute - in: path name: depth schema: type: integer required: true description: The new batch depth, which must be greater than the current depth - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter" responses: "202": description: Returns the postage batch ID that was diluted. content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/BatchIDResponse" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "429": $ref: "SwarmCommon.yaml#/components/responses/429" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/batches": get: summary: Get all globally available postage batches tags: - Postage Stamps responses: "200": description: An array of all available and valid postage batches content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/DebugPostageAllBatchesResponse" default: description: Default response "/batches/{batch_id}": parameters: - in: path name: batch_id schema: $ref: "SwarmCommon.yaml#/components/schemas/BatchID" required: true description: ID of the postage batch get: summary: Get a single globally available postage batch by ID tags: - Postage Stamps responses: "200": description: The postage batch state content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/PostageBatchShort" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "404": $ref: "SwarmCommon.yaml#/components/responses/404" default: description: Default response "/rchash/{depth}/{anchor1}/{anchor2}": get: summary: Get reserve commitment hash with sample proofs tags: - RChash parameters: - in: path name: depth schema: type: integer minimum: 0 default: 0 required: true description: The storage depth. - in: path name: anchor1 schema: $ref: "SwarmCommon.yaml#/components/schemas/HexString" required: true description: The first anchor. - in: path name: anchor2 schema: $ref: "SwarmCommon.yaml#/components/schemas/HexString" required: true description: The second anchor. responses: "200": description: Reserve sample response content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/ApiRCHashResponse" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/accounting": get: summary: Get accounting values for all known peers tags: - Balance responses: "200": description: Own accounting associated values with all known peers content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/PeerAccountingData" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/redistributionstate": get: summary: Get the node's redistribution game status tags: - RedistributionState responses: "200": description: Redistribution status info content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/RedistributionStatusResponse" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/wallet": get: summary: Get wallet balance for BZZ and xDAI tags: - Wallet responses: "200": description: Wallet balance info content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/WalletResponse" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/wallet/withdraw/{coin}": post: summary: Withdraw BZZ or xDAI to a whitelisted address tags: - Wallet parameters: - in: query name: amount required: true schema: $ref: "SwarmCommon.yaml#/components/schemas/BigInt" - in: query name: address required: true schema: $ref: "SwarmCommon.yaml#/components/schemas/EthereumAddress" - in: path name: coin required: true schema: $ref: "SwarmCommon.yaml#/components/schemas/WithdrawCoin" responses: "200": content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/WalletTxResponse" description: OK "400": $ref: "SwarmCommon.yaml#/components/responses/400" description: Amount greater than balance or coin is other than BZZ/xDAI "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/stake/withdrawable": get: summary: Get the withdrawable staked amount. description: This endpoint fetches any amount that is possible to withdraw as surplus. tags: - Staking responses: "200": description: OK content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/GetWithdrawableResponse" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response delete: summary: Withdraw the extra withdrawable staked amount. description: This endpoint withdraws any amount that is possible to withdraw as surplus. tags: - Staking parameters: - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter" responses: "200": description: OK content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/StakeTransactionResponse" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/stake/{amount}": post: summary: Deposit an amount for staking. description: Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance. tags: - Staking parameters: - in: path name: amount schema: type: string required: true description: Amount of BZZ added that will be deposited for staking. - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter" responses: "200": description: OK content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/StakeTransactionResponse" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/stake": get: summary: Get the staked amount. description: This endpoint fetches the total staked amount from the blockchain. tags: - Staking responses: "200": description: OK content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/GetStakeResponse" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response delete: summary: Withdraw all previously staked amounts. description: Be aware, this endpoint can only be called when the contract is paused and undergoing migration to a new contract. tags: - Staking parameters: - $ref: "SwarmCommon.yaml#/components/parameters/GasPriceParameter" - $ref: "SwarmCommon.yaml#/components/parameters/GasLimitParameter" responses: "200": description: OK content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/StakeTransactionResponse" "400": $ref: "SwarmCommon.yaml#/components/responses/400" "500": $ref: "SwarmCommon.yaml#/components/responses/500" default: description: Default response "/loggers": get: summary: Get all available loggers. tags: - Logging responses: "200": description: Returns an array of all available loggers, also represented in short form in a tree. content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/LoggerResponse" "400": $ref: "SwarmCommon.yaml#/components/responses/400" default: description: Default response "/loggers/{exp}": get: summary: Get all available loggers that match the specified expression. parameters: - in: path name: exp schema: $ref: "SwarmCommon.yaml#/components/schemas/LoggerExp" required: true description: Regular expression or a subsystem that matches the logger(s). tags: - Logging responses: "200": description: Returns an array of all available loggers that matches given expression, also represented in short form in a tree. content: application/json: schema: $ref: "SwarmCommon.yaml#/components/schemas/LoggerResponse" "400": $ref: "SwarmCommon.yaml#/components/responses/400" default: description: Default response "/loggers/{exp}/{verbosity}": 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). - in: path name: verbosity schema: type: string enum: [none, error, warning, info, debug, all] required: true description: Verbosity level to apply to the matching 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.