[{"data":1,"prerenderedAt":1004},["ShallowReactive",2],{"docs:\u002Fdocs\u002Fapi\u002Fplacement":3,"docs:nav":956},{"id":4,"title":5,"badge":6,"body":7,"description":947,"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":938},"minimark",[10,18,23,89,95,156,159,168,331,397,407,411,417,462,549,557,561,573,576,580,732,742,746,749,771,777,781,786,790,796,817,911,917,934],[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\": 15, \"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\": 15, \"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],{},"15",[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-15 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,495,509,521,535],{},[102,483,484,487,489,492],{},[123,485,486],{},"10-of-15",[123,488,440],{},[123,490,491],{},"5 losses",[123,493,494],{},"yes — the default",[102,496,497,500,503,506],{},[123,498,499],{},"10-of-20",[123,501,502],{},"2.0×",[123,504,505],{},"10 losses",[123,507,508],{},"yes",[102,510,511,514,516,519],{},[123,512,513],{},"6-of-12",[123,515,502],{},[123,517,518],{},"6 losses",[123,520,508],{},[102,522,523,526,529,532],{},[123,524,525],{},"10-of-14",[123,527,528],{},"1.4×",[123,530,531],{},"4 losses",[123,533,534],{},"no — below 1.5×",[102,536,537,540,543,546],{},[123,538,539],{},"4-of-20",[123,541,542],{},"5.0×",[123,544,545],{},"16 losses",[123,547,548],{},"no — above 4.0×",[550,551,554],"app-callout",{"title":552,"tone":553},"Why there is a maximum","note",[11,555,556],{},"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,558,560],{"id":559},"choosing-a-geometry","Choosing a geometry",[11,562,563,564,566,567,569,570,572],{},"Widen ",[14,565,127],{}," while holding ",[14,568,145],{}," if you want more failure tolerance for the same\nreconstruction threshold. Widening ",[14,571,145],{}," too makes each shard smaller and each read touch more\nproviders, which usually costs you latency for no durability gain.",[11,574,575],{},"The default is the right answer for almost everything. Deviate when you can state why.",[19,577,579],{"id":578},"errors","Errors",[96,581,582,595],{},[99,583,584],{},[102,585,586,589,592],{},[105,587,588],{},"Status",[105,590,591],{},"Body",[105,593,594],{},"Cause",[118,596,597,612,626,640,656,671,689,704,718],{},[102,598,599,604,609],{},[123,600,601],{},[14,602,603],{},"400",[123,605,606],{},[14,607,608],{},"{\"error\": \"invalid request body: ...\"}",[123,610,611],{},"Malformed JSON.",[102,613,614,618,623],{},[123,615,616],{},[14,617,603],{},[123,619,620],{},[14,621,622],{},"{\"error\": \"minShards must be \u003C= totalShards\"}",[123,624,625],{},"Self-explanatory.",[102,627,628,632,637],{},[123,629,630],{},[14,631,603],{},[123,633,634],{},[14,635,636],{},"{\"error\": \"redundancy 1.400 \u003C 1.5\"}",[123,638,639],{},"Below the redundancy floor.",[102,641,642,647,653],{},[123,643,644],{},[14,645,646],{},"401",[123,648,649],{},[650,651,652],"em",{},"plain text",[123,654,655],{},"Signature or credential problem.",[102,657,658,663,668],{},[123,659,660],{},[14,661,662],{},"402",[123,664,665],{},[14,666,667],{},"{\"error\": \"storage cap exceeded\", \"capBytes\": …, \"incomingBytes\": …}",[123,669,670],{},"The write would exceed your storage cap.",[102,672,673,678,683],{},[123,674,675],{},[14,676,677],{},"405",[123,679,680],{},[14,681,682],{},"method not allowed",[123,684,685,686,360],{},"Not a ",[14,687,688],{},"POST",[102,690,691,696,701],{},[123,692,693],{},[14,694,695],{},"503",[123,697,698],{},[14,699,700],{},"{\"error\": \"no contracted hosts available\"}",[123,702,703],{},"No provider pool currently available. Retry with backoff.",[102,705,706,710,715],{},[123,707,708],{},[14,709,695],{},[123,711,712],{},[14,713,714],{},"{\"error\": \"contracts manager not configured\"}",[123,716,717],{},"Placement is unavailable on this deployment.",[102,719,720,724,729],{},[123,721,722],{},[14,723,695],{},[123,725,726],{},[14,727,728],{},"{\"error\": \"no hosts with valid tokens available\"}",[123,730,731],{},"Providers were found but tokens could not be derived. Retry.",[550,733,736],{"title":734,"tone":735},"`503` is transient — treat it as such","warn",[11,737,738,739,741],{},"Provider availability fluctuates. A ",[14,740,695],{}," 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,743,745],{"id":744},"provider-failures-mid-upload","Provider failures mid-upload",[11,747,748],{},"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:",[750,751,752,756,762,765],"ol",{},[753,754,755],"li",{},"Attempt the write to the assigned provider.",[753,757,758,759,761],{},"On failure, do not retry indefinitely — call ",[14,760,16],{}," again and take a provider you have\nnot used in this slab.",[753,763,764],{},"Place the shard there and continue.",[753,766,767,768,770],{},"Register the slab once you have ",[14,769,127],{}," successful placements.",[11,772,773,774,776],{},"Which specific providers hold your shards does not matter. That there are ",[14,775,127],{}," of them, all\ndistinct, does.",[19,778,780],{"id":779},"token-lifetime","Token lifetime",[11,782,783,785],{},[14,784,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,787,789],{"id":788},"get-hosts","GET \u002Fhosts",[11,791,792,793,795],{},"Lists providers currently considered good for upload. Informational — ",[14,794,16],{}," already\nselects for you, and does it better, because it also accounts for contract state and fill level.",[24,797,799],{"className":26,"code":798,"language":28,"meta":29,"style":29},"curl \"$TESSERA_API\u002Fhosts?$AUTH\"\n",[14,800,801],{"__ignoreMap":29},[33,802,803,805,807,809,812,814],{"class":35,"line":36},[33,804,40],{"class":39},[33,806,51],{"class":47},[33,808,55],{"class":54},[33,810,811],{"class":47},"\u002Fhosts?",[33,813,61],{"class":54},[33,815,816],{"class":47},"\"\n",[24,818,820],{"className":170,"code":819,"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,821,822,827,832,843,856,868,880,891,901,906],{"__ignoreMap":29},[33,823,824],{"class":35,"line":36},[33,825,826],{"class":54},"[\n",[33,828,829],{"class":35,"line":71},[33,830,831],{"class":54},"  {\n",[33,833,834,837,839,841],{"class":35,"line":82},[33,835,836],{"class":184},"    \"publicKey\"",[33,838,202],{"class":54},[33,840,205],{"class":47},[33,842,208],{"class":54},[33,844,845,848,851,853],{"class":35,"line":196},[33,846,847],{"class":184},"    \"addresses\"",[33,849,850],{"class":54},": [",[33,852,219],{"class":47},[33,854,855],{"class":54},"],\n",[33,857,858,861,863,866],{"class":35,"line":211},[33,859,860],{"class":184},"    \"countryCode\"",[33,862,202],{"class":54},[33,864,865],{"class":47},"\"\"",[33,867,208],{"class":54},[33,869,870,873,875,878],{"class":35,"line":224},[33,871,872],{"class":184},"    \"latitude\"",[33,874,202],{"class":54},[33,876,877],{"class":43},"0",[33,879,208],{"class":54},[33,881,882,885,887,889],{"class":35,"line":304},[33,883,884],{"class":184},"    \"longitude\"",[33,886,202],{"class":54},[33,888,877],{"class":43},[33,890,208],{"class":54},[33,892,893,896,898],{"class":35,"line":315},[33,894,895],{"class":184},"    \"goodForUpload\"",[33,897,202],{"class":54},[33,899,900],{"class":43},"true\n",[33,902,903],{"class":35,"line":321},[33,904,905],{"class":54},"  }\n",[33,907,908],{"class":35,"line":327},[33,909,910],{"class":54},"]\n",[11,912,913,914,360],{},"Always an array, never ",[14,915,916],{},"null",[550,918,920],{"title":919,"tone":553},"Geography fields are not populated",[11,921,922,925,926,929,930,933],{},[14,923,924],{},"countryCode",", ",[14,927,928],{},"latitude",", and ",[14,931,932],{},"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 an Enterprise configuration\napplied at selection time.",[935,936,937],"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":939},[940,941,942,943,944,945,946],{"id":21,"depth":71,"text":22},{"id":409,"depth":71,"text":410},{"id":559,"depth":71,"text":560},{"id":578,"depth":71,"text":579},{"id":744,"depth":71,"text":745},{"id":779,"depth":71,"text":780},{"id":788,"depth":71,"text":789},"POST \u002Fprepare-write — get the providers, contracts, and access tokens for writing a slab's shards.","md",{},true,"\u002Fdocs\u002Fapi\u002Fplacement","API reference",{"title":5,"description":947},"docs\u002Fapi\u002Fplacement","UDjuZuZmzUr8tRTpEYowJ4QqlMu_2NPJG7REvibHLu8",[957,961,965,966,970,974,979,984,988,992,996,1000],{"path":958,"title":959,"description":960,"section":952,"order":211,"badge":6},"\u002Fdocs\u002Fapi\u002Faccount","Account","GET \u002Faccount — stored, read, and written byte counters for your credential.",{"path":962,"title":963,"description":964,"section":952,"order":196,"badge":6},"\u002Fdocs\u002Fapi\u002Fobjects","Objects","Register, read, list, and delete objects — ordered lists of slab segments with encrypted keys and opaque metadata.",{"path":951,"title":5,"description":947,"section":952,"order":71,"badge":6},{"path":967,"title":968,"description":969,"section":952,"order":36,"badge":6},"\u002Fdocs\u002Fapi\u002Fprovisioning","Credentials","Provision, verify, and revoke the ed25519 credential that is both your API identity and your account.",{"path":971,"title":972,"description":973,"section":952,"order":82,"badge":6},"\u002Fdocs\u002Fapi\u002Fslabs","Slabs","Register, read, list, unpin, and prune erasure-coded slabs — the layer that records which provider holds which shard.",{"path":975,"title":976,"description":977,"section":978,"order":71,"badge":6},"\u002Fdocs\u002Fauthentication","Authentication","Every request is signed with ed25519 over a blake2b hash of the method, host, path, expiry, and body. Here is the exact construction, with working code.","Guides",{"path":980,"title":981,"description":982,"section":983,"order":71,"badge":6},"\u002Fdocs\u002Fconcepts","Concepts & data model","Sectors, shards, slabs, objects, and accounts — what each one is, why the model has no filenames, and what that means for your integration.","Introduction",{"path":985,"title":579,"description":986,"section":987,"order":36,"badge":6},"\u002Fdocs\u002Ferrors","Status codes, the two different error body formats, and the one case where a failure arrives with a 200.","Reference",{"path":989,"title":990,"description":991,"section":983,"order":36,"badge":6},"\u002Fdocs","Overview","Tessera is an HTTP API for storing encrypted, erasure-coded objects across independent storage providers. This is the reference for it.",{"path":993,"title":994,"description":995,"section":987,"order":71,"badge":6},"\u002Fdocs\u002Flimits","Limits & quotas","Rate limits, storage caps, geometry constraints, and the size and encoding limits that apply to every request.",{"path":997,"title":998,"description":999,"section":978,"order":36,"badge":6},"\u002Fdocs\u002Fquickstart","Quickstart","Provision a credential, upload an object across 15 providers, and read it back. Fifteen minutes, one file of code.",{"path":1001,"title":1002,"description":1003,"section":978,"order":82,"badge":6},"\u002Fdocs\u002Frecovery","Recovery without Tessera","How to retrieve your data if Tessera is unavailable, unwilling, or permanently gone — and what you need to keep on hand for that to work.",1786190914174]