gitlab.com/SiaPrime/SiaPrime@v1.4.1/doc/api/Renter.md (about) 1 Renter API 2 ========== 3 4 The Sia API documentation can be found here: 5 [Sia API](https://sia.tech/docs/ "Sia API") 6 7 There may be functional API calls which are not documented. These are not 8 guaranteed to be supported beyond the current release, and should not be used 9 in production. 10 11 Overview 12 -------- 13 14 The renter manages the user's files on the network. The renter's API endpoints 15 expose methods for managing files on the network and managing the renter's 16 allocated funds. 17 18 Index 19 ----- 20 21 | Route | HTTP verb | 22 | ------------------------------------------------------------------------------- | --------- | 23 | [/renter](#renter-get) | GET | 24 | [/renter](#renter-post) | POST | 25 | [/renter/contract/cancel](#rentercontractcancel-post) | POST | 26 | [/renter/contracts](#rentercontracts-get) | GET | 27 | [/renter/downloads](#renterdownloads-get) | GET | 28 | [/renter/downloads/clear](#renterdownloadsclear-post) | POST | 29 | [/renter/files](#renterfiles-get) | GET | 30 | [/renter/file/*___siapath___](#renterfilesiapath-get) | GET | 31 | [/renter/file/*__siapath__](#rentertrackingsiapath-post) | POST | 32 | [/renter/prices](#renterprices-get) | GET | 33 | [/renter/delete/___*siapath___](#renterdelete___siapath___-post) | POST | 34 | [/renter/download/___*siapath___](#renterdownload__siapath___-get) | GET | 35 | [/renter/downloadasync/___*siapath___](#renterdownloadasync__siapath___-get) | GET | 36 | [/renter/rename/___*siapath___](#renterrename___siapath___-post) | POST | 37 | [/renter/stream/___*siapath___](#renterstreamsiapath-get) | GET | 38 | [/renter/upload/___*siapath___](#renteruploadsiapath-post) | POST | 39 40 #### /renter [GET] 41 42 returns the current settings along with metrics on the renter's spending. 43 44 ###### JSON Response 45 ```javascript 46 { 47 // Settings that control the behavior of the renter. 48 "settings": { 49 // Allowance dictates how much the renter is allowed to spend in a given 50 // period. Note that funds are spent on both storage and bandwidth. 51 "allowance": { 52 // Amount of money allocated for contracts. Funds are spent on both 53 // storage and bandwidth. 54 "funds": "1234", // hastings 55 56 // Number of hosts that contracts will be formed with. 57 "hosts":24, 58 59 // Duration of contracts formed, in number of blocks. 60 "period": 6048, // blocks 61 62 // If the current blockheight + the renew window >= the height the 63 // contract is scheduled to end, the contract is renewed automatically. 64 // Is always nonzero. 65 "renewwindow": 3024 // blocks 66 }, 67 // MaxUploadSpeed by default is unlimited but can be set by the user to 68 // manage bandwidth 69 "maxuploadspeed": 1234, // bytes per second 70 71 // MaxDownloadSpeed by default is unlimited but can be set by the user to 72 // manage bandwidth 73 "maxdownloadspeed": 1234, // bytes per second 74 75 // The StreamCacheSize is the number of data chunks that will be cached during 76 // streaming 77 "streamcachesize": 4 78 }, 79 80 // Metrics about how much the Renter has spent on storage, uploads, and 81 // downloads. 82 "financialmetrics": { 83 // Amount of money spent on contract fees, transaction fees and siafund fees. 84 "contractfees": "1234", // hastings 85 86 // How much money, in hastings, the Renter has spent on file contracts, 87 // including fees. 88 "contractspending": "1234", // hastings, (deprecated, now totalallocated) 89 90 // Amount of money spent on downloads. 91 "downloadspending": "5678", // hastings 92 93 // Amount of money spend on storage. 94 "storagespending": "1234", // hastings 95 96 // Total amount of money that the renter has put into contracts. Includes 97 // spent money and also money that will be returned to the renter. 98 "totalallocated": "1234", // hastings 99 100 // Amount of money spent on uploads. 101 "uploadspending": "5678", // hastings 102 103 // Amount of money in the allowance that has not been spent. 104 "unspent": "1234" // hastings 105 }, 106 // Height at which the current allowance period began. 107 "currentperiod": 200 108 } 109 ``` 110 111 #### /renter [POST] 112 113 modify settings that control the renter's behavior. 114 115 ###### Query String Parameters 116 ``` 117 // Number of hastings allocated for file contracts in the given period. 118 funds // hastings 119 120 // Number of hosts that contracts should be formed with. Files cannot be 121 // uploaded to more hosts than you have contracts with, and it's generally good 122 // to form a few more contracts than you need. 123 hosts 124 125 // Duration of contracts formed. Must be nonzero. 126 period // block height 127 128 // Renew window specifies how many blocks before the expiration of the current 129 // contracts the renter will wait before renewing the contracts. A smaller 130 // renew window means that SiaPrime must be run more frequently, but also means 131 // fewer total transaction fees. Storage spending is not affected by the renew 132 // window size. 133 renewwindow // block height 134 135 // Max download speed permitted, speed provide in bytes per second 136 maxdownloadspeed 137 138 // Max upload speed permitted, speed provide in bytes per second 139 maxuploadspeed 140 141 // Stream cache size specifies how many data chunks will be cached while 142 // streaming. 143 streamcachesize 144 ``` 145 146 ###### Response 147 standard success or error response. See 148 [API.md#standard-responses](/doc/API.md#standard-responses). 149 150 #### /renter/contract/cancel [POST] 151 152 cancels a specific contract of the Renter. 153 154 ###### Query String Parameter 155 ``` 156 // ID of the file contract 157 id 158 ``` 159 160 ###### Response 161 standard success or error response. See 162 [API.md#standard-responses](/doc/API.md#standard-responses). 163 164 #### /renter/contracts [GET] 165 166 returns the renter's contracts. Active contracts are contracts that the Renter 167 is currently using to store, upload, and download data, and are returned by 168 default. Inactive contracts are contracts that are in the current period but are 169 marked as not good for renew, these contracts have the potential to become 170 active again but currently are not storing data. Expired contracts are 171 contracts not in the current period, where not more data is being stored and 172 excess funds have been released to the renter. 173 174 ###### Contract Parameters 175 ``` 176 inactive // true or false - Optional 177 expired // true or false - Optional 178 ``` 179 180 ###### JSON Response 181 ```javascript 182 { 183 "activecontracts": [ 184 { 185 // Amount of contract funds that have been spent on downloads. 186 "downloadspending": "1234", // hastings 187 188 // Block height that the file contract ends on. 189 "endheight": 50000, // block height 190 191 // Fees paid in order to form the file contract. 192 "fees": "1234", // hastings 193 194 // Public key of the host the contract was formed with. 195 "hostpublickey": { 196 "algorithm": "ed25519", 197 "key": "RW50cm9weSBpc24ndCB3aGF0IGl0IHVzZWQgdG8gYmU=" 198 }, 199 200 // ID of the file contract. 201 "id": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef", 202 203 // A signed transaction containing the most recent contract revision. 204 "lasttransaction": {}, 205 206 // Address of the host the file contract was formed with. 207 "netaddress": "12.34.56.78:9", 208 209 // Remaining funds left for the renter to spend on uploads & downloads. 210 "renterfunds": "1234", // hastings 211 212 // Size of the file contract, which is typically equal to the number of 213 // bytes that have been uploaded to the host. 214 "size": 8192, // bytes 215 216 // Block height that the file contract began on. 217 "startheight": 50000, // block height 218 219 // DEPRECATED: This is the exact same value as StorageSpending, but it has 220 // incorrect capitalization. This was fixed in 1.3.2, but this field is kept 221 // to preserve backwards compatibility on clients who depend on the 222 // incorrect capitalization. This field will be removed in the future, so 223 // clients should switch to the StorageSpending field (above) with the 224 // correct lowercase name. 225 "StorageSpending": 0, 226 227 // Amount of contract funds that have been spent on storage. 228 "storagespending": "1234", // hastings 229 230 // Total cost to the wallet of forming the file contract. 231 // This includes both the fees and the funds allocated in the contract. 232 "totalcost": "1234", // hastings 233 234 // Amount of contract funds that have been spent on uploads. 235 "uploadspending": "1234" // hastings 236 237 // Signals if contract is good for uploading data 238 "goodforupload": true, 239 240 // Signals if contract is good for a renewal 241 "goodforrenew": false, 242 } 243 ], 244 "inactivecontracts": [], 245 "expiredcontracts": [], 246 } 247 ``` 248 249 #### /renter/downloads [GET] 250 251 lists all files in the download queue. 252 253 ###### JSON Response 254 ```javascript 255 { 256 "downloads": [ 257 { 258 // Local path that the file will be downloaded to. 259 "destination": "/home/users/alice", 260 261 // What type of destination was used. Can be "file", indicating a download 262 // to disk, can be "buffer", indicating a download to memory, and can be 263 // "http stream", indicating that the download was streamed through the 264 // http API. 265 "destinationtype": "file", 266 267 // Length of the download. If the download was a partial download, this 268 // will indicate the length of the partial download, and not the length of 269 // the full file. 270 "length": 8192, // bytes 271 272 // Offset within the file of the download. For full file downloads, the // 273 offset will be '0'. For partial downloads, the offset may be anywhere // 274 within the file. offset+length will never exceed the full file size. 275 "offset": 0, 276 277 // Siapath given to the file when it was uploaded. 278 "siapath": "foo/bar.txt", 279 280 // Whether or not the download has completed. Will be false initially, and 281 // set to true immediately as the download has been fully written out to 282 // the file, to the http stream, or to the in-memory buffer. Completed 283 // will also be set to true if there is an error that causes the download to 284 // fail. 285 "completed": true, 286 287 // Time at which the download completed. Will be zero if the download has 288 // not yet completed. 289 "endtime": "2009-11-10T23:00:00Z", // RFC 3339 time 290 291 // Error encountered while downloading. If there was no error (yet), it 292 // will be the empty string. 293 "error": "" 294 295 // Number of bytes downloaded thus far. Will only be updated as segments 296 // of the file complete fully. This typically has a resolution of tens of 297 // megabytes. 298 "received": 4096, // bytes 299 300 // Time at which the download was initiated. 301 "starttime": "2009-11-10T23:00:00Z", // RFC 3339 time 302 303 // The total amount of data transfered when downloading the file. This 304 // will eventually include data transferred during contract + payment 305 // negotiation, as well as data from failed piece downloads. 306 "totaldatatransfered": 10321, 307 } 308 ] 309 } 310 ``` 311 #### /renter/downloads/clear [POST] 312 313 Clears the download history of the renter for a range of unix time stamps. Both 314 parameters are optional, if no parameters are provided, the entire download 315 history will be cleared. To clear a single download, provide the timestamp for 316 the download as both parameters. Providing only the before parameter will clear 317 all downloads older than the timestamp. Conversely, providing only the after 318 parameter will clear all downloads newer than the timestamp. 319 320 ###### Timestamp Parameters [(with comments)] 321 ``` 322 before // Optional - unix timestamp found in the download history 323 after // Optional - unix timestamp found in the download history 324 ``` 325 326 ###### Response 327 standard success or error response. See 328 [API.md#standard-responses](/doc/API.md#standard-responses). 329 330 #### /renter/files [GET] 331 332 lists the status of all files. 333 334 ###### JSON Response 335 ```javascript 336 { 337 "files": [ 338 { 339 // Path to the file in the renter on the network. 340 "siapath": "foo/bar.txt", 341 342 // Path to the local file on disk. 343 "localpath": "/home/foo/bar.txt", 344 345 // Size of the file in bytes. 346 "filesize": 8192, // bytes 347 348 // true if the file is available for download. Files may be available 349 // before they are completely uploaded. 350 "available": true, 351 352 // true if the file's contracts will be automatically renewed by the 353 // renter. 354 "renewing": true, 355 356 // Average redundancy of the file on the network. Redundancy is 357 // calculated by dividing the amount of data uploaded in the file's open 358 // contracts by the size of the file. Redundancy does not necessarily 359 // correspond to availability. Specifically, a redundancy >= 1 does not 360 // indicate the file is available as there could be a chunk of the file 361 // with 0 redundancy. 362 "redundancy": 5, 363 364 // Total number of bytes successfully uploaded via current file contracts. 365 // This number includes padding and rendundancy, so a file with a size of 366 // 8192 bytes might be padded to 40 MiB and, with a redundancy of 5, 367 // encoded to 200 MiB for upload. 368 "uploadedbytes": 209715200, // bytes 369 370 // Percentage of the file uploaded, including redundancy. Uploading has 371 // completed when uploadprogress is 100. Files may be available for 372 // download before upload progress is 100. 373 "uploadprogress": 100, // percent 374 375 // Block height at which the file ceases availability. 376 "expiration": 60000 377 } 378 ] 379 } 380 ``` 381 382 #### /renter/file/*___siapath___ [GET] 383 384 lists the status of specified file. 385 386 ###### JSON Response 387 ```javascript 388 { 389 "file": { 390 // Path to the file in the renter on the network. 391 "siapath": "foo/bar.txt", 392 393 // Path to the local file on disk. 394 "localpath": "/home/foo/bar.txt", 395 396 // Size of the file in bytes. 397 "filesize": 8192, // bytes 398 399 // true if the file is available for download. Files may be available 400 // before they are completely uploaded. 401 "available": true, 402 403 // true if the file's contracts will be automatically renewed by the 404 // renter. 405 "renewing": true, 406 407 // Average redundancy of the file on the network. Redundancy is 408 // calculated by dividing the amount of data uploaded in the file's open 409 // contracts by the size of the file. Redundancy does not necessarily 410 // correspond to availability. Specifically, a redundancy >= 1 does not 411 // indicate the file is available as there could be a chunk of the file 412 // with 0 redundancy. 413 "redundancy": 5, 414 415 // Total number of bytes successfully uploaded via current file contracts. 416 // This number includes padding and rendundancy, so a file with a size of 417 // 8192 bytes might be padded to 40 MiB and, with a redundancy of 5, 418 // encoded to 200 MiB for upload. 419 "uploadedbytes": 209715200, // bytes 420 421 // Percentage of the file uploaded, including redundancy. Uploading has 422 // completed when uploadprogress is 100. Files may be available for 423 // download before upload progress is 100. 424 "uploadprogress": 100, // percent 425 426 // Block height at which the file ceases availability. 427 "expiration": 60000 428 } 429 } 430 ``` 431 432 #### /renter/file/*___siapath___ [POST] 433 434 endpoint for changing file metadata. 435 436 ###### Path Parameters [(with comments)](/doc/api/Renter.md#path-parameters-3) 437 ``` 438 // SiaPath of the file on the network. The path must be non-empty, may not 439 // include any path traversal strings ("./", "../"), and may not begin with a 440 // forward-slash character. 441 *siapath 442 ``` 443 444 ###### Query String Parameters [(with comments)](/doc/api/Renter.md#query-string-parameters-3) 445 ``` 446 // If provided, this parameter changes the tracking path of a file to the 447 // specified path. Useful if moving the file to a different location on disk. 448 trackingpath 449 ``` 450 451 ###### Response 452 standard success or error response. See 453 [#standard-responses](#standard-responses). 454 455 #### /renter/prices [GET] 456 457 lists the estimated prices of performing various storage and data operations. An 458 allowance can be submitted to provide a more personalized estimate. If no 459 allowance is submitted then the current set allowance will be used, if there is 460 no allowance set then sane defaults will be used. Submitting an allowance is 461 optional, but when submitting an allowance all the components of the allowance 462 are required. The allowance used to create the estimate is returned with the 463 estimate. 464 465 ###### Query String Parameters 5 466 ``` 467 all optional or all required 468 469 // Number of hastings allocated for file contracts in the given period. 470 funds // hastings 471 472 // Number of hosts that contracts should be formed with. Files cannot be 473 // uploaded to more hosts than you have contracts with, and it's generally good 474 // to form a few more contracts than you need. 475 hosts 476 477 // Duration of contracts formed. Must be nonzero. 478 period // block height 479 480 // Renew window specifies how many blocks before the expiration of the current 481 // contracts the renter will wait before renewing the contracts. A smaller 482 // renew window means that SiaPrime must be run more frequently, but also means 483 // fewer total transaction fees. Storage spending is not affected by the renew 484 // window size. 485 renewwindow // block height 486 ``` 487 488 ###### JSON Response 5 489 ```javascript 490 { 491 // The estimated cost of downloading one terabyte of data from the 492 // network. 493 "downloadterabyte": "1234", // hastings 494 495 // The estimated cost of forming a set of contracts on the network. This 496 // cost also applies to the estimated cost of renewing the renter's set of 497 // contracts. 498 "formcontracts": "1234", // hastings 499 500 // The estimated cost of storing one terabyte of data on the network for 501 // a month, including accounting for redundancy. 502 "storageterabytemonth": "1234", // hastings 503 504 // The estimated cost of uploading one terabyte of data to the network, 505 // including accounting for redundancy. 506 "uploadterabyte": "1234", // hastings 507 508 // Amount of money allocated for contracts. Funds are spent on both 509 // storage and bandwidth. 510 "funds": "1234", // hastings 511 512 // Number of hosts that contracts will be formed with. 513 "hosts":24, 514 515 // Duration of contracts formed, in number of blocks. 516 "period": 6048, // blocks 517 518 // If the current blockheight + the renew window >= the height the 519 // contract is scheduled to end, the contract is renewed automatically. 520 // Is always nonzero. 521 "renewwindow": 3024 // blocks 522 } 523 ``` 524 525 #### /renter/delete/___*siapath___ [POST] 526 527 deletes a renter file entry. Does not delete any downloads or original files, 528 only the entry in the renter. 529 530 ###### Path Parameters 531 ``` 532 // Location of the file in the renter on the network. 533 *siapath 534 ``` 535 536 ###### Response 537 standard success or error response. See 538 [API.md#standard-responses](/doc/API.md#standard-responses). 539 540 #### /renter/download/___*siapath___ [GET] 541 542 downloads a file to the local filesystem. The call will block until the file 543 has been downloaded. 544 545 ###### Path Parameters 546 ``` 547 // Location of the file in the renter on the network. 548 *siapath 549 ``` 550 551 ###### Query String Parameters 552 ``` 553 // If async is true, the http request will be non blocking. Can't be used with 554 async 555 // Location on disk that the file will be downloaded to. 556 destination 557 // If httresp is true, the data will be written to the http response. 558 httpresp 559 // Length of the requested data. Has to be <= filesize-offset. 560 length 561 // Offset relative to the file start from where the download starts. 562 offset 563 ``` 564 565 ###### Response 566 standard success or error response. See 567 [API.md#standard-responses](/doc/API.md#standard-responses). 568 569 #### /renter/downloadasync/___*siapath___ [GET] 570 571 downloads a file to the local filesystem. The call will return immediately. 572 573 ###### Path Parameters 574 ``` 575 *siapath 576 ``` 577 578 ###### Query String Parameters 579 ``` 580 destination 581 ``` 582 583 ###### Response 584 standard success or error response. See 585 [API.md#standard-responses](/doc/API.md#standard-responses). 586 587 #### /renter/rename/___*siapath___ [POST] 588 589 renames a file. Does not rename any downloads or source files, only renames the 590 entry in the renter. An error is returned if `siapath` does not exist or 591 `newsiapath` already exists. 592 593 ###### Path Parameters 594 ``` 595 // Current location of the file in the renter on the network. 596 *siapath 597 ``` 598 599 ###### Query String Parameters 600 ``` 601 // New location of the file in the renter on the network. 602 newsiapath 603 ``` 604 605 ###### Response 606 standard success or error response. See 607 [API.md#standard-responses](/doc/API.md#standard-responses). 608 609 #### /renter/stream/*___siapath___ [GET] 610 611 downloads a file using http streaming. This call blocks until the data is 612 received. 613 The streaming endpoint also uses caching internally to prevent siad from 614 re-downloading the same chunk multiple times when only parts of a file are 615 requested at once. This might lead to a substantial increase in ram usage and 616 therefore it is not recommended to stream multiple files in parallel at the 617 moment. This restriction will be removed together with the caching once partial 618 downloads are supported in the future. If you want to stream multiple files you 619 should increase the size of the Renter's `streamcachesize` to at least 2x the 620 number of files you are steaming. 621 622 ###### Path Parameters [(with comments)](/doc/api/Renter.md#path-parameters-1) 623 ``` 624 *siapath 625 ``` 626 627 ###### Response 628 standard success with the requested data in the body or error response. See 629 [#standard-responses](#standard-responses). 630 631 #### /renter/upload/___*siapath___ [POST] 632 633 starts a file upload to the SiaPrime network from the local filesystem. 634 635 ###### Path Parameters 636 637 ``` 638 // Location where the file will reside in the renter on the network. The path 639 // must be non-empty, may not include any path traversal strings ("./", "../"), 640 // and may not begin with a forward-slash character. 641 *siapath 642 ``` 643 644 ###### Query String Parameters 645 ``` 646 // The number of data pieces to use when erasure coding the file. 647 datapieces // int 648 649 // The number of parity pieces to use when erasure coding the file. Total 650 // redundancy of the file is (datapieces+paritypieces)/datapieces. 651 paritypieces // int 652 653 // Location on disk of the file being uploaded. 654 source // string - a filepath 655 ``` 656 657 ###### Response 658 standard success or error response. See 659 [API.md#standard-responses](/doc/API.md#standard-responses). A successful 660 response indicates that the upload started successfully. To confirm the upload 661 completed successfully, the caller must call [/renter/files](#renterfiles-get) 662 until that API returns success with an `uploadprogress` >= 100.0 for the file 663 at the given `siapath`.