[{"data":1,"prerenderedAt":1003},["ShallowReactive",2],{"docs:\u002Fdocs\u002Fapi\u002Fplacement":3,"docs:nav":956},{"id":4,"title":5,"badge":6,"body":7,"description":29,"extension":948,"meta":949,"navigation":950,"order":71,"path":951,"section":952,"seo":953,"stem":954,"__hash__":955},"docs\u002Fdocs\u002Fapi\u002Fplacement.md","Placement",null,{"type":8,"value":9,"toc":939},"minimark",[10,18,23,89,95,156,159,168,331,397,407,411,417,462,550,558,562,574,577,581,733,743,747,750,772,778,782,787,791,797,818,912,918,935],[11,12,13,17],"p",{},[14,15,16],"code",{},"prepare-write"," is the first call of every upload. It returns a set of providers with funded\ncontracts and an access token for each, ready to receive shards.",[19,20,22],"h2",{"id":21},"post-prepare-write","POST \u002Fprepare-write",[24,25,30],"pre",{"className":26,"code":27,"language":28,"meta":29,"style":29},"language-bash shiki shiki-themes github-dark-default github-dark-default","curl -X POST \"$TESSERA_API\u002Fprepare-write?$AUTH\" \\\n  -H 'content-type: application\u002Fjson' \\\n  -d '{\"totalShards\": 30, \"minShards\": 10}'\n","bash","",[14,31,32,69,80],{"__ignoreMap":29},[33,34,37,41,45,49,52,56,59,62,65],"span",{"class":35,"line":36},"line",1,[33,38,40],{"class":39},"sAxfE","curl",[33,42,44],{"class":43},"sEQcL"," -X",[33,46,48],{"class":47},"skZ57"," POST",[33,50,51],{"class":47}," \"",[33,53,55],{"class":54},"sb7RM","$TESSERA_API",[33,57,58],{"class":47},"\u002Fprepare-write?",[33,60,61],{"class":54},"$AUTH",[33,63,64],{"class":47},"\"",[33,66,68],{"class":67},"srH4v"," \\\n",[33,70,72,75,78],{"class":35,"line":71},2,[33,73,74],{"class":43},"  -H",[33,76,77],{"class":47}," 'content-type: application\u002Fjson'",[33,79,68],{"class":67},[33,81,83,86],{"class":35,"line":82},3,[33,84,85],{"class":43},"  -d",[33,87,88],{"class":47}," '{\"totalShards\": 30, \"minShards\": 10}'\n",[11,90,91],{},[92,93,94],"strong",{},"Request body",[96,97,98,117],"table",{},[99,100,101],"thead",{},[102,103,104,108,111,114],"tr",{},[105,106,107],"th",{},"Field",[105,109,110],{},"Type",[105,112,113],{},"Default",[105,115,116],{},"Description",[118,119,120,139],"tbody",{},[102,121,122,128,131,136],{},[123,124,125],"td",{},[14,126,127],{},"totalShards",[123,129,130],{},"integer",[123,132,133],{},[14,134,135],{},"30",[123,137,138],{},"How many providers you want, one shard each.",[102,140,141,146,148,153],{},[123,142,143],{},[14,144,145],{},"minShards",[123,147,130],{},[123,149,150],{},[14,151,152],{},"10",[123,154,155],{},"How many shards must survive to reconstruct.",[11,157,158],{},"Both fields may be omitted; the defaults are the 10-of-30 geometry.",[11,160,161,164,165],{},[92,162,163],{},"Response"," — ",[14,166,167],{},"200 OK",[24,169,173],{"className":170,"code":171,"language":172,"meta":29,"style":29},"language-json shiki shiki-themes github-dark-default github-dark-default","{\n  \"hosts\": [\n    {\n      \"publicKey\": \"ed25519:9f3c1a4b...\",\n      \"address\": \"provider-1.example:9984\",\n      \"accountToken\": \"{\\\"hostKey\\\":\\\"ed25519:9f3c1a4b…\\\",\\\"account\\\":\\\"…\\\",\\\"validUntil\\\":1775212800,\\\"signature\\\":\\\"…\\\"}\",\n      \"contractID\": \"a1b2c3d4...\"\n    }\n  ]\n}\n","json",[14,174,175,180,189,194,209,222,302,313,319,325],{"__ignoreMap":29},[33,176,177],{"class":35,"line":36},[33,178,179],{"class":54},"{\n",[33,181,182,186],{"class":35,"line":71},[33,183,185],{"class":184},"sV7Mv","  \"hosts\"",[33,187,188],{"class":54},": [\n",[33,190,191],{"class":35,"line":82},[33,192,193],{"class":54},"    {\n",[33,195,197,200,203,206],{"class":35,"line":196},4,[33,198,199],{"class":184},"      \"publicKey\"",[33,201,202],{"class":54},": ",[33,204,205],{"class":47},"\"ed25519:9f3c1a4b...\"",[33,207,208],{"class":54},",\n",[33,210,212,215,217,220],{"class":35,"line":211},5,[33,213,214],{"class":184},"      \"address\"",[33,216,202],{"class":54},[33,218,219],{"class":47},"\"provider-1.example:9984\"",[33,221,208],{"class":54},[33,223,225,228,230,233,236,239,241,244,246,249,251,254,256,259,261,263,265,268,270,272,274,277,279,282,284,287,289,291,293,295,297,300],{"class":35,"line":224},6,[33,226,227],{"class":184},"      \"accountToken\"",[33,229,202],{"class":54},[33,231,232],{"class":47},"\"{",[33,234,235],{"class":67},"\\\"",[33,237,238],{"class":47},"hostKey",[33,240,235],{"class":67},[33,242,243],{"class":47},":",[33,245,235],{"class":67},[33,247,248],{"class":47},"ed25519:9f3c1a4b…",[33,250,235],{"class":67},[33,252,253],{"class":47},",",[33,255,235],{"class":67},[33,257,258],{"class":47},"account",[33,260,235],{"class":67},[33,262,243],{"class":47},[33,264,235],{"class":67},[33,266,267],{"class":47},"…",[33,269,235],{"class":67},[33,271,253],{"class":47},[33,273,235],{"class":67},[33,275,276],{"class":47},"validUntil",[33,278,235],{"class":67},[33,280,281],{"class":47},":1775212800,",[33,283,235],{"class":67},[33,285,286],{"class":47},"signature",[33,288,235],{"class":67},[33,290,243],{"class":47},[33,292,235],{"class":67},[33,294,267],{"class":47},[33,296,235],{"class":67},[33,298,299],{"class":47},"}\"",[33,301,208],{"class":54},[33,303,305,308,310],{"class":35,"line":304},7,[33,306,307],{"class":184},"      \"contractID\"",[33,309,202],{"class":54},[33,311,312],{"class":47},"\"a1b2c3d4...\"\n",[33,314,316],{"class":35,"line":315},8,[33,317,318],{"class":54},"    }\n",[33,320,322],{"class":35,"line":321},9,[33,323,324],{"class":54},"  ]\n",[33,326,328],{"class":35,"line":327},10,[33,329,330],{"class":54},"}\n",[96,332,333,341],{},[99,334,335],{},[102,336,337,339],{},[105,338,107],{},[105,340,116],{},[118,342,343,361,374,384],{},[102,344,345,350],{},[123,346,347],{},[14,348,349],{},"publicKey",[123,351,352,353,356,357,360],{},"The provider's identity. ",[14,354,355],{},"ed25519:"," followed by 64 hex characters. Record this in the slab's ",[14,358,359],{},"sectors[].host",".",[102,362,363,368],{},[123,364,365],{},[14,366,367],{},"address",[123,369,370,371,360],{},"Network address to connect to, ",[14,372,373],{},"host:port",[102,375,376,381],{},[123,377,378],{},[14,379,380],{},"accountToken",[123,382,383],{},"An opaque, time-limited authorisation for your writes to this provider. Pass it to the transfer protocol unmodified.",[102,385,386,391],{},[123,387,388],{},[14,389,390],{},"contractID",[123,392,393,394,360],{},"The storage contract the shard is written under. Record this in ",[14,395,396],{},"sectors[].contractID",[11,398,399,400,402,403,406],{},"The response contains exactly ",[14,401,127],{}," entries, each a ",[92,404,405],{},"different"," provider. Provider\nuniqueness within a slab is enforced here and again when the slab is registered, so a slab can never\nend up with two shards in one place.",[19,408,410],{"id":409},"geometry-constraints","Geometry constraints",[11,412,413,416],{},[14,414,415],{},"totalShards \u002F minShards"," is the redundancy factor, and it is validated:",[96,418,419,429],{},[99,420,421],{},[102,422,423,426],{},[105,424,425],{},"Rule",[105,427,428],{},"Value",[118,430,431,441,451],{},[102,432,433,436],{},[123,434,435],{},"Minimum redundancy",[123,437,438],{},[14,439,440],{},"1.5×",[102,442,443,446],{},[123,444,445],{},"Maximum redundancy",[123,447,448],{},[14,449,450],{},"4.0×",[102,452,453,457],{},[123,454,455],{},[14,456,145],{},[123,458,459,460],{},"must be ≤ ",[14,461,127],{},[96,463,464,480],{},[99,465,466],{},[102,467,468,471,474,477],{},[105,469,470],{},"Geometry",[105,472,473],{},"Redundancy",[105,475,476],{},"Tolerates",[105,478,479],{},"Accepted",[118,481,482,496,510,522,536],{},[102,483,484,487,490,493],{},[123,485,486],{},"10-of-30",[123,488,489],{},"3.0×",[123,491,492],{},"20 losses",[123,494,495],{},"yes — the default",[102,497,498,501,504,507],{},[123,499,500],{},"10-of-20",[123,502,503],{},"2.0×",[123,505,506],{},"10 losses",[123,508,509],{},"yes",[102,511,512,515,517,520],{},[123,513,514],{},"6-of-12",[123,516,503],{},[123,518,519],{},"6 losses",[123,521,509],{},[102,523,524,527,530,533],{},[123,525,526],{},"10-of-14",[123,528,529],{},"1.4×",[123,531,532],{},"4 losses",[123,534,535],{},"no — below 1.5×",[102,537,538,541,544,547],{},[123,539,540],{},"4-of-20",[123,542,543],{},"5.0×",[123,545,546],{},"16 losses",[123,548,549],{},"no — above 4.0×",[551,552,555],"app-callout",{"title":553,"tone":554},"Why there is a maximum","note",[11,556,557],{},"The lower bound protects durability. The upper bound exists because past a point you are paying for\nstorage that buys almost nothing: going from 1.5× to 4.0× multiplies your cost by 2.7 for a\nreduction in an already-small failure probability. If you have a workload that genuinely justifies\nmore, the answer is a second independent copy, not a wider stripe.",[19,559,561],{"id":560},"choosing-a-geometry","Choosing a geometry",[11,563,564,565,567,568,570,571,573],{},"Widen ",[14,566,127],{}," while holding ",[14,569,145],{}," if you want more failure tolerance for the same\nreconstruction threshold. Widening ",[14,572,145],{}," too makes each shard smaller and each read touch more\nproviders, which usually costs you latency for no durability gain.",[11,575,576],{},"The default is the right answer for almost everything. Deviate when you can state why.",[19,578,580],{"id":579},"errors","Errors",[96,582,583,596],{},[99,584,585],{},[102,586,587,590,593],{},[105,588,589],{},"Status",[105,591,592],{},"Body",[105,594,595],{},"Cause",[118,597,598,613,627,641,657,672,690,705,719],{},[102,599,600,605,610],{},[123,601,602],{},[14,603,604],{},"400",[123,606,607],{},[14,608,609],{},"{\"error\": \"invalid request body: ...\"}",[123,611,612],{},"Malformed JSON.",[102,614,615,619,624],{},[123,616,617],{},[14,618,604],{},[123,620,621],{},[14,622,623],{},"{\"error\": \"minShards must be \u003C= totalShards\"}",[123,625,626],{},"Self-explanatory.",[102,628,629,633,638],{},[123,630,631],{},[14,632,604],{},[123,634,635],{},[14,636,637],{},"{\"error\": \"redundancy 1.400 \u003C 1.5\"}",[123,639,640],{},"Below the redundancy floor.",[102,642,643,648,654],{},[123,644,645],{},[14,646,647],{},"401",[123,649,650],{},[651,652,653],"em",{},"plain text",[123,655,656],{},"Signature or credential problem.",[102,658,659,664,669],{},[123,660,661],{},[14,662,663],{},"402",[123,665,666],{},[14,667,668],{},"{\"error\": \"storage cap exceeded\", \"capBytes\": …, \"incomingBytes\": …}",[123,670,671],{},"The write would exceed your storage cap.",[102,673,674,679,684],{},[123,675,676],{},[14,677,678],{},"405",[123,680,681],{},[14,682,683],{},"method not allowed",[123,685,686,687,360],{},"Not a ",[14,688,689],{},"POST",[102,691,692,697,702],{},[123,693,694],{},[14,695,696],{},"503",[123,698,699],{},[14,700,701],{},"{\"error\": \"no contracted hosts available\"}",[123,703,704],{},"No provider pool currently available. Retry with backoff.",[102,706,707,711,716],{},[123,708,709],{},[14,710,696],{},[123,712,713],{},[14,714,715],{},"{\"error\": \"contracts manager not configured\"}",[123,717,718],{},"Placement is unavailable on this deployment.",[102,720,721,725,730],{},[123,722,723],{},[14,724,696],{},[123,726,727],{},[14,728,729],{},"{\"error\": \"no hosts with valid tokens available\"}",[123,731,732],{},"Providers were found but tokens could not be derived. Retry.",[551,734,737],{"title":735,"tone":736},"`503` is transient — treat it as such","warn",[11,738,739,740,742],{},"Provider availability fluctuates. A ",[14,741,696],{}," from this endpoint means try again shortly, not that your\nrequest was wrong. Use exponential backoff with jitter, and do not fail a user-facing upload on the\nfirst one.",[19,744,746],{"id":745},"provider-failures-mid-upload","Provider failures mid-upload",[11,748,749],{},"Some shard writes will fail. This is normal, not exceptional, and your client should treat it as a\nroutine branch rather than an error path:",[751,752,753,757,763,766],"ol",{},[754,755,756],"li",{},"Attempt the write to the assigned provider.",[754,758,759,760,762],{},"On failure, do not retry indefinitely — call ",[14,761,16],{}," again and take a provider you have\nnot used in this slab.",[754,764,765],{},"Place the shard there and continue.",[754,767,768,769,771],{},"Register the slab once you have ",[14,770,127],{}," successful placements.",[11,773,774,775,777],{},"Which specific providers hold your shards does not matter. That there are ",[14,776,127],{}," of them, all\ndistinct, does.",[19,779,781],{"id":780},"token-lifetime","Token lifetime",[11,783,784,786],{},[14,785,380],{}," is time-limited. For a long upload, request placement in batches close to when you\nwill use it rather than fetching all tokens up front and working through them slowly. If a token\nexpires mid-upload, re-request placement for the remaining shards.",[19,788,790],{"id":789},"get-hosts","GET \u002Fhosts",[11,792,793,794,796],{},"Lists providers currently considered good for upload. Informational — ",[14,795,16],{}," already\nselects for you, and does it better, because it also accounts for contract state and fill level.",[24,798,800],{"className":26,"code":799,"language":28,"meta":29,"style":29},"curl \"$TESSERA_API\u002Fhosts?$AUTH\"\n",[14,801,802],{"__ignoreMap":29},[33,803,804,806,808,810,813,815],{"class":35,"line":36},[33,805,40],{"class":39},[33,807,51],{"class":47},[33,809,55],{"class":54},[33,811,812],{"class":47},"\u002Fhosts?",[33,814,61],{"class":54},[33,816,817],{"class":47},"\"\n",[24,819,821],{"className":170,"code":820,"language":172,"meta":29,"style":29},"[\n  {\n    \"publicKey\": \"ed25519:9f3c1a4b...\",\n    \"addresses\": [\"provider-1.example:9984\"],\n    \"countryCode\": \"\",\n    \"latitude\": 0,\n    \"longitude\": 0,\n    \"goodForUpload\": true\n  }\n]\n",[14,822,823,828,833,844,857,869,881,892,902,907],{"__ignoreMap":29},[33,824,825],{"class":35,"line":36},[33,826,827],{"class":54},"[\n",[33,829,830],{"class":35,"line":71},[33,831,832],{"class":54},"  {\n",[33,834,835,838,840,842],{"class":35,"line":82},[33,836,837],{"class":184},"    \"publicKey\"",[33,839,202],{"class":54},[33,841,205],{"class":47},[33,843,208],{"class":54},[33,845,846,849,852,854],{"class":35,"line":196},[33,847,848],{"class":184},"    \"addresses\"",[33,850,851],{"class":54},": [",[33,853,219],{"class":47},[33,855,856],{"class":54},"],\n",[33,858,859,862,864,867],{"class":35,"line":211},[33,860,861],{"class":184},"    \"countryCode\"",[33,863,202],{"class":54},[33,865,866],{"class":47},"\"\"",[33,868,208],{"class":54},[33,870,871,874,876,879],{"class":35,"line":224},[33,872,873],{"class":184},"    \"latitude\"",[33,875,202],{"class":54},[33,877,878],{"class":43},"0",[33,880,208],{"class":54},[33,882,883,886,888,890],{"class":35,"line":304},[33,884,885],{"class":184},"    \"longitude\"",[33,887,202],{"class":54},[33,889,878],{"class":43},[33,891,208],{"class":54},[33,893,894,897,899],{"class":35,"line":315},[33,895,896],{"class":184},"    \"goodForUpload\"",[33,898,202],{"class":54},[33,900,901],{"class":43},"true\n",[33,903,904],{"class":35,"line":321},[33,905,906],{"class":54},"  }\n",[33,908,909],{"class":35,"line":327},[33,910,911],{"class":54},"]\n",[11,913,914,915,360],{},"Always an array, never ",[14,916,917],{},"null",[551,919,921],{"title":920,"tone":554},"Geography fields are not populated",[11,922,923,926,927,930,931,934],{},[14,924,925],{},"countryCode",", ",[14,928,929],{},"latitude",", and ",[14,932,933],{},"longitude"," are present in the response shape but are currently\nreturned empty or zero — geo-location of providers is not yet wired up. Do not build jurisdiction\nlogic on these fields. If you need jurisdiction constraints, that is not offered on the public site today.",[936,937,938],"style",{},"html pre.shiki code .sAxfE, html code.shiki .sAxfE{--shiki-default:#FFA657;--shiki-dark:#FFA657}html pre.shiki code .sEQcL, html code.shiki .sEQcL{--shiki-default:#79C0FF;--shiki-dark:#79C0FF}html pre.shiki code .skZ57, html code.shiki .skZ57{--shiki-default:#A5D6FF;--shiki-dark:#A5D6FF}html pre.shiki code .sb7RM, html code.shiki .sb7RM{--shiki-default:#E6EDF3;--shiki-dark:#E6EDF3}html pre.shiki code .srH4v, html code.shiki .srH4v{--shiki-default:#FF7B72;--shiki-dark:#FF7B72}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sV7Mv, html code.shiki .sV7Mv{--shiki-default:#7EE787;--shiki-dark:#7EE787}",{"title":29,"searchDepth":82,"depth":82,"links":940},[941,942,943,944,945,946,947],{"id":21,"depth":71,"text":22},{"id":409,"depth":71,"text":410},{"id":560,"depth":71,"text":561},{"id":579,"depth":71,"text":580},{"id":745,"depth":71,"text":746},{"id":780,"depth":71,"text":781},{"id":789,"depth":71,"text":790},"md",{},true,"\u002Fdocs\u002Fapi\u002Fplacement","API reference",{"title":5,"description":29},"docs\u002Fapi\u002Fplacement","t0O9cZaR3dIcZAysxmJLrgZfCsuYNMwMSvJ9zlMfo_Y",[957,961,966,969,972,973,976,979,982,986,989,992,995,1000],{"path":958,"title":959,"description":29,"section":960,"order":71,"badge":6},"\u002Fdocs\u002Faccounts","Accounts & billing","Guides",{"path":962,"title":963,"description":964,"section":965,"order":36,"badge":6},"\u002Fdocs\u002Fapi-quickstart","API quickstart","Create a billing account over HTTP, then register a storage key with the SDK.","API",{"path":967,"title":968,"description":29,"section":952,"order":211,"badge":6},"\u002Fdocs\u002Fapi\u002Faccount","Account",{"path":970,"title":971,"description":29,"section":952,"order":196,"badge":6},"\u002Fdocs\u002Fapi\u002Fobjects","Objects",{"path":951,"title":5,"description":29,"section":952,"order":71,"badge":6},{"path":974,"title":975,"description":29,"section":952,"order":36,"badge":6},"\u002Fdocs\u002Fapi\u002Fprovisioning","Credentials",{"path":977,"title":978,"description":29,"section":952,"order":82,"badge":6},"\u002Fdocs\u002Fapi\u002Fslabs","Slabs",{"path":980,"title":981,"description":29,"section":960,"order":82,"badge":6},"\u002Fdocs\u002Fauthentication","Authentication",{"path":983,"title":984,"description":29,"section":985,"order":71,"badge":6},"\u002Fdocs\u002Fconcepts","Concepts & data model","Introduction",{"path":987,"title":580,"description":29,"section":988,"order":36,"badge":6},"\u002Fdocs\u002Ferrors","Reference",{"path":990,"title":991,"description":29,"section":965,"order":36,"badge":6},"\u002Fdocs","Overview",{"path":993,"title":994,"description":29,"section":988,"order":71,"badge":6},"\u002Fdocs\u002Flimits","Limits & quotas",{"path":996,"title":997,"description":998,"section":999,"order":36,"badge":6},"\u002Fdocs\u002Fquickstart","CLI quickstart","Install the CLI, create an account, store one file, and read it back.","CLI",{"path":1001,"title":1002,"description":29,"section":960,"order":196,"badge":6},"\u002Fdocs\u002Frecovery","Recovery without Tessera",1794060205204]