Buckets:
| <meta charset="utf-8" /><meta name="hf:doc:metadata" content="{"title":"CAS API Documentation","local":"cas-api-documentation","sections":[{"title":"Authentication","local":"authentication","sections":[],"depth":2},{"title":"Converting Hashes to Strings","local":"converting-hashes-to-strings","sections":[{"title":"Procedure","local":"procedure","sections":[],"depth":3},{"title":"Example","local":"example","sections":[],"depth":3}],"depth":2},{"title":"Endpoints","local":"endpoints","sections":[{"title":"1. Get File Reconstruction","local":"1-get-file-reconstruction","sections":[],"depth":3},{"title":"Example File Reconstruction Response Body","local":"example-file-reconstruction-response-body","sections":[],"depth":3},{"title":"2. Query Chunk Deduplication (Global Deduplication)","local":"2-query-chunk-deduplication-global-deduplication","sections":[{"title":"Example Shard Response Body","local":"example-shard-response-body","sections":[],"depth":4}],"depth":3},{"title":"3. Upload Xorb","local":"3-upload-xorb","sections":[{"title":"Example Xorb Request Body","local":"example-xorb-request-body","sections":[],"depth":4}],"depth":3},{"title":"4. Upload Shard","local":"4-upload-shard","sections":[{"title":"Example Shard Request Body","local":"example-shard-request-body","sections":[],"depth":4}],"depth":3},{"title":"5. Streaming Shard Upload","local":"5-streaming-shard-upload","sections":[],"depth":3},{"title":"6. Batch File Reconstruction","local":"6-batch-file-reconstruction","sections":[],"depth":3},{"title":"7. Head Xorb","local":"7-head-xorb","sections":[],"depth":3},{"title":"8. Head File","local":"8-head-file","sections":[],"depth":3},{"title":"9. Get File Chunk Hashes","local":"9-get-file-chunk-hashes","sections":[],"depth":3},{"title":"10. Get File Reconstruction (v1)","local":"10-get-file-reconstruction-v1","sections":[],"depth":3}],"depth":2},{"title":"Error Cases","local":"error-cases","sections":[{"title":"Non-Retryable Errors","local":"non-retryable-errors","sections":[],"depth":3},{"title":"Retryable Errors","local":"retryable-errors","sections":[],"depth":3}],"depth":2}],"depth":1}"/> | |
| <link href="/docs/xet/pr_2742/en/_app/immutable/entry/start.Av_YqhRg.js" rel="modulepreload"> | |
| <link href="/docs/xet/pr_2742/en/_app/immutable/chunks/Chn541Dq.js" rel="modulepreload"> | |
| <link href="/docs/xet/pr_2742/en/_app/immutable/chunks/wHAYn8DZ.js" rel="modulepreload"> | |
| <link href="/docs/xet/pr_2742/en/_app/immutable/entry/app.DOxgnXbz.js" rel="modulepreload"> | |
| <link href="/docs/xet/pr_2742/en/_app/immutable/chunks/DjTMmYhz.js" rel="modulepreload"> | |
| <link href="/docs/xet/pr_2742/en/_app/immutable/chunks/ZJUpSAix.js" rel="modulepreload"> | |
| <link href="/docs/xet/pr_2742/en/_app/immutable/chunks/DsnmJJEf.js" rel="modulepreload"> | |
| <link href="/docs/xet/pr_2742/en/_app/immutable/chunks/C3-3EOzc.js" rel="modulepreload"> | |
| <link href="/docs/xet/pr_2742/en/_app/immutable/nodes/0.BXcJgKM_.js" rel="modulepreload"> | |
| <link href="/docs/xet/pr_2742/en/_app/immutable/nodes/2.Dv0vxtJO.js" rel="modulepreload"> | |
| <link href="/docs/xet/pr_2742/en/_app/immutable/chunks/CiFFqx6A.js" rel="modulepreload"> | |
| <!--ztmkmn--><meta name="hf:doc:metadata" content="{"title":"CAS API Documentation","local":"cas-api-documentation","sections":[{"title":"Authentication","local":"authentication","sections":[],"depth":2},{"title":"Converting Hashes to Strings","local":"converting-hashes-to-strings","sections":[{"title":"Procedure","local":"procedure","sections":[],"depth":3},{"title":"Example","local":"example","sections":[],"depth":3}],"depth":2},{"title":"Endpoints","local":"endpoints","sections":[{"title":"1. Get File Reconstruction","local":"1-get-file-reconstruction","sections":[],"depth":3},{"title":"Example File Reconstruction Response Body","local":"example-file-reconstruction-response-body","sections":[],"depth":3},{"title":"2. Query Chunk Deduplication (Global Deduplication)","local":"2-query-chunk-deduplication-global-deduplication","sections":[{"title":"Example Shard Response Body","local":"example-shard-response-body","sections":[],"depth":4}],"depth":3},{"title":"3. Upload Xorb","local":"3-upload-xorb","sections":[{"title":"Example Xorb Request Body","local":"example-xorb-request-body","sections":[],"depth":4}],"depth":3},{"title":"4. Upload Shard","local":"4-upload-shard","sections":[{"title":"Example Shard Request Body","local":"example-shard-request-body","sections":[],"depth":4}],"depth":3},{"title":"5. Streaming Shard Upload","local":"5-streaming-shard-upload","sections":[],"depth":3},{"title":"6. Batch File Reconstruction","local":"6-batch-file-reconstruction","sections":[],"depth":3},{"title":"7. Head Xorb","local":"7-head-xorb","sections":[],"depth":3},{"title":"8. Head File","local":"8-head-file","sections":[],"depth":3},{"title":"9. Get File Chunk Hashes","local":"9-get-file-chunk-hashes","sections":[],"depth":3},{"title":"10. Get File Reconstruction (v1)","local":"10-get-file-reconstruction-v1","sections":[],"depth":3}],"depth":2},{"title":"Error Cases","local":"error-cases","sections":[{"title":"Non-Retryable Errors","local":"non-retryable-errors","sections":[],"depth":3},{"title":"Retryable Errors","local":"retryable-errors","sections":[],"depth":3}],"depth":2}],"depth":1}"/><!----> | |
| <link href="/docs/xet/pr_2742/en/_app/immutable/assets/0.tn0RQdqM.css" rel="modulepreload"> <!--[--><!--[0--><!--[--><!--[0--><!--[--><p></p> <div class="items-center shrink-0 min-w-[100px] max-sm:min-w-[50px] justify-end ml-auto flex" style="float: right; margin-left: 10px; display: inline-flex; position: relative; z-index: 10;"><div class="inline-flex rounded-md max-sm:rounded-sm"><button class="inline-flex items-center gap-1 h-7 max-sm:h-7 px-2 max-sm:px-1.5 text-sm font-medium text-gray-800 border border-r-0 rounded-l-md max-sm:rounded-l-sm border-gray-200 bg-white hover:shadow-inner dark:border-gray-850 dark:bg-gray-950 dark:text-gray-200 dark:hover:bg-gray-800" aria-live="polite"><span class="inline-flex items-center justify-center rounded-md p-0.5 max-sm:p-0 hover:text-gray-800 dark:hover:text-gray-200"><svg class="sm:size-3.5 size-3" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----></span> <span>Copy page</span></button> <button class="inline-flex items-center justify-center w-6 max-sm:w-5 h-7 max-sm:h-7 disabled:pointer-events-none text-sm text-gray-500 hover:text-gray-700 dark:hover:text-white rounded-r-md max-sm:rounded-r-sm border border-l transition border-gray-200 bg-white hover:shadow-inner dark:border-gray-850 dark:bg-gray-950 dark:text-gray-200 dark:hover:bg-gray-800" aria-haspopup="menu" aria-expanded="false" aria-label="Open copy menu"><svg class="transition-transform text-gray-400 overflow-visible sm:size-3.5 size-3 rotate-0" width="1em" height="1em" viewBox="0 0 12 7" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1 1L6 6L11 1" stroke="currentColor"></path></svg><!----></button></div> <!--[-1--><!--]--></div><!----> <!--[0--><h1 class="relative group"><a id="cas-api-documentation" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#cas-api-documentation"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>CAS API Documentation</span></h1><!--]--><!----> <p>This document describes the HTTP API endpoints used by the Content Addressable Storage (CAS) client to interact with the remote CAS server.</p> <!--[1--><h2 class="relative group"><a id="authentication" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#authentication"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Authentication</span></h2><!--]--><!----> <p>To authenticate, authorize, and obtain the API base URL, follow the instructions in <a href="./auth">Authentication</a>.</p> <!--[1--><h2 class="relative group"><a id="converting-hashes-to-strings" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#converting-hashes-to-strings"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Converting Hashes to Strings</span></h2><!--]--><!----> <p>Sometimes hashes are used in API paths as hexadecimal strings (reconstruction, xorb upload, global dedupe API).</p> <p>To convert a 32 hash to a 64 hexadecimal character string to be used as part of an API path there is a specific procedure, MUST NOT directly convert each byte.</p> <!--[2--><h3 class="relative group"><a id="procedure" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#procedure"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Procedure</span></h3><!--]--><!----> <p>For every 8 bytes in the hash (indices 0-7, 8-15, 16-23, 24-31) reverse the order of each byte in those regions then concatenate the regions back in order.</p> <p>Otherwise stated, consider each 8 byte part of a hash as a little endian 64 bit unsigned integer, then concatenate the hexadecimal representation of the 4 numbers in order (each padded with 0’s to 16 characters).</p> <blockquote class="note"><p>In all cases that a hash is represented as a string it is converted from a byte array to a string using this procedure.</p></blockquote> <!--[2--><h3 class="relative group"><a id="example" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#example"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Example</span></h3><!--]--><!----> <p>Suppose a hash value is: <code>[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31]</code></p> <p>Then before converting to a string it will first have its bytes reordered to: <code>[7, 6, 5, 4, 3, 2, 1, 0, 15, 14, 13, 12, 11, 10, 9, 8, 23, 22, 21, 20, 19, 18, 17, 16, 31, 30, 29, 28, 27, 26, 25, 24]</code></p> <p>So the string value of the provided hash [0..32] is <strong>NOT</strong> <code>000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f</code>. | |
| It is: <code>07060504030201000f0e0d0c0b0a0908171615141312111f1e1d1c1b1a1918</code>.</p> <!--[1--><h2 class="relative group"><a id="endpoints" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#endpoints"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Endpoints</span></h2><!--]--><!----> <!--[2--><h3 class="relative group"><a id="1-get-file-reconstruction" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#1-get-file-reconstruction"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>1. Get File Reconstruction</span></h3><!--]--><!----> <blockquote class="note"><p>This v2 endpoint is the recommended default. Because older CAS deployments may not serve <code>/v2/</code>, clients SHOULD fall back to the deprecated <a href="./api#10-get-file-reconstruction-v1"><code>GET /v1/reconstructions/{file_id}</code></a> on a <code>404</code> or <code>501</code>.</p></blockquote> <ul><li><p><strong>Description</strong>: Retrieves reconstruction information for a specific file. Returns URLs optimized for multi-range fetching: multiple byte ranges for the same xorb are combined into a single URL. Supports byte range via the optional <code>Range</code> header.</p></li> <li><p><strong>Path</strong>: <code>/v2/reconstructions/{file_id}</code></p></li> <li><p><strong>Method</strong>: <code>GET</code></p></li> <li><p><strong>Parameters</strong>:</p> <ul><li><code>file_id</code>: File hash in hex format (64 lowercase hexadecimal characters). | |
| See <a href="./hashing#file-hashes">file hashes</a> for computing the file hash and <a href="./api#converting-hashes-to-strings">converting hashes to strings</a>.</li></ul></li> <li><p><strong>Headers</strong>:</p> <ul><li><code>Range</code>: OPTIONAL. Format: <code>bytes={start}-{end}</code> (end is inclusive).</li> <li><code>Accept-Encoding</code>: OPTIONAL. The server supports <code>gzip</code> and <code>zstd</code> compression on the JSON response. Clients SHOULD send <code>Accept-Encoding: gzip</code> or <code>Accept-Encoding: zstd</code> to reduce reconstruction response size.</li></ul></li> <li><p><strong>Minimum Token Scope</strong>: <code>read</code></p></li> <li><p><strong>Body</strong>: None.</p></li> <li><p><strong>Response</strong>: JSON (<code>QueryReconstructionResponse</code>)</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-json "><!----><span class="hljs-punctuation">{</span> | |
| <span class="hljs-attr">"offset_into_first_range"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> | |
| <span class="hljs-attr">"terms"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>...<span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span> | |
| <span class="hljs-attr">"xorbs"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>...<span class="hljs-punctuation">}</span> | |
| <span class="hljs-punctuation">}</span><!----></pre></div><!----></li> <li><p><strong>Error Responses</strong>: See <a href="./api#error-cases">Error Cases</a></p> <ul><li><code>400 Bad Request</code>: Malformed <code>file_id</code> in the path. Fix the path before retrying.</li> <li><code>401 Unauthorized</code>: Refresh the token to continue making requests, or provide a token in the <code>Authorization</code> header.</li> <li><code>404 Not Found</code>: The file does not exist. Not retryable.</li> <li><code>416 Range Not Satisfiable</code>: The requested byte range start exceeds the end of the file. Not retryable.</li></ul></li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-txt "><!---->GET /v2/reconstructions/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef | |
| -H "Authorization: Bearer <token>" | |
| OPTIONAL: -H Range: "bytes=0-100000"<!----></pre></div><!----> <!--[2--><h3 class="relative group"><a id="example-file-reconstruction-response-body" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#example-file-reconstruction-response-body"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Example File Reconstruction Response Body</span></h3><!--]--><!----> <p>See <a href="./download-protocol#queryreconstructionresponse-structure">QueryReconstructionResponse</a> for more details in the download protocol specification.</p> <!--[2--><h3 class="relative group"><a id="2-query-chunk-deduplication-global-deduplication" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#2-query-chunk-deduplication-global-deduplication"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>2. Query Chunk Deduplication (Global Deduplication)</span></h3><!--]--><!----> <ul><li><strong>Description</strong>: Checks if a chunk exists in the CAS for deduplication purposes.</li> <li><strong>Path</strong>: <code>/v1/chunks/{prefix}/{hash}</code></li> <li><strong>Method</strong>: <code>GET</code></li> <li><strong>Parameters</strong>: <ul><li><code>prefix</code>: The only acceptable prefix for the Global Deduplication API is <code>default-merkledb</code>.</li> <li><code>hash</code>: Chunk hash in hex format (64 lowercase hexadecimal characters). | |
| See <a href="./hashing#chunk-hashes">Chunk Hashes</a> to compute the chunk hash and <a href="./api#converting-hashes-to-strings">converting hashes to strings</a>.</li></ul></li> <li><strong>Minimum Token Scope</strong>: <code>read</code></li> <li><strong>Body</strong>: None.</li> <li><strong>Response</strong>: Shard format bytes (<code>application/octet-stream</code>), deserialize as a <a href="./shard#global-deduplication">shard</a>.</li> <li><strong>Error Responses</strong>: See <a href="./api#error-cases">Error Cases</a> <ul><li><code>400 Bad Request</code>: Malformed hash in the path. Fix the path before retrying.</li> <li><code>401 Unauthorized</code>: Refresh the token to continue making requests, or provide a token in the <code>Authorization</code> header.</li> <li><code>404 Not Found</code>: Chunk not already tracked by global deduplication. Not retryable.</li></ul></li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-txt "><!---->GET /v1/chunks/default-merkledb/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef | |
| -H "Authorization: Bearer <token>"<!----></pre></div><!----> <!--[3--><h4 class="relative group"><a id="example-shard-response-body" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#example-shard-response-body"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Example Shard Response Body</span></h4><!--]--><!----> <p>An example shard response body can be found in <a href="https://huggingface.co/datasets/xet-team/xet-spec-reference-files/blob/main/Electric_Vehicle_Population_Data_20250917.csv.shard.dedupe" rel="nofollow">Xet reference files</a>.</p> <!--[2--><h3 class="relative group"><a id="3-upload-xorb" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#3-upload-xorb"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>3. Upload Xorb</span></h3><!--]--><!----> <ul><li><strong>Description</strong>: Uploads a serialized Xorb to the server; uploading real data in serialized format.</li> <li><strong>Path</strong>: <code>/v1/xorbs/{prefix}/{hash}</code></li> <li><strong>Method</strong>: <code>POST</code></li> <li><strong>Parameters</strong>: <ul><li><code>prefix</code>: The only acceptable prefix for the Xorb upload API is <code>default</code>.</li> <li><code>hash</code>: Xorb hash in hex format (64 lowercase hexadecimal characters). | |
| See <a href="./hashing#xorb-hashes">Xorb Hashes</a> to compute the hash, and <a href="./api#converting-hashes-to-strings">converting hashes to strings</a>.</li></ul></li> <li><strong>Minimum Token Scope</strong>: <code>write</code></li> <li><strong>Body</strong>: Serialized Xorb bytes (<code>application/octet-stream</code>). | |
| See <a href="./xorb">xorb format serialization</a>.</li> <li><strong>Response</strong>: JSON (<code>UploadXorbResponse</code>)</li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-json "><!----><span class="hljs-punctuation">{</span> | |
| <span class="hljs-attr">"was_inserted"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">true</span></span> | |
| <span class="hljs-punctuation">}</span><!----></pre></div><!----> <ul><li><p>Note: <code>was_inserted</code> is <code>false</code> if the Xorb already exists; this is not an error.</p></li> <li><p><strong>Error Responses</strong>: See <a href="./api#error-cases">Error Cases</a></p> <ul><li><code>400 Bad Request</code>: Malformed hash in the path, Xorb hash does not match the body, or body is incorrectly serialized.</li> <li><code>401 Unauthorized</code>: Refresh the token to continue making requests, or provide a token in the <code>Authorization</code> header.</li> <li><code>403 Forbidden</code>: Token provided but does not have a wide enough scope (for example, a <code>read</code> token was provided). Clients MUST retry with a <code>write</code> scope token.</li></ul></li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-txt "><!---->POST /v1/xorbs/default/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef | |
| -H "Authorization: Bearer <token>"<!----></pre></div><!----> <!--[3--><h4 class="relative group"><a id="example-xorb-request-body" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#example-xorb-request-body"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Example Xorb Request Body</span></h4><!--]--><!----> <p>An example xorb request body can be found in <a href="https://huggingface.co/datasets/xet-team/xet-spec-reference-files/blob/main/eea25d6ee393ccae385820daed127b96ef0ea034dfb7cf6da3a950ce334b7632.xorb" rel="nofollow">Xet reference files</a>.</p> <!--[2--><h3 class="relative group"><a id="4-upload-shard" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#4-upload-shard"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>4. Upload Shard</span></h3><!--]--><!----> <ul><li><strong>Description</strong>: Uploads a Shard to the CAS. | |
| Uploads file reconstructions and new xorb listing, serialized into the shard format; marks the files as uploaded.</li> <li><strong>Path</strong>: <code>/v1/shards</code></li> <li><strong>Method</strong>: <code>POST</code></li> <li><strong>Minimum Token Scope</strong>: <code>write</code></li> <li><strong>Body</strong>: Serialized Shard data as bytes (<code>application/octet-stream</code>). | |
| See <a href="./shard#shard-upload">Shard format guide</a>.</li> <li><strong>Response</strong>: JSON (<code>UploadShardResponse</code>)</li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-json "><!----><span class="hljs-punctuation">{</span> | |
| <span class="hljs-attr">"result"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span> | |
| <span class="hljs-punctuation">}</span><!----></pre></div><!----> <ul><li>Where <code>result</code> is: <ul><li><code>0</code>: The Shard already exists.</li> <li><code>1</code>: <code>SyncPerformed</code> — the Shard was registered.</li></ul></li></ul> <p>The value of <code>result</code> does not carry any meaning, if the upload shard API returns a <code>200 OK</code> status code, the upload was successful and the files listed are considered uploaded.</p> <ul><li><strong>Error Responses</strong>: See <a href="./api#error-cases">Error Cases</a> <ul><li><code>400 Bad Request</code>: Shard is incorrectly serialized or Shard contents failed verification. <ul><li>Can mean that a referenced Xorb doesn’t exist or the shard is too large</li></ul></li> <li><code>401 Unauthorized</code>: Refresh the token to continue making requests, or provide a token in the <code>Authorization</code> header.</li> <li><code>403 Forbidden</code>: Token provided but does not have a wide enough scope (for example, a <code>read</code> token was provided).</li></ul></li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-txt "><!---->POST /v1/shards | |
| -H "Authorization: Bearer <token>"<!----></pre></div><!----> <!--[3--><h4 class="relative group"><a id="example-shard-request-body" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#example-shard-request-body"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Example Shard Request Body</span></h4><!--]--><!----> <p>An example shard request body can be found in <a href="https://huggingface.co/datasets/xet-team/xet-spec-reference-files/blob/main/Electric_Vehicle_Population_Data_20250917.csv.shard.verification-no-footer" rel="nofollow">Xet reference files</a>.</p> <!--[2--><h3 class="relative group"><a id="5-streaming-shard-upload" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#5-streaming-shard-upload"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>5. Streaming Shard Upload</span></h3><!--]--><!----> <ul><li><strong>Description</strong>: Runs the same validation and registration as <a href="./api#4-upload-shard">Upload Shard</a>, but streams finalization progress back as newline-delimited JSON so clients can show real progress on large shards, which can take several seconds to finalize server-side.</li> <li><strong>Path</strong>: <code>/v2/shards</code></li> <li><strong>Method</strong>: <code>POST</code></li> <li><strong>Minimum Token Scope</strong>: <code>write</code></li> <li><strong>Body</strong>: Serialized Shard data as bytes (<code>application/octet-stream</code>), identical to <a href="./api#4-upload-shard"><code>/v1/shards</code></a>. See <a href="./shard#shard-upload">Shard format guide</a>.</li> <li><strong>Response</strong>: A newline-delimited JSON stream (<code>Content-Type: application/x-ndjson</code>, <code>Cache-Control: no-cache</code>), one JSON object (“event”) per line.</li></ul> <p>The HTTP status is <code>200 OK</code> as soon as the stream starts, so success or failure is carried by the terminal event, NOT by the status code. | |
| Clients MUST read the stream to completion and inspect the terminal event.</p> <p>Each event has a <code>type</code> field:</p> <ul><li><p><code>validating</code>: verification progress. <code>verified</code> is the number of completed verification tasks, <code>total</code> the number spawned so far. While the shard is still being received <code>total</code> grows, so treat <code>verified / total</code> as a live ratio, not a final percentage.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-json "><!----><span class="hljs-punctuation">{</span><span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span><span class="hljs-string">"validating"</span><span class="hljs-punctuation">,</span><span class="hljs-attr">"verified"</span><span class="hljs-punctuation">:</span><span class="hljs-number">120</span><span class="hljs-punctuation">,</span><span class="hljs-attr">"total"</span><span class="hljs-punctuation">:</span><span class="hljs-number">512</span><span class="hljs-punctuation">}</span><!----></pre></div><!----></li> <li><p><code>committing</code>: the shard is being durably written. <code>stage</code> identifies the sub-step, so a stalled commit shows where it is stuck:</p> <ul><li><code>uploading</code>: persisting the shard object to storage.</li> <li><code>syncing</code>: registering the shard (file ids, global dedup, shard list).</li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-json "><!----><span class="hljs-punctuation">{</span><span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span><span class="hljs-string">"committing"</span><span class="hljs-punctuation">,</span><span class="hljs-attr">"stage"</span><span class="hljs-punctuation">:</span><span class="hljs-string">"uploading"</span><span class="hljs-punctuation">}</span><!----></pre></div><!----></li> <li><p><code>result</code>: terminal success. Carries the same <a href="./api#4-upload-shard"><code>UploadShardResponse</code></a> values (<code>0</code>: already existed, <code>1</code>: registered); as with <code>/v1/shards</code> the value is informational, a <code>result</code> event means the upload succeeded.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-json "><!----><span class="hljs-punctuation">{</span><span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span><span class="hljs-string">"result"</span><span class="hljs-punctuation">,</span><span class="hljs-attr">"result"</span><span class="hljs-punctuation">:</span><span class="hljs-number">1</span><span class="hljs-punctuation">}</span><!----></pre></div><!----></li> <li><p><code>error</code>: terminal failure with a sanitized message. Because the status is already <code>200 OK</code>, this event is the only failure signal once streaming has started.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-json "><!----><span class="hljs-punctuation">{</span><span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span><span class="hljs-string">"error"</span><span class="hljs-punctuation">,</span><span class="hljs-attr">"message"</span><span class="hljs-punctuation">:</span><span class="hljs-string">"..."</span><span class="hljs-punctuation">}</span><!----></pre></div><!----></li></ul> <p>A typical successful stream:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-txt "><!---->{"type":"validating","verified":0,"total":512} | |
| {"type":"validating","verified":256,"total":512} | |
| {"type":"committing","stage":"uploading"} | |
| {"type":"committing","stage":"syncing"} | |
| {"type":"result","result":1}<!----></pre></div><!----> <p>If validation stalls, the server periodically re-emits the last progress event as a heartbeat so the stream never looks dead, which lets clients keep a short read timeout.</p> <blockquote class="note"><p>Additive change: <code>/v1/shards</code> is unchanged. Clients SHOULD try <code>/v2/shards</code> and fall back to <code>/v1/shards</code> on a <code>404</code> or <code>501</code>. The reference client caches the detected shard API version for the session, so this fallback probe happens once rather than per shard.</p></blockquote> <ul><li><strong>Error Responses</strong>: A malformed or unauthorized request can still fail before streaming starts; see <a href="./api#error-cases">Error Cases</a>. Once the stream has started (<code>200 OK</code>), validation and registration failures are reported through the terminal <code>error</code> event instead. <ul><li><code>401 Unauthorized</code>: Refresh the token to continue making requests, or provide a token in the <code>Authorization</code> header.</li> <li><code>403 Forbidden</code>: Token provided but does not have a wide enough scope (for example, a <code>read</code> token was provided).</li></ul></li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-txt "><!---->POST /v2/shards | |
| -H "Authorization: Bearer <token>"<!----></pre></div><!----> <!--[2--><h3 class="relative group"><a id="6-batch-file-reconstruction" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#6-batch-file-reconstruction"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>6. Batch File Reconstruction</span></h3><!--]--><!----> <ul><li><p><strong>Description</strong>: Retrieves reconstruction information for multiple files in a single request, avoiding N separate calls.</p></li> <li><p><strong>Path</strong>: <code>/v1/reconstructions</code></p></li> <li><p><strong>Method</strong>: <code>POST</code></p></li> <li><p><strong>Headers</strong>:</p> <ul><li><code>Accept-Encoding</code>: OPTIONAL. The server supports <code>gzip</code> and <code>zstd</code> compression on the JSON response. Clients SHOULD send <code>Accept-Encoding: gzip</code> or <code>Accept-Encoding: zstd</code> to reduce response size.</li></ul></li> <li><p><strong>Minimum Token Scope</strong>: <code>read</code></p></li> <li><p><strong>Body</strong>: JSON array of keys, each a <code>{ "prefix", "hash" }</code> object. <code>prefix</code> is <code>default</code>; <code>hash</code> is the file hash in hex format (64 lowercase hexadecimal characters). Duplicate keys are de-duplicated server-side.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-json "><!----><span class="hljs-punctuation">[</span> | |
| <span class="hljs-punctuation">{</span> <span class="hljs-attr">"prefix"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"default"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"hash"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"</span> <span class="hljs-punctuation">}</span> | |
| <span class="hljs-punctuation">]</span><!----></pre></div><!----></li> <li><p><strong>Response</strong>: JSON (<code>BatchQueryReconstructionResponse</code>)</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-json "><!----><span class="hljs-punctuation">{</span> | |
| <span class="hljs-attr">"files"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> | |
| <span class="hljs-attr">"0123..."</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-comment">/* CASReconstructionTerm, ... */</span><span class="hljs-punctuation">]</span> | |
| <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> | |
| <span class="hljs-attr">"fetch_info"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> | |
| <span class="hljs-attr">"0123..."</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-comment">/* CASReconstructionFetchInfo, ... */</span><span class="hljs-punctuation">]</span> | |
| <span class="hljs-punctuation">}</span> | |
| <span class="hljs-punctuation">}</span><!----></pre></div><!----> <p><code>files</code> maps each file id to its reconstruction terms; <code>fetch_info</code> is shared across files and keyed by xorb hash. This endpoint returns the v1 response shape; for the multi-range optimized format, call <code>/v2/reconstructions/{file_id}</code> per file.</p></li> <li><p><strong>Error Responses</strong>: See <a href="./api#error-cases">Error Cases</a></p> <ul><li><code>400 Bad Request</code>: Malformed body or invalid file id in the request.</li> <li><code>401 Unauthorized</code>: Refresh the token to continue making requests, or provide a token in the <code>Authorization</code> header.</li> <li><code>404 Not Found</code>: One or more files do not exist. Not retryable.</li></ul></li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-txt "><!---->POST /v1/reconstructions | |
| -H "Authorization: Bearer <token>" | |
| -H "Content-Type: application/json"<!----></pre></div><!----> <!--[2--><h3 class="relative group"><a id="7-head-xorb" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#7-head-xorb"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>7. Head Xorb</span></h3><!--]--><!----> <ul><li><strong>Description</strong>: Existence check for a Xorb.</li> <li><strong>Path</strong>: <code>/v1/xorbs/{prefix}/{hash}</code></li> <li><strong>Method</strong>: <code>HEAD</code></li> <li><strong>Parameters</strong>: <ul><li><code>prefix</code>: The only acceptable prefix for Xorbs is <code>default</code>.</li> <li><code>hash</code>: Xorb hash in hex format (64 lowercase hexadecimal characters). | |
| See <a href="./hashing#xorb-hashes">Xorb Hashes</a> and <a href="./api#converting-hashes-to-strings">converting hashes to strings</a>.</li></ul></li> <li><strong>Minimum Token Scope</strong>: <code>read</code></li> <li><strong>Body</strong>: None.</li> <li><strong>Response</strong>: Empty body. Response headers: <ul><li><code>Content-Length</code>: size in bytes of the stored Xorb.</li></ul></li> <li><strong>Error Responses</strong>: See <a href="./api#error-cases">Error Cases</a> <ul><li><code>400 Bad Request</code>: Malformed hash in the path.</li> <li><code>401 Unauthorized</code>: Refresh the token to continue making requests, or provide a token in the <code>Authorization</code> header.</li> <li><code>404 Not Found</code>: The Xorb does not exist. Not retryable.</li></ul></li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-txt "><!---->HEAD /v1/xorbs/default/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef | |
| -H "Authorization: Bearer <token>"<!----></pre></div><!----> <!--[2--><h3 class="relative group"><a id="8-head-file" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#8-head-file"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>8. Head File</span></h3><!--]--><!----> <ul><li><strong>Description</strong>: Existence check for a file.</li> <li><strong>Path</strong>: <code>/v1/files/{file_id}</code></li> <li><strong>Method</strong>: <code>HEAD</code></li> <li><strong>Parameters</strong>: <ul><li><code>file_id</code>: File hash in hex format (64 lowercase hexadecimal characters). | |
| See <a href="./hashing#file-hashes">file hashes</a> and <a href="./api#converting-hashes-to-strings">converting hashes to strings</a>.</li></ul></li> <li><strong>Minimum Token Scope</strong>: <code>read</code></li> <li><strong>Body</strong>: None.</li> <li><strong>Response</strong>: Empty body. Response headers: <ul><li><code>Content-Length</code>: size in bytes of the full file.</li></ul></li> <li><strong>Error Responses</strong>: See <a href="./api#error-cases">Error Cases</a> <ul><li><code>400 Bad Request</code>: Malformed <code>file_id</code> in the path.</li> <li><code>401 Unauthorized</code>: Refresh the token to continue making requests, or provide a token in the <code>Authorization</code> header.</li> <li><code>404 Not Found</code>: The file does not exist. Not retryable.</li></ul></li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-txt "><!---->HEAD /v1/files/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef | |
| -H "Authorization: Bearer <token>"<!----></pre></div><!----> <!--[2--><h3 class="relative group"><a id="9-get-file-chunk-hashes" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#9-get-file-chunk-hashes"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>9. Get File Chunk Hashes</span></h3><!--]--><!----> <ul><li><p><strong>Description</strong>: For a file and a set of “dirty” byte ranges (regions the client intends to re-chunk), returns the chunk windows the client must re-chunk plus opaque hash subtrees covering the unchanged gaps. Used by delta uploads to compose a new shard without re-uploading already-known chunks. The response covers the full file.</p></li> <li><p><strong>Path</strong>: <code>/v2/file-chunk-hashes/{file_id}</code></p></li> <li><p><strong>Method</strong>: <code>GET</code></p></li> <li><p><strong>Parameters</strong>:</p> <ul><li><code>file_id</code>: File hash in hex format (64 lowercase hexadecimal characters). | |
| See <a href="./hashing#file-hashes">file hashes</a> and <a href="./api#converting-hashes-to-strings">converting hashes to strings</a>.</li></ul></li> <li><p><strong>Headers</strong>:</p> <ul><li><code>X-Range-Dirty</code>: REQUIRED. One or more byte ranges using the standard <code>bytes=</code> syntax (inclusive ends, comma-separated), e.g. <code>bytes=0-1023,5000-9999</code>. Ranges are sorted and merged server-side. At least one range MUST be present.</li> <li><code>Accept-Encoding</code>: OPTIONAL. The server supports <code>gzip</code> and <code>zstd</code> compression on the JSON response.</li></ul></li> <li><p><strong>Minimum Token Scope</strong>: <code>read</code></p></li> <li><p><strong>Body</strong>: None.</p></li> <li><p><strong>Response</strong>: JSON (<code>FileChunkHashesResponse</code>). Unlike other endpoints in this spec, this response uses <code>camelCase</code> field names, matching the server.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-json "><!----><span class="hljs-punctuation">{</span> | |
| <span class="hljs-attr">"totalChunks"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1234</span><span class="hljs-punctuation">,</span> | |
| <span class="hljs-attr">"fileSize"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">9876543</span><span class="hljs-punctuation">,</span> | |
| <span class="hljs-attr">"windows"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span> | |
| <span class="hljs-punctuation">{</span> <span class="hljs-attr">"dirtyByteRange"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span><span class="hljs-number">0</span><span class="hljs-punctuation">,</span> <span class="hljs-number">65536</span><span class="hljs-punctuation">]</span> <span class="hljs-punctuation">}</span> | |
| <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span> | |
| <span class="hljs-attr">"hashRanges"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span> | |
| <span class="hljs-literal"><span class="hljs-keyword">null</span></span><span class="hljs-punctuation">,</span> | |
| <span class="hljs-string">"<opaque MerkleHashSubtree>"</span> | |
| <span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span> | |
| <span class="hljs-attr">"gapVerification"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span> | |
| <span class="hljs-string">"<hex MerkleHash>"</span> | |
| <span class="hljs-punctuation">]</span> | |
| <span class="hljs-punctuation">}</span><!----></pre></div><!----> <ul><li><code>windows</code>: one entry per dirty range (adjacent dirty ranges that share the same chunk are merged). Each <code>dirtyByteRange</code> is <code>[start, end)</code> with an <strong>exclusive</strong> end (note: the <code>X-Range-Dirty</code> request header uses inclusive ends). Bounds are chunk-aligned, expanded outward to fully contain the requested dirty range; the client re-chunks this exact span.</li> <li><code>hashRanges</code>: <code>N + 1</code> entries for <code>N</code> windows — <code>[before_w0, between_w0_w1, ..., after_wN]</code>. Each entry is an opaque <code>MerkleHashSubtree</code>; pass as-is to the client merge routine. <code>null</code> when the gap is empty (for example, a window starts at chunk 0).</li> <li><code>gapVerification</code>: one hash per stable original segment (a segment lying entirely in a gap between dirty windows or before/after them, in segment order). The client wraps each into a <code>FileVerificationEntry</code> for the verification section of the composed shard. Empty when every segment overlaps a dirty range.</li></ul></li> <li><p><strong>Error Responses</strong>: See <a href="./api#error-cases">Error Cases</a></p> <ul><li><code>400 Bad Request</code>: Missing or malformed <code>X-Range-Dirty</code> header, malformed <code>file_id</code>, or no range survives clamping to the file.</li> <li><code>401 Unauthorized</code>: Refresh the token to continue making requests, or provide a token in the <code>Authorization</code> header.</li> <li><code>404 Not Found</code>: The file does not exist. Not retryable.</li></ul></li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-txt "><!---->GET /v2/file-chunk-hashes/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef | |
| -H "Authorization: Bearer <token>" | |
| -H "X-Range-Dirty: bytes=0-65535,200000-299999"<!----></pre></div><!----> <!--[2--><h3 class="relative group"><a id="10-get-file-reconstruction-v1" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#10-get-file-reconstruction-v1"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>10. Get File Reconstruction (v1)</span></h3><!--]--><!----> <blockquote class="warning"><p><strong>Deprecated.</strong> Use <a href="./api#1-get-file-reconstruction"><code>GET /v2/reconstructions/{file_id}</code></a> instead. This v1 endpoint is still served for existing clients but will be removed once they migrate. The v2 endpoint returns the multi-range optimized response described in section 1.</p></blockquote> <ul><li><p><strong>Description</strong>: Retrieves reconstruction information for a specific file, includes byte range support when <code>Range</code> header is set. Returns the v1 response shape (<code>terms</code> + <code>fetch_info</code>).</p></li> <li><p><strong>Path</strong>: <code>/v1/reconstructions/{file_id}</code></p></li> <li><p><strong>Method</strong>: <code>GET</code></p></li> <li><p><strong>Parameters</strong>:</p> <ul><li><code>file_id</code>: File hash in hex format (64 lowercase hexadecimal characters). | |
| See <a href="./hashing#file-hashes">file hashes</a> for computing the file hash and <a href="./api#converting-hashes-to-strings">converting hashes to strings</a>.</li></ul></li> <li><p><strong>Headers</strong>:</p> <ul><li><code>Range</code>: OPTIONAL. Format: <code>bytes={start}-{end}</code> (end is inclusive).</li></ul></li> <li><p><strong>Minimum Token Scope</strong>: <code>read</code></p></li> <li><p><strong>Body</strong>: None.</p></li> <li><p><strong>Response</strong>: JSON (<code>QueryReconstructionResponse</code>)</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-json "><!----><span class="hljs-punctuation">{</span> | |
| <span class="hljs-attr">"offset_into_first_range"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">0</span><span class="hljs-punctuation">,</span> | |
| <span class="hljs-attr">"terms"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>...<span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span> | |
| <span class="hljs-attr">"fetch_info"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>...<span class="hljs-punctuation">}</span> | |
| <span class="hljs-punctuation">}</span><!----></pre></div><!----></li> <li><p><strong>Error Responses</strong>: See <a href="./api#error-cases">Error Cases</a></p> <ul><li><code>400 Bad Request</code>: Malformed <code>file_id</code> in the path. Fix the path before retrying.</li> <li><code>401 Unauthorized</code>: Refresh the token to continue making requests, or provide a token in the <code>Authorization</code> header.</li> <li><code>404 Not Found</code>: The file does not exist. Not retryable.</li> <li><code>416 Range Not Satisfiable</code>: The requested byte range start exceeds the end of the file. Not retryable.</li></ul></li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-txt "><!---->GET /v1/reconstructions/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef | |
| -H "Authorization: Bearer <token>" | |
| OPTIONAL: -H Range: "bytes=0-100000"<!----></pre></div><!----> <!--[1--><h2 class="relative group"><a id="error-cases" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#error-cases"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Error Cases</span></h2><!--]--><!----> <!--[2--><h3 class="relative group"><a id="non-retryable-errors" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#non-retryable-errors"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Non-Retryable Errors</span></h3><!--]--><!----> <ul><li><strong>400 Bad Request</strong>: Returned when the request parameters are invalid (for example, invalid Xorb/Shard on upload APIs).</li> <li><strong>401 Unauthorized</strong>: Refresh the token to continue making requests, or provide a token in the <code>Authorization</code> header.</li> <li><strong>403 Forbidden</strong>: Token provided but does not have a wide enough scope (for example, a <code>read</code> token was provided for an API requiring <code>write</code> scope).</li> <li><strong>404 Not Found</strong>: Occurs on <code>GET</code> APIs where the resource (Xorb, file) does not exist.</li> <li><strong>416 Range Not Satisfiable</strong>: Reconstruction API only; returned when byte range requests are invalid. Specifically, the requested start range is greater than or equal to the length of the file.</li></ul> <!--[2--><h3 class="relative group"><a id="retryable-errors" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#retryable-errors"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Retryable Errors</span></h3><!--]--><!----> <ul><li><strong>Connection Errors</strong>: Often caused by network issues. Retry if intermittent. | |
| Clients SHOULD ensure no firewall blocks requests and SHOULD NOT use DNS overrides.</li> <li><strong>429 Rate Limiting</strong>: Lower your request rate using a backoff strategy, then wait and retry. | |
| Assume all APIs are rate limited.</li> <li><strong>500 Internal Server Error</strong>: The server experienced an intermittent issue; clients SHOULD retry their requests.</li> <li><strong>503 Service Unavailable</strong>: Service is temporarily unable to process requests; wait and retry.</li> <li><strong>504 Gateway Timeout</strong>: Service took too long to respond; wait and retry.</li></ul> <a class="!text-gray-400 !no-underline text-sm flex items-center not-prose mt-4" href="https://github.com/huggingface/hub-docs/blob/main/docs/xet/api.md" target="_blank"><svg class="mr-1" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M31,16l-7,7l-1.41-1.41L28.17,16l-5.58-5.59L24,9l7,7z"></path><path d="M1,16l7-7l1.41,1.41L3.83,16l5.58,5.59L8,23l-7-7z"></path><path d="M12.419,25.484L17.639,6.552l1.932,0.518L14.351,26.002z"></path></svg><!----> <span><span class="underline">Update</span> on GitHub</span></a><!----> <p></p><!--]--><!----><!--]--><!--]--><!--]--> <!--[-1--><!--]--><!--]--> | |
| <script> | |
| { | |
| __sveltekit_ofiiif = { | |
| base: "/docs/xet/pr_2742/en", | |
| assets: "/docs/xet/pr_2742/en" | |
| }; | |
| const element = document.currentScript.parentElement; | |
| Promise.all([ | |
| import("/docs/xet/pr_2742/en/_app/immutable/entry/start.Av_YqhRg.js"), | |
| import("/docs/xet/pr_2742/en/_app/immutable/entry/app.DOxgnXbz.js") | |
| ]).then(([kit, app]) => { | |
| kit.start(app, element, { | |
| node_ids: [0, 2], | |
| data: [null,null], | |
| form: null, | |
| error: null | |
| }); | |
| }); | |
| } | |
| </script> | |
Xet Storage Details
- Size:
- 96.3 kB
- Xet hash:
- 55843a76dd6fd9d718a0b1ead1d9efc974a9200bd6c24a77c4f39160ffd32ff0
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.