openapi: "3.0.0" info: title: Renterd API version: 2.0.0 description: API that caters to both casual users seeking straightforward data storage and developers requiring a robust API for building apps on Sia tags: - name: authentication description: API authentication - name: autopilot description: Autopilot configuration and operations - name: worker description: Worker operations and status - name: bus description: Bus operations and management paths: /api/auth: post: tags: - authentication summary: Create a new authentication token description: Creates a new authentication token that is returned via the 'renterd_auth' cookie which is set by the server and the json response body. The token can be used as a cookie or as the 'apikey' query parameter for authentication. parameters: - name: validity description: The duration in milliseconds for which the token will be valid in: query required: true schema: $ref: "#/components/schemas/DurationMS" responses: "200": description: Successfully created a new token content: application/json: schema: type: object properties: token: type: string pattern: "^[a-fA-F0-9]{32}$" description: A hex-encoded string representing the token "400": description: Bad request ############################# # # Autopilot routes # ############################# /autopilot/config/evaluate: post: tags: - autopilot summary: Evaluate autopilot configuration description: Evaluates the provided autopilot configuration and returns some information about the hosts that would be considered usable using that configuration. If possible, it also returns a recommendation for a better configuration that would allow for forming contracts with more hosts. requestBody: content: application/json: schema: type: object properties: autopilotConfig: $ref: "#/components/schemas/AutopilotConfig" gougingSettings: $ref: "#/components/schemas/GougingSettings" redundancySettings: $ref: "#/components/schemas/RedundancySettings" responses: "200": description: The evaluated autopilot configuration content: application/json: schema: type: object properties: hosts: type: integer format: uin64 description: Number of hosts available usable: type: integer format: uint64 description: Number of hosts that the autopilot could form contracts with using the provided config unusable: type: object properties: blocked: type: integer format: uint64 description: Number of hosts unavailable due to being blocklisted gouging: type: object properties: contract: type: integer format: uint64 description: Number of hosts that fail the contract gouging checks download: type: integer format: uint64 description: Number of hosts that fail the download gouging checks gouging: type: integer format: uint64 description: Number of hosts that fail the general gouging checks pruning: type: integer format: uint64 description: Number of hosts that fail the pruning gouging checks upload: type: integer format: uint64 description: Number of hosts that fail the upload gouging checks lowMaxDuration: type: integer format: uint64 description: Number of hosts that have a max contract duration that is too low notAcceptingContracts: type: integer format: uint64 description: Number of hosts that are not accepting contracts notScanned: type: integer format: uint64 description: Number of hosts that haven't been successfully scanned yet recommendation: $ref: "#/components/schemas/ConfigRecommendation" "400": description: Malformed request content: text/plain: schema: type: string examples: missingRequiredFields: summary: Missing required fields value: "missing required fields in configuration, amount must be set" "500": description: Internal server error content: text/plain: schema: type: string /autopilot/state: get: tags: - autopilot summary: Get the autopilot state description: Returns the current state of the autopilot, including migration, pruning, and scanning status. responses: "200": description: The current state of the autopilot content: application/json: schema: type: object allOf: - $ref: "#/components/schemas/BuildState" properties: enabled: type: boolean description: Whether the autopilot is enabled migrating: type: boolean description: Indicates if the autopilot is currently migrating migratingLastStart: type: string format: date-time description: When migration last started pruning: type: boolean description: Indicates if the autopilot is currently pruning pruningLastStart: type: string format: date-time description: When pruning last started scanning: type: boolean description: Indicates if the autopilot is currently scanning scanningLastStart: type: string format: date-time description: When scanning last started uptimeMs: type: integer format: int64 description: The autopilot uptime in milliseconds startTime: type: string format: date-time description: When the autopilot was started /autopilot/trigger: post: tags: - autopilot summary: Wake up autopilot description: Triggers the autopilot to start an iteration of contract maintenance and host scanning. requestBody: content: application/json: schema: type: object properties: forceScan: type: boolean description: If true, the autopilot force a new batch of host scans even if it recently scanned the hosts. default: false responses: "200": description: Successfully attempted to trigger the autopilot content: application/json: schema: type: object properties: triggered: type: boolean description: Indicates whether the request triggered a new iteration of the maintenance loop. If maintenance was already ongoing, this will be false. "400": description: Malformed request ############################# # # Worker routes # ############################# /worker/accounts: get: tags: - worker summary: Get all worker accounts description: Returns all accounts the worker maintains with hosts for payment. responses: "200": description: Successfully retrieved worker accounts content: application/json: schema: type: array items: $ref: "#/components/schemas/Account" /worker/account/{hostkey}: get: tags: - worker summary: Get a worker account description: Returns the account the worker maintains with the specified host for payment. parameters: - name: hostkey in: path required: true schema: $ref: "#/components/schemas/PublicKey" description: The host's public key responses: "200": description: Successfully retrieved worker account content: application/json: schema: $ref: "#/components/schemas/Account" /worker/account/{id}/resetdrift: post: tags: - worker summary: Reset drift for a worker's account description: Resets the drift for the specified account to 0. Drift is the accumulated delta between the worker's expected balance and the host's actual balance. Used to track if a host is trying to cheat the renter over time. parameters: - name: id in: path required: true schema: allOf: - $ref: "#/components/schemas/PublicKey" - description: The account's ID responses: "200": description: Successfully reset drift for worker account content: application/json: schema: $ref: "#/components/schemas/Account" "404": description: The account was not found content: text/plain: schema: type: string example: "account doesn't exist" /worker/memory: get: tags: - worker summary: Get overview of worker's memory usage. description: Returns the memory usage of the worker for both uploads and downloads. responses: "200": description: Successfully retrieved memory usage content: application/json: schema: type: object properties: download: allOf: - $ref: "#/components/schemas/MemoryStatus" - description: The memory status for downloads upload: allOf: - $ref: "#/components/schemas/MemoryStatus" - description: The memory status for uploads /worker/multipart/{key}: put: tags: - worker summary: Upload a part of an ongoing multipart upload description: Upload a single part of an ongoing multipart upload. Parts can be uploaded in parallel and then combined afterwards. parameters: - name: key description: The key of the file to upload in: path required: true schema: $ref: "#/components/schemas/ObjectKey" - name: bucket description: The name of the bucket the multipart upload belongs to in: query required: true schema: $ref: "#/components/schemas/BucketName" - name: uploadid description: The ID of the ongoing multipart upload in: query required: true schema: $ref: "#/components/schemas/MultipartUploadID" - name: partnumber description: The part number of the part being uploaded in: query required: true schema: $ref: "#/components/schemas/MultipartPartNumber" - name: minshards description: Used to override the minimum number of shards the part should be split into. in: query required: false schema: $ref: "#/components/schemas/RedundancySettingsMinShards" - name: totalshards description: Used to override the total number of shards the part should be split into. in: query required: false schema: $ref: "#/components/schemas/RedundancySettingsTotalShards" - name: encryptionoffset description: The offset of the part within the final object. This is required unless the upload was explicitly created to not be encrypted before erasure coding. in: query required: false schema: type: integer format: uint64 requestBody: content: application/octet-stream: schema: type: string format: binary responses: "200": description: Successfully uploaded part headers: ETag: description: The ETag of the uploaded part schema: $ref: "#/components/schemas/ETag" "400": description: Malformed request "404": description: Bucket or upload weren't found "503": description: Consensus isn't synced /worker/object/{key}: get: tags: - worker summary: Download an object description: Downloads an object from the Sia network. parameters: - name: key description: The key of the file to download in: path required: true schema: $ref: "#/components/schemas/ObjectKey" - name: bucket description: The name of the bucket the object belongs to in: query required: true schema: $ref: "#/components/schemas/BucketName" - name: dl description: If '1' or 'true', forces the 'Content-Disposition' header of the response to be set to 'attachment' in: query required: false schema: type: string example: "dl=1" - name: Range in: header description: The range of bytes to download. If not provided, the entire object will be downloaded. schema: type: string example: "bytes=0-100" responses: "200": description: Successfully downloaded object content: application/octet-stream: schema: type: string format: binary headers: "Accept-Ranges": description: The range units the server supports schema: type: string "Content-Range": description: The range of bytes that were downloaded schema: type: string "Content-Type": description: The content type of the object schema: type: string "ETag": description: The ETag of the downloaded object schema: $ref: "#/components/schemas/ETag" "400": description: Invalid range or missing parameters content: text/plain: schema: type: string example: invalid range "404": description: Object not found content: text/plain: schema: type: string example: object not found "416": description: No overlap between 'Range' and object's content content: text/plain: schema: type: string example: "invalid range: failed to overlap" "500": description: Internal server error content: text/plain: schema: type: string example: "failed to fetch object metadata" put: tags: - worker summary: Upload an object description: Uploads an object to the Sia network. parameters: - name: key description: The key of the file to upload in: path required: true schema: $ref: "#/components/schemas/ObjectKey" - name: bucket description: The name of the bucket the object belongs to in: query required: true schema: $ref: "#/components/schemas/BucketName" - name: minshards description: Used to override the minimum number of shards the object should be split into. in: query required: false schema: $ref: "#/components/schemas/RedundancySettingsMinShards" - name: totalshards description: Used to override the total number of shards the object should be split into. in: query required: false schema: $ref: "#/components/schemas/RedundancySettingsTotalShards" - name: mimetype description: The MIME type of the object in: query required: false schema: $ref: "#/components/schemas/MimeType" requestBody: content: application/octet-stream: schema: type: string format: binary responses: "200": description: Successfully uploaded object headers: ETag: description: The ETag of the uploaded object schema: $ref: "#/components/schemas/ETag" "400": description: Invalid combination of request parameters "404": description: Bucket not found "503": description: Consensus isn't synced delete: tags: - worker summary: Delete an object description: Deletes an object from the database. The data is not removed from the network immediately. Instead, the autopilot prunes data from the contracts periodically, after that happens the host is no longer obliged to store the data and it's effectively removed from the network. parameters: - name: key description: The key of the file to delete in: path required: true schema: $ref: "#/components/schemas/ObjectKey" - name: bucket description: The name of the bucket the object belongs to in: query required: true schema: $ref: "#/components/schemas/BucketName" responses: "200": description: Successfully deleted object "404": description: Object not found /worker/objects/remove: post: tags: - worker summary: Delete a batch of objects with a given prefix description: Deletes all objects with the provided prefix from the database. The data is not removed from the network immediately. Instead, the autopilot prunes data from the contracts periodically, after that happens the host is no longer obliged to store the data and it's effectively removed from the network. requestBody: content: application/json: schema: type: object properties: bucket: allOf: - $ref: "#/components/schemas/BucketName" - description: The name of the bucket the objects belong to prefix: allOf: - $ref: "#/components/schemas/ObjectKey" - description: The prefix of the objects to delete responses: "200": description: Successfully removed objects "400": description: Malformed request content: text/plain: schema: type: string examples: missingBucket: summary: Missing bucket field example value: "'bucket' parameter is required" missingPrefix: summary: Missing prefix field example value: "'prefix' parameter is required" "404": description: Object not found "500": description: Internal server error /worker/state: get: tags: - worker summary: Get the worker's state. description: Returns general information about the work. responses: "200": description: Successfully retrieved worker state content: application/json: schema: type: object allOf: - $ref: "#/components/schemas/BuildState" properties: id: type: string description: The worker's ID startTime: type: string format: date-time description: When the worker was started /worker/stats/downloads: get: tags: - worker summary: Get download statistics description: Returns the download statistics of the worker. responses: "200": description: Successfully retrieved download statistics content: application/json: schema: type: object properties: avgDownloadSpeedMbps: type: number format: float description: The average download speed in Mbps avgOverdrivePct: type: number format: float description: The average overdrive percentage healthyDownloaders: type: integer format: uint64 description: The number of healthy downloaders numDownloaders: type: integer format: uint64 description: The total number of downloaders downloadersStats: type: array items: type: object properties: avgSectorDownloadSpeedMbps: type: number format: float description: The average sector download speed in Mbps hostKey: allOf: - $ref: "#/components/schemas/PublicKey" - description: The host's public key /worker/stats/uploads: get: tags: - worker summary: Get upload statistics description: Returns the upload statistics of the worker. responses: "200": description: Successfully retrieved upload statistics content: application/json: schema: type: object properties: avgUploadSpeedMbps: type: number format: float description: The average upload speed in Mbps avgOverdrivePct: type: number format: float description: The average overdrive percentage healthyUploaders: type: integer format: uint64 description: The number of healthy uploaders numUploaders: type: integer format: uint64 description: The total number of uploaders uploadersStats: type: array items: type: object properties: avgSectorUploadSpeedMbps: type: number format: float description: The average sector upload speed in Mbps hostKey: allOf: - $ref: "#/components/schemas/PublicKey" - description: The host's public key ############################# # # Bus routes # ############################# /bus/accounts: get: tags: - bus summary: Get all accounts parameters: - name: owner in: query required: false schema: type: string description: The owner of the account. This is usually the id of the worker that maintains the account. description: Returns all accounts. responses: "200": description: Successfully retrieved accounts content: application/json: schema: type: array items: $ref: "#/components/schemas/Account" "500": description: Internal server error post: tags: - bus summary: Save accounts description: Saves the provided accounts to the database. requestBody: content: application/json: schema: type: object properties: accounts: type: array items: $ref: "#/components/schemas/Account" responses: "200": description: Successfully saved accounts "400": description: Malformed request content: text/plain: schema: type: string examples: missingOwnerField: summary: Missing owner field example value: "account is missing a valid 'owner' field" "500": description: Internal server error /bus/accounts/fund: post: tags: - bus summary: Fund an account description: Funds the specified account with the provided amount. requestBody: content: application/json: schema: type: object properties: accountID: allOf: - $ref: "#/components/schemas/PublicKey" - description: The ID of the account to fund. amount: allOf: - $ref: "#/components/schemas/Currency" - description: The amount to fund the account with. contractID: allOf: - $ref: "#/components/schemas/FileContractID" - description: The ID of the contract to fund the account with. responses: "200": description: Successfully funded account content: application/json: schema: type: object properties: deposit: allOf: - $ref: "#/components/schemas/Currency" - description: The amount that was deposited into the account "400": description: Malformed request "404": description: Contract not found "500": description: Internal server error /bus/alerts: get: tags: - bus summary: Get all alerts description: Returns all currently registered alerts. parameters: - name: limit in: query description: The maximum number of alerts to return schema: type: integer minimum: -1 default: -1 - name: offset in: query description: The number of alerts to skip schema: type: integer minimum: 0 default: 0 responses: "200": description: Successfully retrieved alerts content: application/json: schema: type: object properties: alerts: type: array items: $ref: "#/components/schemas/Alert" hasMore: type: boolean description: Whether there are more alerts to fetch totals: type: object properties: info: type: integer format: uint64 description: The number of info alerts warning: type: integer format: uint64 description: The number of warning alerts error: type: integer format: uint64 description: The number of error alerts critical: type: integer format: uint64 description: The number of critical alerts "400": description: Malformed request content: text/plain: schema: type: string examples: invalidLimit: summary: Invalid limit example value: "limit must be greater than or equal to -1" invalidOffset: summary: Invalid offset example value: "offset must be greater than or equal to 0" "500": description: Internal server error /bus/alerts/dismiss: post: tags: - bus summary: Dismiss alerts description: Dismisses the alerts that correspond to the IDs in the request body. requestBody: content: application/json: schema: type: array items: $ref: "#/components/schemas/Hash256" responses: "200": description: Successfully dismissed alerts "500": description: Internal server error /bus/alerts/register: post: tags: - bus summary: Register an alert description: Registers a new alert. requestBody: content: application/json: schema: type: object properties: severity: $ref: "#/components/schemas/Alert" responses: "200": description: Successfully registered alert "500": description: Internal server error /bus/autopilot: get: tags: - bus summary: Get autopilot configuration description: Returns the current autopilot configuration. responses: "200": description: Successfully retrieved autopilot configuration content: application/json: schema: $ref: "#/components/schemas/AutopilotConfig" "500": description: Internal server error put: tags: - bus summary: Update autopilot configuration description: Updates the autopilot configuration. requestBody: content: application/json: schema: type: object properties: enabled: type: boolean description: Whether the autopilot is enabled contracts: $ref: "#/components/schemas/ContractsConfig" hosts: $ref: "#/components/schemas/HostsConfig" responses: "200": description: Successfully updated autopilot configuration "400": description: Malformed request "500": description: Internal server error /bus/buckets: get: tags: - bus summary: Get all buckets description: Returns all known buckets. Every object is attached to a bucket and every bucket can have its own set of access policies. responses: "200": description: Successfully retrieved buckets content: application/json: schema: type: array items: $ref: "#/components/schemas/Bucket" "500": description: Internal server error post: tags: - bus summary: Create bucket description: Create a new bucket. requestBody: content: application/json: schema: type: object properties: name: $ref: "#/components/schemas/BucketName" policy: $ref: "#/components/schemas/BucketPolicy" responses: "200": description: Successfully saved buckets "400": description: Malformed request content: text/plain: schema: type: string examples: invalidBucketName: summary: Invalid bucket name example value: "bucket name must match pattern '^(?!(^xn--|.+-s3alias$))^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$'" bucketAlreadyExists: summary: Bucket already exists example value: "bucket already exists" "500": description: Internal server error /bus/bucket/{name}/policy: put: tags: - bus summary: Update bucket policy description: Updates the policy of the specified bucket. The policy can be used to configure public read access to the bucket. parameters: - name: name in: path required: true schema: $ref: "#/components/schemas/BucketName" description: The name of the bucket requestBody: content: application/json: schema: type: object properties: policy: type: object properties: publicReadAccess: type: boolean description: Whether the bucket is publicly readable responses: "200": description: Successfully updated bucket policy "400": description: Malformed request content: text/plain: schema: type: string examples: noBucketName: summary: No bucket name provided value: "bucket name is required" "404": description: Bucket not found /bus/bucket/{name}: get: tags: - bus summary: Get bucket description: Returns metadata about the specified bucket. parameters: - name: name in: path required: true schema: $ref: "#/components/schemas/BucketName" description: The name of the bucket responses: "200": description: Successfully retrieved bucket content: application/json: schema: $ref: "#/components/schemas/BucketName" "404": description: Bucket not found delete: tags: - bus summary: Delete bucket description: Deletes the specified bucket. A bucket can only be deleted if it is empty. parameters: - name: name in: path required: true schema: $ref: "#/components/schemas/BucketName" description: The name of the bucket responses: "200": description: Successfully deleted bucket "400": description: Malformed request content: text/plain: schema: type: string examples: noBucketName: summary: No bucket name provided value: "bucket name is required" "404": description: Bucket not found "409": description: Bucket not empty "500": description: Internal server error /bus/consensus/acceptblock: post: tags: - bus summary: Accept block description: Adds the block to the chain manager and broadcasts the block header. requestBody: content: application/json: schema: $ref: "#/components/schemas/Block" responses: "200": description: Successfully accepted block "500": description: Internal server error /bus/consensus/network: get: tags: - bus summary: Get network details description: Returns various details about the network. responses: "200": description: Successfully retrieved network content: application/json: schema: $ref: "#/components/schemas/Network" /bus/consensus/siafundfee/{payout}: get: tags: - bus summary: Get siafund fee description: Returns the siafund fee for a contract with the specified payout. parameters: - name: payout in: path required: true description: The payout to calculate the fee for schema: $ref: "#/components/schemas/Currency" responses: "200": description: Successfully retrieved siafund fee content: application/json: schema: $ref: "#/components/schemas/Currency" "500": description: Internal server error /bus/consensus/state: get: tags: - bus summary: Get consensus state description: Returns the current block height and the time at which the last block got mined, along with a boolean indicating whether the node is synced. A node is considered synced if the last block time is less than three hours ago. responses: "200": description: Successfully retrieved consensus state content: application/json: schema: $ref: "#/components/schemas/ConsensusState" "500": description: Internal server error /bus/contracts: get: tags: - bus summary: Get all contracts description: Returns the metadata of the contracts that match the provided filter mode. parameters: - name: filtermode in: query schema: type: string enum: [active, archived, all, good] default: active responses: "200": description: List of contracts content: application/json: schema: type: array items: $ref: "#/components/schemas/ContractMetadata" "400": description: Malformed request content: text/plain: schema: type: string examples: invalidFilterMode: summary: Invalid filter mode example value: "invalid filter mode 'bad', must be one of [active, archived, all, good]" "500": description: Internal server error put: tags: - bus summary: Update a contract description: Updates the specified contract with the provided metadata, if the contract does not exist it is added. requestBody: content: application/json: schema: $ref: "#/components/schemas/ContractMetadata" responses: "200": description: Successfully updated contract "500": description: Internal server error /bus/contracts/all: delete: tags: - bus summary: Archives all contracts description: Archives all contracts. Archiving a contract means that all the data that was stored in that contract has to be migrated. responses: "200": description: All contracts where archived successfully "500": description: Internal server error /bus/contracts/archive: post: tags: - bus summary: Archive contracts description: Archives the contracts with the specified reasons. Archiving a contract means that all the data that was stored in that contract has to be migrated. requestBody: description: > A mapping of file contract IDs (keys) to archive reasons (values). Keys must match the pattern `^fcid:[0-9a-fA-F]{64}$`. content: application/json: schema: type: object additionalProperties: type: string description: The reason for archiving the contract responses: "200": description: Contracts archived successfully "500": description: Internal server error /bus/contracts/form: post: tags: - bus summary: Form a new contract description: Forms a new contract with the provided metadata. This endpoint is usually called by the autopilot but also allows to form contracts manually. requestBody: content: application/json: schema: type: object description: The request body for the POST /contracts endpoint. properties: endHeight: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The block height at which the contract will end. hostCollateral: allOf: - $ref: "#/components/schemas/Currency" - description: The amount of collateral the host is committing. hostKey: allOf: - $ref: "#/components/schemas/PublicKey" - description: The public key of the host. renterFunds: allOf: - $ref: "#/components/schemas/Currency" - description: The funds the renter is committing. renterAddress: allOf: - $ref: "#/components/schemas/Address" - description: The renter's address responses: "200": description: Contract formed successfully content: application/json: schema: $ref: "#/components/schemas/ContractMetadata" "400": description: Invalid request parameters content: text/plain: schema: type: string examples: invalidEndHeight: summary: No end height provided value: "EndHeight can not be zero" invalidHostKey: summary: No host key provided value: "HostKey must be provided" invalidHostCollateral: summary: No host collateral provided value: "HostCollateral can not be zero" invalidRenterFunds: summary: No renter funds provided value: "RenterFunds can not be zero" invalidRenterAddress: summary: No renter address provided value: "RenterAddress must be provided" "404": description: Host not found "500": description: Internal server error /bus/contracts/prunable: get: tags: - bus summary: Get prunable contract data description: Returns a list of all contracts that indicates how many bytes can be pruned from each contract. If objects are removed, they are removed from the database first and foremost. It is only when the contracts are pruned that hosts are no longer obligated to store the sectors, which effectively removes the data from the network. responses: "200": description: Prunable contract data content: application/json: schema: type: object description: The response containing prunable contract data and summary statistics. properties: contracts: type: array description: A list of prunable contracts with their size information. items: $ref: "#/components/schemas/ContractSize" totalPrunable: type: integer format: uint64 description: The total prunable size across all contracts in bytes totalSize: type: integer format: uint64 description: The total size of all contracts in bytes /bus/contracts/renewed/{id}: get: tags: - bus summary: Get renewed contract description: Returns the metadata of contract that was renewed from the contract with given contract ID. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/FileContractID" responses: "200": description: Renewed contract metadata content: application/json: schema: $ref: "#/components/schemas/ContractMetadata" "500": description: Internal server error /bus/contracts/spending: post: tags: - bus summary: Record contract spending description: Records the spending of a contract. This is used to keep track of how much was spent on sector deletions, funding ephemeral accounts, listing sector roots, and storing sectors. requestBody: content: application/json: schema: type: array items: type: object properties: deletions: allOf: - $ref: "#/components/schemas/Currency" - description: Total amount spent on sector deletions fundAccount: allOf: - $ref: "#/components/schemas/Currency" - description: Total amount spent on funding ephemeral accounts sectorRoots: allOf: - $ref: "#/components/schemas/Currency" - description: Total amount spent on listing sector roots uploads: allOf: - $ref: "#/components/schemas/Currency" - description: Total amount spent on storing sectors contractID: $ref: "#/components/schemas/FileContractID" revisionNumber: $ref: "#/components/schemas/RevisionNumber" size: type: integer format: uint64 description: The size of the contract in bytes missedHostPayout: allOf: - $ref: "#/components/schemas/Currency" - description: The amount of siacoins that the host will receive if the contract resolves missed validRenterPayout: allOf: - $ref: "#/components/schemas/Currency" - description: The amount of siacoins that the renter will receive if the contract resolves valid. responses: "200": description: Spending recorded successfully "500": description: Internal server error /bus/contract/{id}: get: tags: - bus summary: Get contract by ID description: Returns the metadata of the contract with the specified ID. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/FileContractID" responses: "200": description: Contract metadata content: application/json: schema: $ref: "#/components/schemas/ContractMetadata" "500": description: Internal server error delete: tags: - bus summary: Archive contract with archival reason 'removed'. Archiving a contract means that all the data that was stored in that contract has to be migrated. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/FileContractID" responses: "200": description: Contract archived successfully "500": description: Internal server error /bus/contract/{id}/acquire: post: tags: - bus summary: Acquire contract lock. This lock is used to prevent multiple operations on the same contract from happening at the same time. Usually any operation that requires an update to the contract's revision needs to acquire the lock. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/FileContractID" requestBody: content: application/json: schema: type: object properties: duration: allOf: - $ref: "#/components/schemas/DurationMS" - description: The duration of the lock in milliseconds priority: $ref: "#/components/schemas/Priority" responses: "200": description: Contract lock acquired content: application/json: schema: $ref: "#/components/schemas/ContractLockID" /bus/contract/{id}/ancestors: get: tags: - bus summary: Get contract ancestors. A contract's ancestors are the contracts that were formed before it. If a contract is renewed, the existing contract is considered an ancestor of the new contract. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/FileContractID" - name: minstartheight in: query required: true schema: type: integer format: uint64 responses: "200": description: Contract ancestors content: application/json: schema: type: array items: $ref: "#/components/schemas/ContractMetadata" "500": description: Internal server error /bus/contract/{id}/broadcast: post: tags: - bus summary: Broadcast contract's revision description: Broadcasting a contract's revision is the process of creating a signed transaction that includes the contract's revision and broadcasting that transaction to the network for it to be taken up in a block. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/FileContractID" responses: "200": description: Contract's revision broadcasted successfully "500": description: Internal server error /bus/contract/{id}/keepalive: post: tags: - bus summary: Keep contract lock alive description: When a contract lock gets acquired, a certain timeout is applied. This lock can be kept alive by sending a keepalive request. If the lock is not kept alive, it will be released automatically after the timeout. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/FileContractID" requestBody: content: application/json: schema: type: object properties: duration: allOf: - $ref: "#/components/schemas/DurationMS" - description: The amount of miliseconds to extend the lock by lockID: $ref: "#/components/schemas/ContractLockID" responses: "200": description: Contract lock keepalive successful "500": description: Internal server error /bus/contract/{id}/revision: get: tags: - bus summary: Get latest contract revision description: Returns the latest revision of the contract with the specified ID. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/FileContractID" responses: "200": description: Latest contract revision content: application/json: schema: $ref: "#/components/schemas/Revision" "404": description: Contract not found "500": description: Internal server error /bus/contract/{id}/prune: post: tags: - bus summary: Prune contract data description: Pruning a contract means that we compare the contract's sectors on the host with the contract's sectors in the database. Every sector in the contract that is not accounted for in our database will be pruned and thus deleted from the contract on the host side. This effectively removes the data from the network. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/FileContractID" requestBody: content: application/json: schema: type: object properties: timeout: $ref: "#/components/schemas/DurationMS" responses: "200": description: Contract pruned successfully content: application/json: schema: type: object properties: size: type: integer format: uint64 description: The size of the pruned contract in bytes pruned: type: integer format: uint64 description: The number of bytes pruned remaining: type: integer format: uint64 description: The number of prunable bytes remaining error: type: string description: An error message if the prune failed "500": description: Internal server error /bus/contract/{id}/renew: post: tags: - bus summary: Renew contract description: If a contract is nearing its end height, or if it is running out of funds, it can be renewed, or refreshed, respecitively. If a contract is not renewed in due time, it will be archived and the data will need to be migrated to a different host. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/FileContractID" requestBody: content: application/json: schema: type: object properties: endHeight: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The height at which the contract will expire expectedNewStorage: type: integer format: uint64 minNewCollateral: $ref: "#/components/schemas/Currency" renterFunds: $ref: "#/components/schemas/Currency" responses: "200": description: Contract renewed successfully content: application/json: schema: $ref: "#/components/schemas/ContractMetadata" /bus/contract/{id}/release: post: tags: - bus summary: Release contract lock parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/FileContractID" requestBody: content: application/json: schema: type: object properties: lockID: $ref: "#/components/schemas/ContractLockID" responses: "200": description: Contract lock released successfully "500": description: Internal server error /bus/contract/{id}/roots: get: tags: - bus summary: Get contract sector roots description: Returns the sector roots of the contract from the database. These are not necessarily the same as the sector roots from the contract on the host. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/FileContractID" responses: "200": description: Contract sector roots content: application/json: schema: type: array items: $ref: "#/components/schemas/Hash256" /bus/contract/{id}/size: get: tags: - bus summary: Get contract size description: Returns the size of the contract as reported by the file contract revision, as well as the amount of data that can be removed from the contract through pruning. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/FileContractID" responses: "200": description: Contract size information content: application/json: schema: $ref: "#/components/schemas/ContractSize" "400": description: Contract not found "500": description: Internal server error /bus/contract/{id}/usability: put: tags: - bus summary: Update contract usability description: Updates the usability of the contract with the provided ID. A contract can be marked as either 'good' or 'bad'. If a contract is considered bad, all of the data in that contract needs to be migrated to 'good' contracts to ensure all of the data remains healthy and the files continue to be accessible. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/FileContractID" requestBody: content: application/json: schema: type: string enum: [good, bad] responses: "200": description: Contract usability updated successfully "400": description: Malformed request "404": description: Contract not found "500": description: Internal server error /bus/hosts: get: tags: - bus summary: Get usable hosts description: Returns the metadata of all hosts that are deemed usable. A host is usable if it passed the gouging checks, which are a series of checks performed on the host's prices to ensure they are within reason. responses: "200": description: List of usable hosts content: application/json: schema: type: array items: $ref: '#/components/schemas/HostInfo' "500": description: Internal server error post: tags: - bus summary: Search hosts using filters description: Returns a filtered list of hosts based on specified criteria requestBody: content: application/json: schema: type: object properties: usabilityMode: type: string enum: - usable - unusable - all filterMode: type: string enum: - allowed - blocked - all offset: type: integer minimum: 0 default: 0 description: The number of hosts to skip limit: type: integer minimum: -1 default: -1 description: The maximum number of hosts to return addressContains: type: string description: The host's net address to search for keyIn: type: array items: $ref: '#/components/schemas/PublicKey' maxLastScan: type: string format: date-time responses: "200": description: List of filtered hosts content: application/json: schema: type: array items: $ref: '#/components/schemas/Host' "500": description: Internal server error /bus/hosts/allowlist: get: tags: - bus summary: Get host allowlist description: Returns the list of allowed host public keys. If the allowlist is empty, all hosts are allowed. If the allowlist is not empty, only hosts with public keys that are in the allowlist are allowed and used to form contracts with. responses: "200": description: List of allowed host public keys content: application/json: schema: type: array items: $ref: '#/components/schemas/PublicKey' "500": description: Internal server error put: tags: - bus summary: Update host allowlist description: Updates the list of allowed host public keys requestBody: content: application/json: schema: type: object properties: add: type: array items: $ref: '#/components/schemas/PublicKey' remove: type: array items: $ref: '#/components/schemas/PublicKey' clear: type: boolean responses: "200": description: Allowlist updated successfully "400": description: Malformed request "500": description: Internal server error /bus/hosts/blocklist: get: tags: - bus summary: Get host blocklist description: Returns the list of blocked host net addresses. If a host is blocked, it will not be used to form contracts with responses: "200": description: List of blocked host net addresses content: application/json: schema: type: array items: type: string format: ipv4 "500": description: Internal server error put: tags: - bus summary: Update host blocklist description: Updates the list of blocked host public keys requestBody: content: application/json: schema: type: object properties: add: type: array items: type: string remove: type: array items: type: string clear: type: boolean responses: "200": description: Blocklist updated successfully "400": description: Malformed request "500": description: Internal server error /bus/hosts/remove: post: tags: - bus summary: Remove offline hosts description: Removes hosts that have been offline for the specified duration or have had too many consecutive scan failures requestBody: content: application/json: schema: type: object properties: maxDowntimeHours: type: integer maxConsecutiveScanFailures: type: integer responses: "200": description: Number of hosts removed content: application/json: schema: type: integer format: uint64 "400": description: Malformed request content: text/plain: schema: type: string examples: invalidMaxDowntime: summary: Invalid max downtime value: "maxDowntime must be non-zero" "500": description: Internal server error /bus/host/{hostkey}: get: tags: - bus summary: Get host details description: Returns detailed information about a specific host parameters: - name: hostkey in: path description: Public key of the host schema: $ref: '#/components/schemas/PublicKey' required: true responses: "200": description: Host details content: application/json: schema: $ref: '#/components/schemas/HostInfo' "404": description: Host not found "500": description: Internal server error /bus/host/{hostkey}/check: put: tags: - bus summary: Update host check description: Updates host checks for a specific host. Host checks include gouging checks, but also other checks that score the host in relation to other hosts parameters: - name: hostkey in: path description: Public key of the host schema: $ref: '#/components/schemas/PublicKey' required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/HostChecks' responses: "200": description: Host check updated successfully "400": description: Malformed request "500": description: Internal server error /bus/host/{hostkey}/resetlostsectors: post: tags: - bus summary: Reset lost sectors description: Resets the lost sectors counter for a specific host. The lost sector count is incremented if a host is unable to provide a sector that the renter thought was stored on the host. parameters: - name: hostkey in: path description: Public key of the host schema: $ref: '#/components/schemas/PublicKey' required: true responses: "200": description: Lost sectors reset successfully "500": description: Internal server error /bus/host/{hostkey}/scan: post: tags: - bus summary: Scan host description: Performs a scan of the host to check its settings and availability parameters: - name: hostkey in: path description: Public key of the host schema: $ref: '#/components/schemas/PublicKey' required: true requestBody: content: application/json: schema: type: object properties: timeout: allOf: - $ref: '#/components/schemas/DurationMS' - description: Scan timeout in milliseconds responses: "200": description: Host scan results content: application/json: schema: type: object properties: ping: allOf: - $ref: '#/components/schemas/DurationMS' - description: Round trip time in milliseconds scanError: type: string settings: $ref: '#/components/schemas/HostSettings' priceTable: $ref: '#/components/schemas/HostPriceTable' v2Settings: $ref: '#/components/schemas/HostV2Settings' "500": description: Internal server error "503": description: Not connected to peers /bus/metric/{key}: get: tags: - bus summary: Get metrics description: Returns the metrics for the specified key parameters: - name: key in: path required: true schema: type: string enum: [contract, contractprune, performance, wallet] description: The type of metric to fetch - name: start in: query required: true schema: type: string format: date-time description: Start time for the metrics query - name: n in: query required: true schema: type: integer minimum: 1 description: Number of intervals to fetch - name: interval in: query required: true schema: allOf: - $ref: '#/components/schemas/DurationMS' - description: Interval duration in milliseconds - name: contractid in: query schema: $ref: "#/components/schemas/FileContractID" - name: hostkey in: query schema: $ref: "#/components/schemas/PublicKey" - name: hostversion in: query schema: type: string responses: "200": description: Successfully retrieved metrics content: application/json: schema: type: array items: oneOf: - $ref: "#/components/schemas/ContractMetric" - $ref: "#/components/schemas/ContractPruneMetric" - $ref: "#/components/schemas/WalletMetric" "400": description: Invalid parameters content: text/plain: schema: type: string examples: invalidN: summary: Invalid 'n' value value: "'n' has to be greater than zero" requiredInterval: summary: Missing value for parameter 'interval' value: "parameter 'interval' is required" requiredN: summary: Missing value for parameter 'n' value: "parameter 'n' is required" requiredStart: summary: Missing value for parameter 'start' value: "parameter 'start' is required" unknownMetric: summary: Unknown metric key value: "unknown metric key, must be one of [contract, contractprune, performance, wallet]" "500": description: Internal server error put: tags: - bus summary: Record metrics parameters: - name: key in: path required: true schema: type: string enum: [contract, contractprune, performance, wallet] description: The type of metric to record requestBody: content: application/json: schema: type: object properties: metrics: type: array items: $ref: "#/components/schemas/ContractPruneMetric" responses: "200": description: Successfully recorded metrics "400": description: Invalid metric key or request body content: text/plain: schema: type: string examples: invalidKey:unknownMetric: summary: Unknown metric key value: "unknown metric key, must be one of [contract, contractprune, performance, wallet]" "500": description: Internal server error delete: tags: - bus summary: Delete metrics parameters: - name: key in: path required: true schema: type: string enum: [contract, contractprune, performance, wallet] description: The type of metric to delete - name: cutoff in: query required: true schema: type: string format: date-time description: Delete metrics older than this timestamp responses: "200": description: Successfully deleted metrics "400": description: Invalid parameters content: text/plain: schema: type: string examples: requiredCutoff: summary: Missing value for parameter 'cutoff' value: "parameter 'cutoff' is required" requiredMetric: summary: Missing value for parameter 'key' value: "parameter 'key' is required" unknownMetric: summary: Unknown metric key value: "unknown metric key, must be one of [contract, contractprune, performance, wallet]" "500": description: Internal server error /bus/multipart/create: post: tags: - bus summary: Create a multipart upload description: Creates a new multipart upload and returns an upload ID. requestBody: content: application/json: schema: type: object properties: bucket: $ref: "#/components/schemas/BucketName" key: allOf: - $ref: "#/components/schemas/ObjectKey" - description: The key of the object to upload mimeType: $ref: "#/components/schemas/MimeType" metadata: $ref: "#/components/schemas/ObjectUserMetadata" disableClientSideEncryption: type: boolean description: Whether to disable client-side encryption default: false responses: "200": description: Successfully created multipart upload content: application/json: schema: type: object properties: uploadID: allOf: - $ref: "#/components/schemas/UploadID" - description: The ID of the multipart upload "500": description: Internal server error /bus/multipart/abort: post: tags: - bus summary: Abort a multipart upload description: Aborts an ongoing multipart upload and removes any uploaded parts. requestBody: content: application/json: schema: type: object properties: bucket: $ref: "#/components/schemas/BucketName" key: $ref: "#/components/schemas/ObjectKey" uploadID: $ref: "#/components/schemas/MultipartUploadID" responses: "200": description: Successfully aborted multipart upload "404": description: Upload not found "500": description: Internal server error /bus/multipart/complete: post: tags: - bus summary: Complete a multipart upload description: Completes a multipart upload by combining all uploaded parts into a single object. requestBody: content: application/json: schema: type: object properties: bucket: $ref: "#/components/schemas/BucketName" key: $ref: "#/components/schemas/ObjectKey" uploadID: allOf: - $ref: "#/components/schemas/UploadID" - description: The ID of the multipart upload parts: type: array items: $ref: "#/components/schemas/MultipartCompletedPart" metadata: $ref: "#/components/schemas/ObjectUserMetadata" responses: "200": description: Successfully completed multipart upload content: application/json: schema: type: object properties: eTag: type: string description: The ETag of the completed object "500": description: Internal server error /bus/multipart/part: put: tags: - bus summary: Upload a part of a multipart upload description: Adds a part to an ongoing multipart upload. requestBody: content: application/json: schema: type: object properties: bucket: $ref: "#/components/schemas/BucketName" eTag: $ref: "#/components/schemas/ETag" key: $ref: "#/components/schemas/ObjectKey" uploadID: $ref: "#/components/schemas/UploadID" partNumber: $ref: "#/components/schemas/MultipartPartNumber" slices: type: array items: $ref: "#/components/schemas/SlabSlice" responses: "200": description: Successfully uploaded part "400": description: Invalid request parameters content: text/plain: schema: type: string example: invalidPartNumber: summary: Invalid part number value: "partNumber must be between 1 and 10000" requiredEtag: summary: Required ETag value: "eTag must be non-empty" requiredUploadID: summary: Required upload ID value: "uploadID must be non-empty" "500": description: Internal server error /bus/multipart/upload/{id}: get: tags: - bus summary: Get multipart upload details description: Returns details about an ongoing multipart upload. parameters: - name: id in: path required: true schema: type: string description: The ID of the multipart upload responses: "200": description: Successfully retrieved multipart upload details content: application/json: schema: type: object properties: bucket: $ref: "#/components/schemas/BucketName" encryptionKey: allOf: - $ref: "#/components/schemas/EncryptionKey" - description: The encryption key used for this upload key: type: string description: The key of the object uploadID: allOf: - $ref: "#/components/schemas/UploadID" - description: The ID of the multipart upload createdAt: type: string format: date-time description: When the upload was created "500": description: Internal server error /bus/multipart/listuploads: post: tags: - bus summary: List multipart uploads description: Lists all ongoing multipart uploads. requestBody: content: application/json: schema: type: object properties: bucket: $ref: "#/components/schemas/BucketName" prefix: type: string description: Filter uploads by key prefix keyMarker: type: string description: Key to start listing from uploadIDMarker: allOf: - $ref: "#/components/schemas/UploadID" - description: Upload ID to start listing from limit: type: integer description: Maximum number of uploads to return responses: "200": description: Successfully listed multipart uploads content: application/json: schema: type: object properties: hasMore: type: boolean description: Whether there are more uploads to fetch nextMarker: type: string description: The key marker for the next page of results nextUploadIDMarker: allOf: - $ref: "#/components/schemas/UploadID" - description: The upload ID marker for the next page of results uploads: type: array items: type: object properties: bucket: type: string description: The name of the bucket encryptionKey: type: string description: The encryption key used for this upload key: type: string description: The key of the object uploadID: allOf: - $ref: "#/components/schemas/UploadID" - description: The ID of the multipart upload createdAt: type: string format: date-time description: When the upload was created /bus/multipart/listparts: post: tags: - bus summary: List parts of a multipart upload description: Lists all parts that have been uploaded for a specific multipart upload. requestBody: content: application/json: schema: type: object properties: bucket: $ref: "#/components/schemas/BucketName" key: $ref: "#/components/schemas/ObjectKey" uploadID: allOf: - $ref: "#/components/schemas/UploadID" - description: The ID of the multipart upload partNumberMarker: type: integer description: Part number to start listing from limit: type: integer format: int64 description: Maximum number of parts to return responses: "200": description: Successfully listed multipart upload parts content: application/json: schema: type: object properties: hasMore: type: boolean description: Whether there are more parts to fetch nextMarker: type: integer description: The part number marker for the next page of results parts: type: array items: $ref: "#/components/schemas/MultipartListPartItem" "500": description: Internal server error /bus/objects/{prefix}: get: tags: - bus summary: List objects description: Lists objects with the specified prefix. parameters: - name: prefix in: path required: true schema: type: string example: "folder/" pattern: ".*" # greedy match description: The prefix to filter objects by - name: bucket in: query required: true schema: $ref: "#/components/schemas/BucketName" - name: delimiter in: query schema: type: string description: Path delimiter ("/" or empty) - name: limit in: query schema: type: integer default: -1 description: Maximum number of objects to return - name: marker in: query schema: type: string description: Key to start listing from - name: sortby in: query schema: type: string description: Field to sort results by - name: sortdir in: query schema: type: string description: Sort direction (asc/desc) - name: substring in: query schema: type: string description: Filter objects by substring - name: slabencryptionkey in: query schema: allOf: - $ref: "#/components/schemas/EncryptionKey" - description: Encryption key for slabs responses: "200": description: Successfully listed objects content: application/json: schema: type: object properties: objects: type: array items: $ref: "#/components/schemas/Object" hasMore: type: boolean description: Whether there are more objects to fetch "400": description: Malformed request content: text/plain: schema: type: string examples: unsupportedDelimiter: summary: Unsupported delimiter value: "delimiter must be '/' or empty" "500": description: Internal server error /bus/objects/copy: post: tags: - bus summary: Copy object description: Copies an object from one location to another. requestBody: content: application/json: schema: type: object properties: sourceBucket: $ref: "#/components/schemas/BucketName" destinationBucket: $ref: "#/components/schemas/BucketName" sourceKey: type: string description: The key of the source object destinationKey: type: string description: The key for the destination object mimeType: type: string description: The MIME type for the copied object metadata: $ref: "#/components/schemas/ObjectUserMetadata" responses: "200": description: Successfully copied object headers: Last-Modified: schema: type: string ETag: schema: type: string content: application/json: schema: $ref: "#/components/schemas/ObjectMetadata" "500": description: Internal server error /bus/objects/remove: post: tags: - bus summary: Remove objects by prefix description: Removes all objects with the specified prefix. requestBody: content: application/json: schema: type: object properties: bucket: $ref: "#/components/schemas/BucketName" prefix: type: string description: The prefix of objects to remove minLength: 1 responses: "200": description: Successfully removed objects "400": description: Malformed request content: text/plain: schema: type: string examples: requiredBucket: summary: Missing value for parameter 'bucket' value: "parameter 'bucket' is required" requiredPrefix: summary: Missing value for parameter 'prefix' value: "prefix cannot be empty" "500": description: Internal server error /bus/objects/rename: post: tags: - bus summary: Rename objects description: Renames a single object or multiple objects with a prefix. requestBody: content: application/json: schema: type: object properties: bucket: $ref: "#/components/schemas/BucketName" from: type: string description: Source path/prefix to: type: string description: Destination path/prefix mode: type: string enum: [single, multi] description: Whether to rename a single object or multiple objects force: type: boolean description: Whether to overwrite existing objects responses: "200": description: Successfully renamed objects "400": description: Malformed request content: text/plain: schema: type: string examples: requiredBucket: summary: Missing value for parameter 'bucket' value: "parameter 'bucket' is required" invalidMode: summary: Invalid mode value: "mode must be 'single' or 'multi'" "500": description: Internal server error /bus/object/{key}: get: tags: - bus summary: Get object description: Returns an object's metadata or full object data. parameters: - name: key in: path required: true schema: allOf: - $ref: "#/components/schemas/ObjectKey" - pattern: ".*" # greedy match description: The key of the object to fetch - name: bucket in: query required: true description: The name of the bucket the object is in schema: $ref: "#/components/schemas/BucketName" - name: onlymetadata in: query required: false schema: type: boolean description: If true, only returns object metadata without data responses: "200": description: Successfully retrieved object content: application/json: schema: $ref: "#/components/schemas/Object" "404": description: Object not found "500": description: Internal server error put: tags: - bus summary: Store object description: Stores or updates an object. parameters: - name: key in: path required: true schema: allOf: - $ref: "#/components/schemas/ObjectKey" - pattern: ".*" # greedy match description: The key of the object requestBody: content: application/json: schema: type: object properties: bucket: $ref: "#/components/schemas/BucketName" eTag: type: string description: The ETag of the object mimeType: type: string description: The MIME type of the object metadata: $ref: "#/components/schemas/ObjectUserMetadata" object: $ref: "#/components/schemas/Object" responses: "200": description: Successfully stored object "400": description: Malformed request "500": description: Internal server error delete: tags: - bus summary: Delete object description: Deletes an object from the bucket. parameters: - name: key in: path required: true schema: allOf: - $ref: "#/components/schemas/ObjectKey" - pattern: ".*" # greedy match description: The key of the object to delete - name: bucket in: query required: true schema: $ref: "#/components/schemas/BucketName" responses: "200": description: Successfully deleted object "404": description: Object not found "500": description: Internal server error /bus/params/gouging: get: tags: - bus summary: Get gouging parameters description: Returns the current gouging parameters including consensus state, gouging settings, and redundancy settings. responses: "200": description: Successfully retrieved gouging parameters content: application/json: schema: type: object properties: consensusState: type: object properties: blockHeight: $ref: "#/components/schemas/BlockHeight" lastBlockTime: type: string format: date-time description: Timestamp of the last block synced: type: boolean description: Whether consensus is synced gougingSettings: $ref: "#/components/schemas/GougingSettings" redundancySettings: $ref: "#/components/schemas/RedundancySettings" "500": description: Internal server error /bus/params/upload: get: tags: - bus summary: Get upload parameters description: Returns parameters needed for uploads including consensus height, gouging parameters and upload packing status. responses: "200": description: Successfully retrieved upload parameters content: application/json: schema: type: object allOf: - type: object properties: currentHeight: allOf: - $ref: "#/components/schemas/BlockHeight" - description: Current consensus height uploadPacking: type: boolean description: Whether upload packing is enabled - $ref: "#/components/schemas/GougingParams" "500": description: Internal server error /bus/sectors/{hostkey}/{root}: delete: tags: - bus summary: Delete host sector description: Marks a sector as lost for a specific host. parameters: - name: hostkey in: path required: true schema: $ref: "#/components/schemas/PublicKey" description: The host's public key - name: root in: path required: true schema: $ref: "#/components/schemas/Hash256" description: The Merkle root of the sector responses: "200": description: Successfully marked sector as lost "500": description: Internal server error /bus/settings/gouging: get: tags: - bus summary: Get gouging settings description: Returns the current gouging settings. The gouging settings are used to define boundaries for various fields that we check host prices against when trying to detect price gouging. responses: "200": description: Successfully retrieved gouging settings content: application/json: schema: $ref: "#/components/schemas/GougingSettings" "500": description: Internal server error put: tags: - bus summary: Update gouging settings description: Updates the gouging settings. requestBody: content: application/json: schema: $ref: "#/components/schemas/GougingSettings" responses: "200": description: Successfully updated gouging settings "400": description: Malformed request "500": description: Internal server error /bus/settings/pinned: get: tags: - bus summary: Get pinned settings description: Returns the current pinned settings. Pinned settings allow pinning currency settings against an underlying fiat currency to allow expressing them in a more stable currency. responses: "200": description: Successfully retrieved pinned settings content: application/json: schema: $ref: "#/components/schemas/PinnedSettings" put: tags: - bus summary: Update pinned settings description: Updates the pinned settings. requestBody: content: application/json: schema: $ref: "#/components/schemas/PinnedSettings" responses: "200": description: Successfully updated pinned settings "400": description: Invalid settings content: text/plain: schema: type: string examples: explorerDisabled: summary: Explorer disabled value: "explorer must be enabled for settings to be pinned" "500": description: Internal server error /bus/settings/s3: get: tags: - bus summary: Get S3 settings description: Returns the current S3 settings. responses: "200": description: Successfully retrieved S3 settings content: application/json: schema: $ref: "#/components/schemas/S3Settings" "500": description: Internal server error put: tags: - bus summary: Update S3 settings description: Updates the S3 settings. requestBody: content: application/json: schema: $ref: "#/components/schemas/S3Settings" responses: "200": description: Successfully updated S3 settings "400": description: Malformed request "500": description: Internal server error /bus/settings/upload: get: tags: - bus summary: Get upload settings description: Returns the current upload settings. Upload settings allow configuring various parameters for uploads, such as whether packing is enabled, or the redundancy with which data is stored on the Sia network. responses: "200": description: Successfully retrieved upload settings content: application/json: schema: $ref: "#/components/schemas/UploadSettings" "500": description: Internal server error put: tags: - bus summary: Update upload settings description: Updates the upload settings. requestBody: content: application/json: schema: $ref: "#/components/schemas/UploadSettings" responses: "200": description: Successfully updated upload settings "400": description: Malformed request "500": description: Internal server error /bus/slabbuffers: get: tags: - bus summary: Get slab buffers info description: Returns information about all slab buffers. A slab buffer is an on-disk buffer that's used when upload packing is enabled. If a buffer reaches the size of a slab it is uploaded to the network. responses: "200": description: Successfully retrieved slab buffers content: application/json: schema: type: array items: $ref: "#/components/schemas/SlabBuffer" "500": description: Internal server error /bus/slabbuffer/done: post: tags: - bus summary: Mark packed slabs as uploaded description: Marks the specified packed slabs as successfully uploaded. requestBody: content: application/json: schema: type: object properties: slabs: type: array items: $ref: "#/components/schemas/UploadedPackedSlab" responses: "200": description: Successfully marked slabs as uploaded "500": description: Internal server error /bus/slabbuffer/fetch: post: tags: - bus summary: Fetch packed slabs for upload description: Returns packed slabs that are ready to be uploaded. requestBody: content: application/json: schema: type: object properties: lockingDuration: allOf: - $ref: "#/components/schemas/DurationMS" - description: Duration in milliseconds to lock the slabs minShards: $ref: "#/components/schemas/RedundancySettingsMinShards" totalShards: $ref: "#/components/schemas/RedundancySettingsTotalShards" limit: type: integer description: Maximum number of packed slabs to return responses: "200": description: Successfully retrieved packed slabs content: application/json: schema: type: array items: $ref: "#/components/schemas/PackedSlab" "500": description: Internal server error /bus/slabs/migration: post: tags: - bus summary: Get slabs for migration description: Returns slabs that need to be migrated based on health cutoff. requestBody: content: application/json: schema: type: object properties: healthCutoff: type: number format: float64 description: The health cutoff at which slabs are returned for migration limit: type: integer description: Maximum number of slabs to return responses: "200": description: Successfully retrieved slabs for migration content: application/json: schema: type: object properties: slabs: type: array items: type: object properties: encryptionKey: $ref: "#/components/schemas/EncryptionKey" health: type: number format: float64 description: Current health of the slab "400": description: Malformed request "500": description: Internal server error /bus/slabs/partial/{key}: get: tags: - bus summary: Get partial slab description: Retrieves a portion of a slab's data. parameters: - name: key in: path required: true schema: $ref: "#/components/schemas/EncryptionKey" - name: offset in: query required: true schema: type: integer minimum: 0 description: Offset within the slab - name: length in: query required: true schema: type: integer minimum: 1 description: Number of bytes to retrieve responses: "200": description: Successfully retrieved partial slab data content: application/octet-stream: schema: type: string format: binary "400": description: Malformed request content: text/plain: schema: type: string examples: invalidLimit: summary: Invalid limit example value: "limit must be greater than or equal to -1" invalidOffset: summary: Invalid offset example value: "offset must be greater than or equal to 0" "404": description: Slab not found "500": description: Internal server error /bus/slabs/partial: post: tags: - bus summary: Add partial slab description: Adds data to a partial slab. parameters: - name: minshards in: query required: true schema: $ref: "#/components/schemas/RedundancySettingsMinShards" - name: totalshards in: query required: true schema: $ref: "#/components/schemas/RedundancySettingsTotalShards" requestBody: content: application/octet-stream: schema: type: string format: binary responses: "200": description: Successfully added partial slab content: application/json: schema: type: object properties: slabs: type: array items: $ref: "#/components/schemas/SlabSlice" slabBufferMaxSizeSoftReached: type: boolean description: Whether the slab buffer soft limit was reached "400": description: Malformed request content: text/plain: schema: type: string examples: invalidRedundancy: summary: Invalid redundancy parameters value: "minShards must be positive and totalShards must be greater than minShards" invalidTotalShards: summary: Invalid total shards value: "totalShards must be less than or equal to 255" "500": description: Internal server error /bus/slabs/refreshhealth: post: tags: - bus summary: Refresh slab health description: Recalculates health for all slabs. responses: "200": description: Successfully refreshed slab health "500": description: Internal server error /bus/slab/{key}: get: tags: - bus summary: Get slab description: Returns information about a specific slab. parameters: - name: key in: path required: true schema: $ref: "#/components/schemas/EncryptionKey" responses: "200": description: Successfully retrieved slab content: application/json: schema: $ref: "#/components/schemas/Slab" "404": description: Slab not found "500": description: Internal server error put: tags: - bus summary: Update slab description: Updates the sectors for a slab. parameters: - name: key in: path required: true schema: $ref: "#/components/schemas/EncryptionKey" requestBody: content: application/json: schema: type: array items: type: object properties: contractID: $ref: "#/components/schemas/FileContractID" root: $ref: "#/components/schemas/Hash256" responses: "200": description: Successfully updated slab "400": description: Malformed request "404": description: Slab not found "500": description: Internal server error /bus/syncer/address: get: tags: - bus summary: Get the syncer's address description: Returns the address of the syncer. responses: "200": description: Successfully retrieved syncer address content: application/json: schema: $ref: "#/components/schemas/SyncerAddress" /bus/syncer/connect: post: tags: - bus summary: Connect to a syncer description: Connects to the specified syncer. requestBody: content: application/json: schema: allOf: - $ref: "#/components/schemas/SyncerAddress" - description: The address of the syncer to connect to responses: "200": description: Successfully connected to syncer "500": description: Internal server error /bus/syncer/peers: get: tags: - bus summary: Get syncer peers description: Returns the syncer's peers. responses: "200": description: Successfully retrieved syncer peers content: application/json: schema: type: array items: $ref: "#/components/schemas/SyncerAddress" /bus/system/sqlite3/backup: post: tags: - bus summary: Backup SQLite database description: Creates a backup of the specified SQLite database. requestBody: content: application/json: schema: type: object properties: database: type: string enum: [main, metrics] description: Which database to backup path: type: string description: Path where to save the backup responses: "200": description: Successfully created backup "400": description: Invalid database specified "404": description: Backup not supported "500": description: Internal server error /bus/state: get: tags: - bus summary: Get bus state description: Returns the current state of the bus including version, build info, and explorer status. responses: "200": description: Successfully retrieved bus state content: application/json: schema: type: object properties: startTime: type: string format: date-time description: When the bus was started version: type: string description: Version of renterd commit: type: string description: Git commit hash of the build os: type: string description: Operating system buildTime: type: string format: date-time description: When this version was built explorer: type: object properties: enabled: type: boolean description: Whether the explorer is enabled url: type: string description: Base URL of the explorer network: type: string description: Name of the network (mainnet/testnet) /bus/stats/objects: get: tags: - bus summary: Get object statistics description: Returns statistics about objects in a bucket. parameters: - name: bucket in: query schema: $ref: "#/components/schemas/BucketName" description: Optional bucket to get stats for responses: "200": description: Successfully retrieved object statistics content: application/json: schema: type: object properties: numObjects: type: integer format: uint64 description: Number of objects numUnfinishedObjects: type: integer format: uint64 description: Number of unfinished objects minHealth: type: number format: float64 description: Minimum health of all objects totalObjectsSize: type: integer format: uint64 description: Size of all objects totalUnfinishedObjectsSize: type: integer format: uint64 description: Size of all unfinished objects totalSectorsSize: type: integer format: uint64 description: Uploaded size of all objects totalUploadedSize: type: integer format: uint64 description: Uploaded size of all objects including redundant sectors "500": description: Internal server error /bus/txpool/recommendedfee: get: tags: - bus summary: Get recommended fee description: Returns the recommended fee for a transaction. responses: "200": description: Successfully retrieved recommended fee content: application/json: schema: $ref: "#/components/schemas/Currency" "500": description: Internal server error /bus/txpool/transactions: get: tags: - bus summary: Get all transactions description: Returns all transactions in the transaction pool. responses: "200": description: Successfully retrieved transactions content: application/json: schema: type: array items: $ref: "#/components/schemas/Transaction" "500": description: Internal server error /bus/txpool/broadcast: post: tags: - bus summary: Broadcast transaction description: Broadcasts the specified transaction. requestBody: content: application/json: schema: $ref: "#/components/schemas/Transaction" responses: "200": description: Successfully broadcast transaction "500": description: Internal server error /bus/upload/{id}: post: tags: - bus summary: Track upload description: Starts tracking an upload with the given ID. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/UploadID" responses: "200": description: Successfully started tracking upload "500": description: Internal server error delete: tags: - bus summary: Finish upload description: Marks an upload as finished and stops tracking it. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/UploadID" responses: "200": description: Successfully finished upload "500": description: Internal server error /bus/upload/{id}/sector: post: tags: - bus summary: Add sectors to upload description: Adds sector roots to a tracked upload. parameters: - name: id in: path required: true schema: $ref: "#/components/schemas/UploadID" requestBody: content: application/json: schema: type: array items: $ref: "#/components/schemas/Hash256" responses: "200": description: Successfully added sectors "500": description: Internal server error /bus/wallet: get: tags: - bus summary: Get wallet information description: Returns information about the wallet. responses: "200": description: Successfully retrieved wallet content: application/json: schema: type: object properties: spendable: allOf: - $ref: "#/components/schemas/Currency" - description: The amount of spendable siacoins in the wallet confirmed: allOf: - $ref: "#/components/schemas/Currency" - description: The amount of siacoins that have been confirmed in a block unconfirmed: allOf: - $ref: "#/components/schemas/Currency" - description: The amount of siacoins that have not been confirmed in a block immature: allOf: - $ref: "#/components/schemas/Currency" - description: The amount of siacoins that have yet to mature address: allOf: - $ref: "#/components/schemas/Address" - description: The wallet's address scanHeight: type: integer format: uint64 description: The height up until which the wallet is synced "500": description: Internal server error /bus/wallet/events: get: tags: - bus summary: Get wallet events description: Returns all events related to the wallet. parameters: - name: limit in: query description: The maximum number of events to return schema: type: integer minimum: -1 default: -1 - name: offset in: query description: The number of events to skip schema: type: integer minimum: 0 default: 0 responses: "200": description: Successfully retrieved wallet events content: application/json: schema: type: array items: $ref: "#/components/schemas/Event" "400": description: Malformed request content: text/plain: schema: type: string examples: invalidLimit: summary: Invalid limit example value: "limit must be greater than or equal to -1" invalidOffset: summary: Invalid offset example value: "offset must be greater than or equal to 0" "500": description: Internal server error /bus/wallet/pending: get: tags: - bus summary: Get unconfirmed events description: Returns all unconfirmed events in the wallet. responses: "200": description: Successfully retrieved pending events content: application/json: schema: type: array items: $ref: "#/components/schemas/Event" "500": description: Internal server error /bus/wallet/redistribute: post: tags: - bus summary: Redistribute wallet funds description: Redistributes the wallet's funds into desired number of outputs of requested value. requestBody: content: application/json: schema: type: object properties: outputs: type: integer format: uint64 description: The number of outputs to redistribute the wallet's funds into amount: allOf: - $ref: "#/components/schemas/Currency" - description: The value of each output responses: "200": description: Successfully redistributed wallet funds content: application/json: schema: type: array items: $ref: "#/components/schemas/TransactionID" "400": description: Malformed request "500": description: Internal server error /bus/wallet/send: post: tags: - bus summary: Send siacoins description: Sends the specified amount of siacoins to the specified address. requestBody: content: application/json: schema: type: object properties: address: allOf: - $ref: "#/components/schemas/Address" - description: The address to send the siacoins to amount: allOf: - $ref: "#/components/schemas/Currency" - description: The amount of siacoins to send subtractMinerFee: type: boolean description: Whether to subtract the miner fee from the amount useUnconfirmed: type: boolean description: Whether to use unconfirmed outputs responses: "200": description: Successfully sent siacoins content: application/json: schema: allOf: - $ref: "#/components/schemas/TransactionID" - description: The ID of the transaction "400": description: Malformed request "500": description: Internal server error /bus/webhooks: get: tags: - bus summary: Get webhooks description: Returns all registered webhooks and their queue information. responses: "200": description: Successfully retrieved webhooks content: application/json: schema: type: object properties: queues: type: array items: $ref: "#/components/schemas/WebhookQueueInfo" webhooks: type: array items: $ref: "#/components/schemas/Webhook" post: tags: - bus summary: Register webhook description: Registers a new webhook. Alerts is the only system that uses webhooks. requestBody: content: application/json: schema: $ref: "#/components/schemas/Webhook" responses: "200": description: Successfully registered webhook "500": description: Internal server error /bus/webhooks/action: post: tags: - bus summary: Broadcast webhook action description: Broadcasts a webhook event to registered webhooks. requestBody: content: application/json: schema: $ref: "#/components/schemas/WebhookEvent" responses: "200": description: Successfully broadcast action "500": description: Internal server error /bus/webhook/delete: post: tags: - bus summary: Delete webhook description: Deletes a registered webhook. requestBody: content: application/json: schema: $ref: "#/components/schemas/Webhook" responses: "200": description: Successfully deleted webhook "404": description: Webhook not found "500": description: Internal server error components: schemas: ############################# # # Core types # ############################# Account: type: object properties: id: allOf: - $ref: "#/components/schemas/PublicKey" - description: The account's ID cleanShutdown: type: boolean description: Whether the account has been cleanly shutdown. If not, the account will require a sync with the host. hostKey: allOf: - $ref: "#/components/schemas/PublicKey" - description: The host's public key balance: allOf: - $ref: "#/components/schemas/Currency" - description: The account's balance as expected by the worker drift: allOf: - $ref: "#/components/schemas/SignedCurrency" - description: The accumulated drift between the worker's expected balance and the host's actual balance. Used to track if a host is trying to cheat the renter over time. owner: type: string description: The owner of the account that manages it. This is the id of the worker that maintains the account. minLength: 1 requiresSync: type: boolean description: Whether the account requires a sync with the host. This is usually the case when the host reports insufficient balance for an account that the worker still believes to be funded. Address: allOf: - $ref: "#/components/schemas/Hash256" - description: The hash of a set of UnlockConditions Alert: type: object properties: id: allOf: - $ref: "#/components/schemas/Hash256" - description: The alert's ID severity: type: string enum: - info - warning - error - critical description: The severity of the alert message: type: string description: The alert's message date: type: object description: Arbitrary data providing additional context for the alert timestamp: type: string format: date-time description: The time the alert was created Attestation: type: object properties: publicKey: $ref: "#/components/schemas/PublicKey" key: type: string value: type: string format: byte signature: $ref: "#/components/schemas/Signature" Block: type: object properties: parentID: allOf: - $ref: "#/components/schemas/BlockID" - description: The ID of the parent block nonce: type: integer format: uint64 description: The nonce used to mine the block timestamp: type: string format: date-time description: The time the block was mined minerPayouts: type: array items: $ref: "#/components/schemas/SiacoinOutput" transactions: type: array items: $ref: "#/components/schemas/Transaction" v2: $ref: "#/components/schemas/V2BlockData" BlockID: allOf: - $ref: "#/components/schemas/Hash256" - description: A unique identifier for a block ChainIndex: type: object properties: height: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The height of the block in the blockchain id: allOf: - $ref: "#/components/schemas/BlockID" - description: The ID of the block ContractMetadata: type: object properties: id: allOf: - $ref: "#/components/schemas/FileContractID" - description: The unique identifier for the file contract. hostKey: allOf: - $ref: "#/components/schemas/PublicKey" - description: The public key of the host. v2: type: boolean description: Indicates if the contract is a V2 contract. proofHeight: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The height at which the storage proof needs to be submitted renewedFrom: allOf: - $ref: "#/components/schemas/FileContractID" - description: The ID of the contract this one was renewed from revisionHeight: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The block height of the latest revision revisionNumber: allOf: - $ref: "#/components/schemas/RevisionNumber" - description: The current revision number of the contract size: type: integer format: uint64 description: The size of the contract in bytes startHeight: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The block height at which the contract created state: type: string description: The state of the contract enum: - pending - active - complete - failed usability: type: string description: The usability status of the contract enum: - good - bad windowStart: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The block height when the contract's proof window starts. windowEnd: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The block height when the contract's proof window ends. contractPrice: allOf: - $ref: "#/components/schemas/Currency" - description: The price of forming the contract. initialRenterFunds: allOf: - $ref: "#/components/schemas/Currency" - description: The initial funds provided by the renter. spending: allOf: - $ref: "#/components/schemas/ContractSpending" - description: Costs and spending details of the contract. archivalReason: type: string description: The reason for archiving the contract, if applicable. enum: - renewed - removed - hostpruned renewedTo: allOf: - $ref: "#/components/schemas/FileContractID" - description: The ID of the contract this one was renewed to, if applicable. ContractSpending: type: object properties: deletions: allOf: - $ref: "#/components/schemas/Currency" - description: Total amount spent on sector deletions fundAccount: allOf: - $ref: "#/components/schemas/Currency" - description: Total amount spent on funding ephemeral accounts sectorRoots: allOf: - $ref: "#/components/schemas/Currency" - description: Total amount spent on listing sector roots uploads: allOf: - $ref: "#/components/schemas/Currency" - description: Total amount spent on storing sectors CoveredFields: type: object properties: wholeTransaction: type: boolean description: Whether the whole transaction is covered by the signature siacoinInputs: type: array items: type: integer format: uint64 siacoinOutputs: type: array items: type: integer format: uint64 fileContracts: type: array items: type: integer format: uint64 fileContractRevisions: type: array items: type: integer format: uint64 storageProofs: type: array items: type: integer format: uint64 siafundInputs: type: array items: type: integer format: uint64 siafundOutputs: type: array items: type: integer format: uint64 minerFees: type: array items: type: integer format: uint64 arbitraryData: type: array items: type: integer format: uint64 signatures: type: array items: type: integer format: uint64 Currency: type: string pattern: "^\\d+$" maxLength: 39 # fits 2^128 - 1 description: An unsigned amount of Hastings, the smallest unit of currency in Sia. 1 Siacoin (SC) equals 10^24 Hastings (H). FileContract: type: object description: A storage agreement between a renter and a host. properties: filesize: type: integer format: uint64 description: The size of the contract in bytes. fileMerkleRoot: allOf: - $ref: "#/components/schemas/Hash256" - description: The Merkle root of the contract's data. windowStart: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The block height when the contract's proof window starts. windowEnd: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The block height when the contract's proof window ends. payout: allOf: - $ref: "#/components/schemas/Currency" - description: The total payout for the contract. validProofOutputs: type: array description: List of outputs created if the contract is successfully fulfilled. items: $ref: "#/components/schemas/SiacoinOutput" missedProofOutputs: type: array description: List of outputs created if the contract is not fulfilled. items: $ref: "#/components/schemas/SiacoinOutput" unlockHash: $ref: "#/components/schemas/Address" revisionNumber: $ref: "#/components/schemas/RevisionNumber" FileContractID: type: string pattern: "^fcid:[0-9a-fA-F]{64}$" description: A unique identifier for a file contract FileContractRevision: type: object description: Represents a revision to an existing file contract. properties: parentID: allOf: - $ref: "#/components/schemas/FileContractID" - description: The ID of the parent file contract being revised. unlockConditions: allOf: - $ref: "#/components/schemas/UnlockConditions" - description: The conditions required to unlock the contract for revision. filesize: type: integer format: uint64 description: The size of the file in bytes after the revision. fileMerkleRoot: allOf: - $ref: "#/components/schemas/Hash256" - description: The updated Merkle root of the file's data. windowStart: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The block height when the revised proof window starts. windowEnd: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The block height when the revised proof window ends. validProofOutputs: type: array description: Updated outputs if the revised contract is successfully fulfilled. items: $ref: "#/components/schemas/SiacoinOutput" missedProofOutputs: type: array description: Updated outputs if the revised contract is not fulfilled. items: $ref: "#/components/schemas/SiacoinOutput" unlockHash: allOf: - $ref: "#/components/schemas/Address" - description: The updated hash of the conditions required to unlock the contract funds. revisionNumber: $ref: "#/components/schemas/RevisionNumber" Hash256: type: string pattern: ^[0-9a-fA-F]{64}$ description: A 256-bit blake2b hash HostPrices: type: object properties: contractPrice: allOf: - $ref: "#/components/schemas/Currency" - description: Cost to the renter for forming, renewing, or refreshing a contract. Paid up front and covers the cost of the revision and storage proof transaction the host broadcasts at the end of the contract. collateral: allOf: - $ref: "#/components/schemas/Currency" - description: The amount of Hastings the host will risk per byte of storage per block. storagePrice: allOf: - $ref: "#/components/schemas/Currency" - description: Cost per byte of storage per block. ingressPrice: allOf: - $ref: "#/components/schemas/Currency" - description: Cost per byte of data uploaded from the host egressPrice: allOf: - $ref: "#/components/schemas/Currency" - description: Cost per byte of data downloaded from the host tipHeight: type: integer format: uint64 description: The height at which the prices were last updated validUntil: type: string format: date-time description: The time at which these prices will no longer be honored by the host. signature: $ref: "#/components/schemas/Signature" HostPriceTable: type: object description: A detailed price table containing cost and configuration values for a host. properties: uid: allOf: - $ref: "#/components/schemas/SettingsID" - description: Unique specifier that identifies this price table. validity: description: Duration (in nanoseconds) for which the host guarantees these prices are valid. type: integer format: int64 example: 3600000000000 # 1 hour in nanoseconds hostblockheight: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The host's current block height. updatepricetablecost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost to fetch a new price table from the host. accountbalancecost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost to fetch the balance of an ephemeral account. fundaccountcost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost to fund an ephemeral account on the host. latestrevisioncost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost to retrieve the latest revision of a contract. subscriptionmemorycost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost of storing a byte of data for a subscription period. subscriptionnotificationcost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost of a single notification on top of bandwidth charges. initbasecost: allOf: - $ref: '#/components/schemas/Currency' - description: The base cost incurred when starting an MDM program. memorytimecost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost per byte per time for the memory consumed by a program. downloadbandwidthcost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost per byte for download bandwidth. uploadbandwidthcost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost per byte for upload bandwidth. dropsectorsbasecost: allOf: - $ref: '#/components/schemas/Currency' - description: The base cost of performing a DropSectors instruction. dropsectorsunitcost: allOf: - $ref: '#/components/schemas/Currency' - description: The unit cost per sector for performing a DropSectors instruction. hassectorbasecost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost for executing the HasSector command. readbasecost: allOf: - $ref: '#/components/schemas/Currency' - description: The base cost of performing a Read instruction. readlengthcost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost per byte read during a Read instruction. renewcontractcost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost for renewing a contract. revisionbasecost: allOf: - $ref: '#/components/schemas/Currency' - description: The base cost for performing a Revision command. swapsectorcost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost of swapping two full sectors by root. writebasecost: allOf: - $ref: '#/components/schemas/Currency' - description: The base cost per write operation. writelengthcost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost per byte written during a Write instruction. writestorecost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost per byte/block of additional storage. txnfeeminrecommended: allOf: - $ref: '#/components/schemas/Currency' - description: The minimum recommended transaction fee. txnfeemaxrecommended: allOf: - $ref: '#/components/schemas/Currency' - description: The maximum recommended transaction fee. contractprice: allOf: - $ref: '#/components/schemas/Currency' - description: The additional fee charged by the host to form or renew a contract. collateralcost: allOf: - $ref: '#/components/schemas/Currency' - description: The cost per byte for the collateral promised by the host. maxcollateral: allOf: - $ref: '#/components/schemas/Currency' - description: The maximum amount of collateral the host is willing to put into a contract. maxduration: description: Maximum duration (in blocks) for which the host is willing to form a contract. type: integer format: uint64 example: 14400 # ~100 days at 10-minute block time. windowsize: description: Minimum time (in blocks) requested for the renew window of a contract. type: integer format: uint64 example: 1000 registryentriesleft: description: The remaining number of registry entries available on the host. type: integer format: uint64 example: 5000 registryentriestotal: description: The total number of registry entries available on the host. type: integer format: uint64 example: 10000 HostSettings: type: object properties: acceptingContracts: type: boolean description: Whether the host is accepting new contracts maxDownloadBatchSize: type: integer format: uint64 description: Maximum allowed download batch size maxDuration: type: integer format: uint64 description: Maximum allowed contract duration maxReviseBatchSize: type: integer format: uint64 description: Maximum allowed revision batch size netAddress: type: string description: Network address of the host remainingStorage: type: integer format: uint64 description: Amount of storage the host has remaining sectorSize: type: integer format: uint64 description: Size of a storage sector totalStorage: type: integer format: uint64 description: Total amount of storage space address: $ref: "#/components/schemas/Address" windowSize: type: integer format: uint64 description: Size of the proof window collateral: $ref: "#/components/schemas/Currency" maxCollateral: $ref: "#/components/schemas/Currency" baseRPCPrice: $ref: "#/components/schemas/Currency" contractPrice: $ref: "#/components/schemas/Currency" downloadBandwidthPrice: $ref: "#/components/schemas/Currency" sectorAccessPrice: $ref: "#/components/schemas/Currency" storagePrice: $ref: "#/components/schemas/Currency" uploadBandwidthPrice: $ref: "#/components/schemas/Currency" ephemeralAccountExpiry: type: integer format: int64 description: Duration before an ephemeral account expires maxEphemeralAccountBalance: $ref: "#/components/schemas/Currency" revisionNumber: $ref: "#/components/schemas/RevisionNumber" version: type: string description: Version of the host software release: type: string description: Release tag of the host software example: "hostd 1.0.0" siamuxPort: type: string description: Port used for siamux connections HostV2Settings: type: object properties: protocolVersion: $ref: "#/components/schemas/SemVer" release: type: string description: Release tag of the host software example: "hostd 1.0.0" walletAddress: $ref: "#/components/schemas/Address" acceptingContracts: type: boolean description: Whether the host is accepting new contracts maxCollateral: $ref: "#/components/schemas/Currency" maxContractDuration: type: integer format: uint64 description: Maximum allowed contract duration remainingStorage: type: integer format: uint64 description: Amount of storage the host has remaining totalStorage: type: integer format: uint64 description: Total amount of storage space prices: $ref: "#/components/schemas/HostPrices" PublicKey: type: string pattern: "^ed25519:[0-9a-fA-F]{64}$" description: A ed25519 public key SatisfiedPolicy: type: object properties: policy: type: object signature: type: array items: $ref: "#/components/schemas/Signature" preimages: type: array items: type: string format: byte SiacoinElement: type: object properties: id: allOf: - $ref: "#/components/schemas/SiacoinOutputID" - description: The ID of the element stateElement: allOf: - $ref: "#/components/schemas/StateElement" - description: The state of the element siafundOutput: allOf: - $ref: "#/components/schemas/SiacoinOutput" - description: The output of the element maturityHeight: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The block height when the output matures SiacoinInput: type: object properties: parentID: allOf: - $ref: "#/components/schemas/SiacoinOutputID" - description: The ID of the output being spent unlockConditions: allOf: - $ref: "#/components/schemas/UnlockConditions" - description: The unlock conditions required to spend the output SiacoinOutput: type: object properties: value: allOf: - $ref: "#/components/schemas/Currency" - description: The amount of Siacoins in the output address: $ref: "#/components/schemas/Address" SiacoinOutputID: allOf: - $ref: "#/components/schemas/Hash256" - description: Unique identifier for a Siacoin output. SiafundElement: type: object properties: id: allOf: - $ref: "#/components/schemas/SiafundOutputID" - description: The ID of the element stateElement: allOf: - $ref: "#/components/schemas/StateElement" - description: The state of the element siafundOutput: allOf: - $ref: "#/components/schemas/SiafundOutput" - description: The output of the element claimStart: allOf: - $ref: "#/components/schemas/Currency" - description: value of SiafundTaxRevenue when element was created SiafundInput: type: object description: Represents an input used to spend an unspent Siafund output. properties: parentID: allOf: - $ref: "#/components/schemas/SiafundOutputID" - description: The ID of the parent Siafund output being spent. unlockConditions: allOf: - $ref: "#/components/schemas/UnlockConditions" - description: The conditions required to unlock the parent Siafund output. claimAddress: allOf: - $ref: "#/components/schemas/Address" - description: The address receiving the Siacoin claim generated by the Siafund output. SiafundOutput: type: object description: Represents an output created to distribute Siafund. properties: value: type: integer format: uint64 description: The amount of Siafund in the output. address: allOf: - $ref: "#/components/schemas/Address" - description: The address receiving the Siafund. SiafundOutputID: allOf: - $ref: "#/components/schemas/Hash256" - description: Unique identifier for a Siafund output. Signature: type: string format: byte pattern: "[0-9a-fA-F]{64}" description: A ed25519 signature SignedCurrency: type: string pattern: "^-?\\d+$" maxLength: 39 # fits 2^128 - 1 description: A signed amount of Hastings, the smallest unit of currency in Sia. 1 Siacoin (SC) equals 10^24 Hastings (H). StateElement: type: object properties: leafIndex: type: integer format: uint64 description: The index of the element in the Merkle tree merkleProof: type: array description: The Merkle proof demonstrating the inclusion of the leaf items: $ref: "#/components/schemas/Hash256" StorageProof: type: object description: Represents a proof of storage for a file contract. properties: parentID: allOf: - $ref: "#/components/schemas/FileContractID" - description: The ID of the file contract being proven. leaf: type: string format: byte description: The selected leaf from the Merkle tree of the file's data. proof: type: array description: The Merkle proof demonstrating the inclusion of the leaf. items: $ref: "#/components/schemas/Hash256" Transaction: type: object properties: siacoinInputs: type: array description: List of Siacoin inputs used in the transaction. items: $ref: "#/components/schemas/SiacoinInput" siacoinOutputs: type: array description: List of Siacoin outputs created by the transaction. items: $ref: "#/components/schemas/SiacoinOutput" fileContracts: type: array description: List of file contracts created by the transaction. items: $ref: "#/components/schemas/FileContract" fileContractRevisions: type: array description: List of revisions to existing file contracts included in the transaction. items: $ref: "#/components/schemas/FileContractRevision" storageProofs: type: array description: List of storage proofs asserting the storage of data for file contracts. items: $ref: "#/components/schemas/StorageProof" siafundInputs: type: array description: List of Siafund inputs spent in the transaction. items: $ref: "#/components/schemas/SiafundInput" siafundOutputs: type: array description: List of Siafund outputs created by the transaction. items: $ref: "#/components/schemas/SiafundOutput" minerFees: type: array description: List of miner fees included in the transaction. items: $ref: "#/components/schemas/Currency" arbitraryData: type: array description: Arbitrary binary data included in the transaction. items: type: string format: byte signatures: type: array description: List of cryptographic signatures verifying the transaction. items: $ref: "#/components/schemas/TransactionSignature" TransactionID: allOf: - $ref: "#/components/schemas/Hash256" - description: Unique identifier for a transaction. TransactionSignature: type: object properties: parentID: allOf: - $ref: "#/components/schemas/Hash256" - description: The ID of the transaction being signed publicKeyIndex: type: integer format: uint64 description: The index of the public key used to sign the transaction timelock: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The block height at which the outputs in the transaction can be spent coveredFields: allOf: - $ref: "#/components/schemas/CoveredFields" - description: Indicates which fields of the transaction are covered by the signature signature: allOf: - $ref: "#/components/schemas/Signature" - description: The signature of the transaction UnlockConditions: type: object properties: timelock: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The block height at which the outputs can be spent publicKeys: type: array items: $ref: "#/components/schemas/UnlockKey" signaturesRequired: type: integer format: uint64 description: The number of signatures required to spend the output UnlockKey: type: object properties: algorithm: type: string format: bytes description: | A fixed 16-byte array that specifies the algorithm used to generate the key example: "ed25519" key: description: | A 32-byte key represented as a hex-encoded string. Must be exactly 64 characters long, containing only hexadecimal digits type: string format: bytes pattern: "^[a-fA-F0-9]{64}$" V2BlockData: type: object properties: height: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The height of the block commitment: $ref: "#/components/schemas/Hash256" transactions: type: array items: $ref: "#/components/schemas/V2Transaction" V2FileContract: type: object properties: capacity: type: integer format: uint64 filesize: type: integer format: uint64 fileMerkleRoot: $ref: "#/components/schemas/Hash256" proofHeight: type: integer format: uint64 expirationHeight: type: integer format: uint64 renterOutput: $ref: "#/components/schemas/SiacoinOutput" hostOutput: $ref: "#/components/schemas/SiacoinOutput" missedHostValue: $ref: "#/components/schemas/Currency" totalCollateral: $ref: "#/components/schemas/Currency" renterPublicKey: $ref: "#/components/schemas/PublicKey" hostPublicKey: $ref: "#/components/schemas/PublicKey" revisionNumber: $ref: "#/components/schemas/RevisionNumber" renterSignature: $ref: "#/components/schemas/Signature" hostSignature: $ref: "#/components/schemas/Signature" V2FileContractElement: type: object properties: id: allOf: - $ref: "#/components/schemas/FileContractID" - description: The ID of the element stateElement: allOf: - $ref: "#/components/schemas/StateElement" - description: The state of the element v2FileContract: $ref: "#/components/schemas/V2FileContract" V2FileContractResolution: type: object properties: parent: $ref: "#/components/schemas/V2FileContractElement" resolution: type: object V2FileContractRevision: type: object properties: parent: $ref: "#/components/schemas/V2FileContractElement" revision: $ref: "#/components/schemas/V2FileContract" V2SiacoinInput: type: object properties: parent: $ref: "#/components/schemas/SiacoinElement" satisfiedPolicy: $ref: "#/components/schemas/SatisfiedPolicy" V2SiafundInput: type: object properties: parent: $ref: "#/components/schemas/SiafundElement" claimAddress: $ref: "#/components/schemas/Address" satisfiedPolicy: $ref: "#/components/schemas/SatisfiedPolicy" V2Transaction: type: object properties: siacoinInputs: type: array items: $ref: "#/components/schemas/V2SiacoinInput" siacoinOutputs: type: array items: $ref: "#/components/schemas/SiacoinOutput" siafundInputs: type: array items: $ref: "#/components/schemas/V2SiafundInput" siafundOutputs: type: array items: $ref: "#/components/schemas/SiafundOutput" fileContracts: type: array items: $ref: "#/components/schemas/V2FileContract" fileContractRevisions: type: array items: $ref: "#/components/schemas/V2FileContractRevision" fileContractResolutions: type: array items: $ref: "#/components/schemas/V2FileContractResolution" attestations: type: array items: $ref: "#/components/schemas/Attestation" arbitraryData: type: array items: type: string format: byte newFoundationAddress: $ref: "#/components/schemas/Address" minerFee: $ref: "#/components/schemas/Currency" ############################# # # Helper types # ############################# AutopilotConfig: type: object properties: enabled: type: boolean description: Whether the autopilot is enabled contracts: $ref: "#/components/schemas/ContractsConfig" hosts: $ref: "#/components/schemas/HostsConfig" BlockHeight: type: integer format: uint64 description: The height of a block example: 92813 Bucket: type: object properties: name: $ref: "#/components/schemas/BucketName" policy: type: object properties: publicReadAccess: type: boolean description: Whether the bucket is publicly readable createdAt: type: string format: date-time description: The time the bucket was created BucketName: type: string pattern: (?!(^xn--|.+-s3alias$))^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$ description: The name of the bucket. example: "default" BucketPolicy: type: object description: Defines access rules and permissions for a bucket. properties: publicReadAccess: type: boolean description: Configures public read access to all the objects in the bucket. BuildState: type: object properties: buildTime: type: string format: date-time description: The build time of the build commit: type: string description: The commit hash of the build version: type: string description: The version of the build os: type: string description: The operating system of the build ConfigRecommendation: type: object properties: gougingSettings: $ref: "#/components/schemas/GougingSettings" ConsensusState: type: object properties: blockHeight: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The current block height lastBlockTime: type: string format: date-time description: The time of the last block synced: type: boolean description: Whether the node is synced with the network ContractLockID: type: object properties: lockID: type: integer format: uint64 description: The ID of the lock example: 12 ContractMetric: type: object properties: timestamp: type: string format: date-time contractID: $ref: "#/components/schemas/FileContractID" hostKey: $ref: "#/components/schemas/PublicKey" remainingCollateral: $ref: "#/components/schemas/Currency" remainingFunds: $ref: "#/components/schemas/Currency" revisionNumber: $ref: "#/components/schemas/RevisionNumber" deleteSpending: $ref: "#/components/schemas/Currency" fundAccountSpending: $ref: "#/components/schemas/Currency" sectorRootsSpending: $ref: "#/components/schemas/Currency" uploadSpending: $ref: "#/components/schemas/Currency" ContractPruneMetric: type: object properties: timestamp: type: string format: date-time contractID: $ref: "#/components/schemas/FileContractID" hostKey: $ref: "#/components/schemas/PublicKey" hostVersion: type: string pruned: type: integer format: uint64 remaining: type: integer format: uint64 duration: type: integer format: int64 description: Duration in nanoseconds ContractsConfig: type: object properties: amount: type: integer format: uint64 description: The minimum number of contracts to form default: 0 period: type: integer format: uint64 description: The length of a contract's period in blocks (1 block being 10 minutes on average) default: 0 renewWindow: type: integer format: uint64 description: The number of blocks before the end of a contract that a contract should be renewed default: 0 download: type: integer format: uint64 description: Expected download bandwidth used per period in bytes default: 0 upload: type: integer format: uint64 description: Expected upload bandwidth used per period in bytes default: 0 storage: type: integer format: uint64 description: Expected amount of data stored in bytes default: 0 prune: type: boolean description: Whether to automatically prune deleted data from contracts default: false ContractSize: type: object properties: prunable: type: integer format: uint64 description: The amount of data that can be pruned from a contract size: type: integer format: uint64 description: The total size of a contract DurationMS: type: integer format: int64 description: A duration in milliseconds example: 30000 EncryptionKey: type: string pattern: ^(key|skey):[0-9a-fA-F]{64}$ description: A key used to encrypt and decrypt data. The key is either a regular key (key) or a salted key (skey). The latter requires a seed to be used for encryption and decryption. ETag: type: string pattern: '^(W/)?".*?"$' description: An ETag representing a resource example: "W/\"33a64df551425fcc55e4d42a148795d9f25f89d4\"" Event: type: object description: A transaction or other event that affects the wallet including miner payouts, siafund claims, and file contract payouts. properties: id: allOf: - $ref: "#/components/schemas/Hash256" - description: The event's ID index: allOf: - $ref: "#/components/schemas/ChainIndex" - description: Information about the block that triggered the creation of this event confirmations: type: integer format: uint64 description: The number of blocks on top of the block that triggered the creation of this event type: type: string enum: - miner - foundation - siafundClaim - v1Transaction - v1ContractResolution - v2Transaction - v2ContractResolution description: The type of the event data: type: object maturityHeight: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The block height at which the payout matures. timestamp: type: string format: date-time description: The time the event was created relevant: type: array items: $ref: "#/components/schemas/Address" GougingParams: type: object properties: consensusState: $ref: "#/components/schemas/ConsensusState" gougingSettings: $ref: "#/components/schemas/GougingSettings" redundancySettings: $ref: "#/components/schemas/RedundancySettings" GougingSettings: type: object properties: maxRPCPrice: allOf: - $ref: "#/components/schemas/Currency" - description: The maximum base price a host can charge per RPC maxContractPrice: allOf: - $ref: "#/components/schemas/Currency" - description: The maximum price a host can charge for a contract formation maxDownloadPrice: allOf: - $ref: "#/components/schemas/Currency" - description: The maximum price a host can charge for downloading in hastings / byte maxUploadPrice: allOf: - $ref: "#/components/schemas/Currency" - description: The maximum price a host can charge for uploading in hastings / byte maxStoragePrice: allOf: - $ref: "#/components/schemas/Currency" - description: The maximum price a host can charge for storage in hastings / byte / block hostBlockHeightLeeway: type: integer format: uint32 description: The number of blocks a host's chain's height can diverge from our own before we stop using it minPriceTableValidity: type: integer format: uint64 description: The time a host's price table should be valid after acquiring it in milliseconds minAccountExpiry: type: integer format: uint64 description: The minimum amount of time an account on a host can be idle for before expiring minMaxEphemeralAccountBalance: allOf: - $ref: "#/components/schemas/Currency" - description: The minimum max balance a host should allow us to fund an account with GougingSettingsPins: type: object properties: maxDownload: $ref: "#/components/schemas/Pin" maxStorage: $ref: "#/components/schemas/Pin" maxUpload: $ref: "#/components/schemas/Pin" HostsConfig: type: object properties: maxConsecutiveScanFailures: type: integer format: uint64 description: The maximum number of consecutive scan failures before a host is removed from the database default: 0 maxDowntimeHours: type: integer format: uint64 description: The maximum number of hours a host can be offline before it is removed from the database default: 0 minProtocolVersion: type: string description: The minimum supported protocol version of a host to be considered good Host: type: object properties: knownSince: type: string format: date-time description: The time the host was first seen lastAnnouncement: type: string format: date-time description: The time the host last announced itself publicKey: $ref: "#/components/schemas/PublicKey" netAddress: type: string description: The address of the host example: "foo.bar:1234" priceTable: $ref: "#/components/schemas/HostPriceTable" settings: $ref: "#/components/schemas/HostSettings" v2Settings: $ref: "#/components/schemas/HostV2Settings" interactions: $ref: "#/components/schemas/HostInteractions" scanned: type: boolean description: Whether the host has been scanned blocked: type: boolean description: Whether the host is blocked checks: $ref: "#/components/schemas/HostChecks" storedData: type: integer format: uint64 description: The amount of data stored on the host in bytes v2SiamuxAddresses: type: array items: type: string description: The addresses of the host for the V2 protocol example: "foo.bar:5678" HostChecks: type: object properties: gougingBreakdown: $ref: '#/components/schemas/HostGougingBreakdown' scoreBreakdown: $ref: '#/components/schemas/HostScoreBreakdown' usabilityBreakdown: $ref: '#/components/schemas/HostUsabilityBreakdown' HostGougingBreakdown: type: object properties: downloadErr: type: string description: Error message related to download gouging checks. gougingErr: type: string description: Error message related to general gouging checks. pruneErr: type: string description: Error message related to pruning checks. uploadErr: type: string description: Error message related to upload gouging checks. HostInfo: type: object properties: publicKey: $ref: "#/components/schemas/PublicKey" siamuxAddr: type: string description: The address of the host example: "foo.bar:1234" v2SiamuxAddresses: type: array items: type: string description: The addresses of the host for the V2 protocol example: "foo.bar:5678" HostInteractions: type: object properties: totalScans: type: integer format: uint64 description: The total number of scans performed on the host. lastScan: type: string format: date-time description: Timestamp of the last scan performed. lastScanSuccess: type: boolean description: Indicates whether the last scan was successful. lostSectors: type: integer format: uint64 description: Number of sectors lost since the last reporting period. secondToLastScanSuccess: type: boolean description: Indicates whether the second-to-last scan was successful. uptime: type: string format: duration description: Total uptime duration of the host. downtime: type: string format: duration description: Total downtime duration of the host. successfulInteractions: type: number format: float description: The number of successful interactions with the host. failedInteractions: type: number format: float description: The number of failed interactions with the host. HostScoreBreakdown: type: object properties: age: type: number format: float description: Score contribution based on the host's age. collateral: type: number format: float description: Score contribution based on the host's collateral amount. interactions: type: number format: float description: Score contribution based on successful interactions. storageRemaining: type: number format: float description: Score contribution based on remaining storage capacity. uptime: type: number format: float description: Score contribution based on host uptime. version: type: number format: float description: Score contribution based on the host's software version. prices: type: number format: float description: Score contribution based on pricing metrics. HostUsabilityBreakdown: type: object properties: blocked: type: boolean description: Indicates if the host is blocked. offline: type: boolean description: Indicates if the host is offline. lowMaxDuration: type: boolean description: Indicates if the host has a low maximum contract duration. lowScore: type: boolean description: Indicates if the host has a low score. redundantIP: type: boolean description: Indicates if the host's IP address is redundant. gouging: type: boolean description: Indicates if the host is gouging prices. notAcceptingContracts: type: boolean description: Indicates if the host is not accepting new contracts. notAnnounced: type: boolean description: Indicates if the host has not been announced on the network. notCompletingScan: type: boolean description: Indicates if the host is failing to complete scans. MemoryStatus: type: object properties: available: type: integer format: uint64 description: The amount of remaining memory currently available in bytes example: 83886080 total: type: integer format: uint64 description: The total amount of memory available in bytes example: 1073741824 minimum: 1 MimeType: type: string description: The MIME type of the object example: "text/plain" MultipartUpload: type: object properties: bucket: type: string description: The name of the bucket encryptionKey: $ref: "#/components/schemas/EncryptionKey" key: type: string description: The key of the object uploadID: allOf: - $ref: "#/components/schemas/UploadID" - description: The ID of the multipart upload createdAt: type: string format: date-time description: When the upload was created MultipartListPartItem: type: object properties: partNumber: $ref: "#/components/schemas/MultipartPartNumber" lastModified: type: string format: date-time description: When this part was last modified eTag: $ref: "#/components/schemas/ETag" size: type: integer format: int64 description: The size of this part in bytes MultipartCompletedPart: type: object properties: partNumber: $ref: "#/components/schemas/MultipartPartNumber" eTag: $ref: "#/components/schemas/ETag" MultipartPartNumber: type: integer description: The number of this part minimum: 1 maximum: 10000 example: 123 MultipartUploadID: type: string pattern: ^[0-9a-fA-F]{64}$ description: A unique identifier for a multipart upload example: "7aaac83c6d553865755286c326e852a68300bebf7feea1b435d61bd3610bf82b" Network: type: object properties: name: type: string description: The name of the network initialCoinbase: allOf: - $ref: "#/components/schemas/Currency" - description: The initial coinbase reward - default: "300000000000000000000000000000" minimumCoinbase: allOf: - $ref: "#/components/schemas/Currency" - description: The minimum coinbase reward - default: "30000000000000000000000000000" initialTarget: allOf: - $ref: "#/components/schemas/BlockID" - description: The initial target - default: "0000000020000000000000000000000000000000000000000000000000000000" blockInterval: type: integer format: uint64 description: The block interval default: 600000000000 maturityDelay: type: integer format: uint64 description: The maturity delay default: 144 hardforkDevAddr: type: object properties: height: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The height of the hardfork - example: 10000 oldAddress: allOf: - $ref: "#/components/schemas/Address" - description: The old developer address - default: "7d0c44f7664e2d34e53efde0661a6f628ec9264785ae8e3cd7c973e8d190c3c97b5e3ecbc567" newAddress: allOf: - $ref: "#/components/schemas/Address" - description: The new developer address - default: "f371c70bce9eb8979cd5099f599ec4e4fcb14e0afcf31f9791e03e6496a4c0b358c98279730b" hardforkTax: type: object properties: height: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The height of the hardfork - example: 21000 hardforkStorageProof: type: object properties: height: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The height of the hardfork - example: 100000 hardforkOak: type: object properties: height: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The height of the hardfork - example: 135000 fixHeight: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The height of the fix - example: 139000 genesisTimestamp: type: string format: date-time description: The genesis timestamp default: "2015-06-06T16:13:20+02:00" hardforkASIC: type: object properties: height: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The height of the hardfork - example: 179000 oakTime: type: integer format: uint64 description: The oak time oakTarget: allOf: - $ref: "#/components/schemas/BlockID" - description: The oak target hardforkFoundation: type: object properties: height: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The height of the hardfork - example: 298000 primaryAddress: allOf: - $ref: "#/components/schemas/Address" - description: The primary address - default: "053b2def3cbdd078c19d62ce2b4f0b1a3c5e0ffbeeff01280efb1f8969b2f5bb4fdc680f0807" failsafeAddress: allOf: - $ref: "#/components/schemas/Address" - description: The failsafe address - default: "27c22a6c6e6645802a3b8fa0e5374657438ef12716d2205d3e866272de1b644dbabd53d6d560" hardforkV2: type: object properties: allowHeight: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The height at which V2 consensus types are allowed - example: 1000000 requireHeight: allOf: - $ref: "#/components/schemas/BlockHeight" - description: The height at which V2 consensus types are required - example: 1025000 Object: type: object allOf: - type: object properties: metadata: $ref: "#/components/schemas/ObjectUserMetadata" - $ref: "#/components/schemas/ObjectMetadata" - type: object properties: encryptionKey: $ref: "#/components/schemas/EncryptionKey" slabs: type: array items: $ref: "#/components/schemas/SlabSlice" ObjectKey: type: string example: "folder/file" minLength: 1 ObjectMetadata: type: object properties: bucket: $ref: "#/components/schemas/BucketName" etag: allOf: - $ref: "#/components/schemas/ETag" - description: The ETag of the object health: type: number format: float description: The health of the object modTime: type: string format: date-time description: When the object was last modified key: type: string description: The key of the object size: type: integer format: int64 description: The size of the object in bytes mimeType: type: string description: The MIME type of the object ObjectUserMetadata: type: object additionalProperties: type: string description: User-defined metadata about an object provided through X-Sia-Meta- headers PackedSlab: type: object properties: bufferID: type: integer format: uint description: ID of the buffer containing the slab data: type: string format: binary description: The slab data encryptionKey: $ref: "#/components/schemas/EncryptionKey" Pin: type: object properties: pinned: type: boolean description: Whether pin is enabled value: type: number format: float64 description: The value of the underlying currency to which the setting is pinned PinnedSettings: type: object properties: currency: $ref: "#/components/schemas/Currency" threshold: type: number format: float64 description: A percentage between 0 and 1 that determines when the pinned settings are updated based on the exchange rate at the time gougingSettingsPins: $ref: "#/components/schemas/GougingSettingsPins" Priority: type: integer format: int example: 80 RedundancySettings: type: object properties: minShards: $ref: "#/components/schemas/RedundancySettingsMinShards" totalShards: $ref: "#/components/schemas/RedundancySettingsTotalShards" RedundancySettingsMinShards: type: integer minimum: 1 format: uint8 description: The number of data shards a piece of an object gets erasure-coded into default: 10 RedundancySettingsTotalShards: type: integer minimum: 2 format: uint8 description: The number of total data shards a piece of an object gets erasure-coded into default: 30 Revision: type: object properties: contractID: $ref: "#/components/schemas/FileContractID" missedHostValue: $ref: "#/components/schemas/Currency" renterFunds: $ref: "#/components/schemas/Currency" revisionNumber: $ref: "#/components/schemas/RevisionNumber" size: type: integer format: uint64 description: The size of the contract in bytes RevisionNumber: type: integer format: uint64 description: The revision number of the contract example: 246 SemVer: type: array description: "Represents a semantic version as an array of three unsigned 8-bit integers: [major, minor, patch]" minItems: 3 maxItems: 3 items: type: integer format: uint8 minimum: 0 maximum: 255 example: [1, 2, 3] SettingsID: type: string description: A 16-byte unique identifier represented as a hex string. format: byte example: "4d3b2a1c9f8e7d6c5b4a3f2e1d0c9b8a" SlabBuffer: type: object properties: complete: type: boolean description: Whether the slab buffer is complete and ready to upload filename: type: string description: Name of the buffer on disk size: type: integer format: int64 description: Size of the buffer maxSize: type: integer format: int64 description: Maximum size of the buffer locked: type: boolean description: Whether the slab buffer is locked for uploading UploadID: type: string description: A 32-byte unique identifier represented as a hex string. format: byte example: "f1e2d3c4b5a697887776665544332211ffeeddccbbaa99887766554433221100" Slab: type: object description: A slab of data to migrate properties: health: type: number format: float minimum: 0 maximum: 1 encryptionKey: allOf: - $ref: "#/components/schemas/EncryptionKey" - description: The encryption key used to encrypt the slab's shards minShards: allOf: - $ref: "#/components/schemas/RedundancySettingsMinShards" - description: The number of data shards the slab is split into SlabSlice: type: object description: A contiguous region within a slab properties: slab: $ref: "#/components/schemas/Slab" offset: type: integer format: uint32 limit: type: integer format: uint32 SyncerAddress: type: string description: The address of the syncer example: "118.92.232.145:9981" S3Settings: type: object properties: accessKeyID: type: string description: S3 access key ID secretAccessKey: type: string description: S3 secret access key disableAuth: type: boolean description: Whether to disable S3 authentication UploadedPackedSlab: type: object properties: bufferID: type: integer format: uint description: ID of the buffer containing the slab shards: type: array items: $ref: "#/components/schemas/UploadedSector" UploadedSector: type: object properties: contractID: $ref: "#/components/schemas/FileContractID" root: $ref: "#/components/schemas/Hash256" UploadSettings: type: object properties: packing: $ref: "#/components/schemas/UploadPackingSettings" redundancy: $ref: "#/components/schemas/RedundancySettings" UploadPackingSettings: type: object properties: enabled: type: boolean description: Whether upload packing is enabled slabBufferMaxSizeSoft: type: integer format: int64 description: Maximum size for slab buffers WalletMetric: type: object properties: timestamp: type: string format: date-time confirmed: $ref: "#/components/schemas/Currency" spendable: $ref: "#/components/schemas/Currency" unconfirmed: $ref: "#/components/schemas/Currency" immature: $ref: "#/components/schemas/Currency" Webhook: type: object properties: module: type: string description: The module this webhook belongs to enum: - alerts event: type: string description: The event type this webhook listens for enum: - dismiss - register url: type: string description: The URL to send webhook events to example: "https://foo.com:8000/api/events" headers: type: object additionalProperties: type: string description: Custom headers to include in webhook requests WebhookEvent: type: object properties: module: type: string description: The module that triggered the event enum: - alerts event: type: string description: The type of event that occurred enum: - dismiss - register data: type: object description: Event-specific data payload WebhookQueueInfo: type: object properties: url: type: string description: The URL of the webhook numPending: type: integer description: Number of pending events in queue lastSuccess: type: string format: date-time description: Timestamp of last successful delivery lastError: type: string format: date-time description: Timestamp of last failed delivery lastErrorMessage: type: string description: Message from last failed delivery