<pclass="lead">Warpbox is a one endpoint upload API. Send a multipart file with <code>curl</code>, a script, ShareX, or the <code>warpbox</code> CLI and get back a shareable box link. Request JSON to also receive private manage and delete URLs.</p>
<pclass="muted-copy">Want file URLs, a manage link, and a delete link back? Add <code>-H 'Accept: application/json'</code>. See <ahref="#responses"data-doc-link>the JSON response</a>.</p>
<pclass="lead">Base URL <code>{{.Data.BaseURL}}</code>. Authentication is optional: send <code>Authorization: Bearer <token></code> to upload as your account and use your account limits, or omit it to upload anonymously.</p>
</header>
<articleid="ep-upload"class="endpoint card">
<divclass="card-content">
<divclass="endpoint-head">
<spanclass="method method-post">POST</span>
<codeclass="endpoint-path">/api/v1/upload</code>
</div>
<p>The core endpoint. Accepts a <code>multipart/form-data</code> body with one or more files. Returns a plain box URL by default, or the full JSON object when you send <code>Accept: application/json</code>.</p>
<h4>Request fields</h4>
<divclass="field-grid">
<span><code>file</code></span><p>One or more files. Repeat the field for multiple files. Used by curl, browsers, and the CLI.</p>
<span><code>sharex</code></span><p>Alternative file field used by ShareX custom uploader configs. Same behaviour as <code>file</code>.</p>
<span><code>max_days</code></span><p>Optional. Days before the box expires. Defaults to 7.</p>
<span><code>expires_minutes</code></span><p>Optional. Lifetime in minutes. Takes precedence over <code>max_days</code> when > 0. Use it for expiries under a day (e.g. <code>60</code> = one hour).</p>
<span><code>max_downloads</code></span><p>Optional. Auto-expire the box after this many downloads.</p>
<span><code>password</code></span><p>Optional. Password required before viewing or downloading.</p>
<span><code>obfuscate_metadata</code></span><p>Optional <code>on</code>. Hides file names/counts until unlock (only meaningful with a password).</p>
</div>
<h4>Request headers</h4>
<divclass="field-grid">
<span><code>Accept</code></span><p><code>application/json</code> to receive the JSON body; otherwise a single plain-text URL.</p>
<span><code>Authorization</code></span><p>Optional <code>Bearer <token></code>. Attributes the upload to your account.</p>
<span><code>X-Warpbox-Batch</code></span><p>Optional grouping key. Uploads sharing a value within {{.Data.ShareXGroupWindow}} land in the same box. See <ahref="#integrations"data-doc-link>Integrations</a>.</p>
<p>Returned when <code>Accept: application/json</code> is sent. The raw delete token appears <strong>only once</strong>, inside <code>manageUrl</code> and <code>deleteUrl</code>, so store them privately. Full schema: <ahref="{{.Data.ResponseSchemaURL}}">upload-response.json</a>.</p>
<pclass="muted-copy">On error the body is <code>{ "error": "message" }</code> with a non-2xx status. Common causes: <code>413</code> over the size limit, <code>429</code> rate limited or over your daily quota, <code>401</code> bad token.</p>
</div>
</article>
<articleid="ep-resumable"class="endpoint card">
<divclass="card-content">
<h3>Resumable uploads</h3>
<p>For large files. Browser uploads use this by default. Create a session with file metadata, <code>PUT</code> exact-sized chunks, then complete. Chunks are temporary and cleaned if the session expires. Send the same <code>Authorization</code> header on every request for authenticated sessions.</p>
<divclass="endpoint-list">
<div><spanclass="method method-post">POST</span><code>/api/v1/uploads/resumable</code><em>Create a session</em></div>
<div><spanclass="method method-put">PUT</span><code>/api/v1/uploads/resumable/{sessionID}/files/{fileID}/chunks/{index}</code><em>Upload one chunk</em></div>
<div><spanclass="method method-post">POST</span><code>/api/v1/uploads/resumable/{sessionID}/complete</code><em>Finalize (returns the upload JSON)</em></div>
<pclass="lead">A tiny uploader script that wraps the API. It only needs <code>curl</code> (already on macOS, Linux, and Windows 10+). Point it at this instance once by setting <code>WARPBOX_HOST</code> to <code>{{.Data.BaseURL}}</code>, then upload from anywhere.</p>
# zsh users: use ~/.zshrc, then reload with: source ~/.profile</code></pre>
</figure>
<pclass="muted-copy">Verify with <code>warpbox --help</code>. Prefer a system wide install? Drop it in <code>/usr/local/bin</code> with <code>sudo</code>.</p>
<h4>Windows (PowerShell)</h4>
<p>Save the script, then add a function to your PowerShell profile so <code>warpbox</code> works anywhere.</p>
<p>To upload as your account (and use your account's size, daily, and retention limits), the CLI needs an API token. <strong>Set it in your environment</strong> so it never appears in your shell history or in the process list that any user on the machine can read:</p>
<figureclass="code-block">
<pre><code># macOS / Linux (add to ~/.profile or ~/.zshrc to persist)
export WARPBOX_TOKEN=wbx_your_token
warpbox ./photo.png
# Windows (persist for your user)
setx WARPBOX_TOKEN "wbx_your_token"</code></pre>
</figure>
<p>For CI or shared machines, keep the token in a file with locked down permissions and point the CLI at it. This avoids putting the secret on the command line at all:</p>
<pclass="muted-copy"><code>--auth <token></code> exists for quick tests but is discouraged: it leaks into shell history and <code>ps</code>. Create or revoke tokens under <ahref="/account/settings">Account, Access tokens</a>.</p>
<p>Grouping is <strong>opt in via the <code>X-Warpbox-Batch</code> request header</strong>. Without it, every file becomes its own box (the default). When the header is present, uploads sharing the same value (per account, or per IP for anonymous) within {{.Data.ShareXGroupWindow}} of each other are added to the <strong>same</strong> box, so a ShareX selection of several files produces one shareable link instead of one per file. The shipped config sets <code>X-Warpbox-Batch: sharex</code>; remove that header for one box per file.</p>
<pclass="muted-copy">The response also exposes <code>{json:thumbnailUrl}</code> for ShareX previews, <code>{json:deleteUrl}</code> for the deletion URL, and <code>{json:error}</code> so ShareX surfaces messages like rate limiting.</p>
<pclass="lead">Every snippet hits <code>POST {{.Data.UploadURL}}</code>. Add <code>-H 'Authorization: Bearer <token>'</code> to any of them to upload as your account.</p>
</header>
<articleid="ex-curl"class="card">
<divclass="card-content">
<h3>curl</h3>
<p>Plain text (one URL) for the shell; JSON for automation.</p>
<figureclass="code-block">
<pre><code># Just the box URL
curl -F file=@./report.pdf {{.Data.UploadURL}}
# Full JSON with manage + delete URLs, password and 1-hour expiry
curl -F file=@./report.pdf \
-F password=hunter2 \
-F expires_minutes=60 \
-H 'Accept: application/json' \
{{.Data.UploadURL}}</code></pre>
</figure>
</div>
</article>
<articleid="ex-wget"class="card">
<divclass="card-content">
<h3>wget</h3>
<p>The endpoint needs a real <code>multipart/form-data</code> body, which <code>wget</code> can't assemble on its own, so build the body by hand and post it. It also shows the wire format:</p>
<pclass="muted-copy">Add more form fields (<code>password</code>, <code>expires_minutes</code>, …) by repeating the <code>--%s … Content-Disposition: form-data; name="…"</code> block before the closing boundary. If this feels fiddly, <code>curl</code> or the CLI build the body for you.</p>
</div>
</article>
<articleid="ex-httpie"class="card">
<divclass="card-content">
<h3>HTTPie</h3>
<p>Multipart with form fields:</p>
<figureclass="code-block">
<pre><code>http --multipart POST {{.Data.UploadURL}} \
<pclass="muted-copy">On Windows PowerShell 5.1, use the bundled <code>curl.exe</code> (the same approach the <ahref="#cli"data-doc-link>CLI</a> takes) or the <code>warpbox.ps1</code> script.</p>
<pclass="lead">Quick answers, each linking back to the relevant part of the docs.</p>
</header>
<divclass="faq-list">
<detailsclass="faq-item">
<summary>Do I need an account or API key?</summary>
<p>No. Anonymous uploads work without one, see the <ahref="#home"data-doc-link>quickstart</a>. Add a token only to upload as your account and use your account's limits; set one up under <ahref="/account/settings">Account, Access tokens</a> and pass it as described in <ahref="#cli-auth"data-doc-link>CLI authentication</a>.</p>
</details>
<detailsclass="faq-item">
<summary>How do I send a password, expiry, or download limit?</summary>
<p>They're multipart form fields on the upload endpoint: <code>password</code>, <code>expires_minutes</code> (or <code>max_days</code>), and <code>max_downloads</code>. See the full list under <ahref="#ep-upload"data-doc-link>Endpoints, request fields</a>, or use the CLI flags in <ahref="#cli-usage"data-doc-link>CLI usage</a>.</p>
</details>
<detailsclass="faq-item">
<summary>How do I get file URLs and a delete link back?</summary>
<p>Send <code>Accept: application/json</code>. The response includes <code>boxUrl</code>, per-file <code>url</code>s, and the private <code>manageUrl</code>/<code>deleteUrl</code> (shown only once). See <ahref="#responses"data-doc-link>the JSON response</a>.</p>
</details>
<detailsclass="faq-item">
<summary>How do I upload one big file reliably?</summary>
<p>Use the <ahref="#ep-resumable"data-doc-link>resumable endpoints</a>: create a session, PUT chunks, then complete. Interrupted uploads can resume from the last chunk.</p>
</details>
<detailsclass="faq-item">
<summary>Can I upload several files into one shareable link?</summary>
<p>Yes. Send the <code>X-Warpbox-Batch</code> header with a shared value within {{.Data.ShareXGroupWindow}}. Details in <ahref="#integrations"data-doc-link>Integrations, grouping</a>.</p>
</details>
<detailsclass="faq-item">
<summary>Where's the keep-it-secret way to store my token?</summary>
<p>Use the <code>WARPBOX_TOKEN</code> environment variable or <code>--auth-file</code>, not <code>--auth</code> on the command line. Full guidance in <ahref="#cli-auth"data-doc-link>CLI authentication</a>.</p>
</details>
<detailsclass="faq-item">
<summary>My upload returns an error, what do the codes mean?</summary>
<p>Errors come back as <code>{ "error": "message" }</code> with a non-2xx status: <code>413</code> too large, <code>429</code> rate limited / over quota, <code>401</code> invalid token. See <ahref="#responses"data-doc-link>error responses</a>.</p>
</details>
<detailsclass="faq-item">
<summary>How do I use Warpbox from ShareX?</summary>
<p>Import the <code>.sxcu</code> and (optionally) add your token header. Step by step with the config in <ahref="#integrations"data-doc-link>Integrations, ShareX setup</a>.</p>
</details>
<detailsclass="faq-item">
<summary><code>warpbox: command not found</code> after install?</summary>
<p>The install directory isn't on your <code>PATH</code>. Fix it per your platform in <ahref="#cli-install"data-doc-link>Install & add to PATH</a>.</p>
</details>
<detailsclass="faq-item">
<summary>Is there a machine-readable schema?</summary>
<p>Yes: <ahref="{{.Data.RequestSchemaURL}}">upload-request.json</a> and <ahref="{{.Data.ResponseSchemaURL}}">upload-response.json</a> (JSON Schema 2020-12).</p>
