Chute API
Chute turns a file or a snippet of text into a short public link. Everything the web app
does — upload a file, create a text paste, organise uploads into folders, hand out anonymous
upload links, set expiry — is available over a small HTTP API you can drive from a script,
ShareX, a CI job, or curl.
- Base URL:
https://chute.leiritech.com - Format: JSON in, JSON out (the one-step upload takes
multipart/form-data). - Everything is scoped to you. A key authenticates as exactly one account. You can only
ever see and change your own uploads, pastes, folders, and links. Another user's id is
indistinguishable from one that does not exist — it returns
404, never a hint that it is real.
Authentication
Create a key in the web app under Settings → API keys. It is shown once, at creation time — copy it immediately. A key looks like:
chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb
Send it in the X-Api-Key header on every request:
curl -H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
https://chute.leiritech.com/api/profile
A missing or invalid key returns 401:
{ "error": "Invalid API key" }
What a key can and cannot do
A key can drive the whole content surface: files, pastes, folders, upload-links, uploads
management, and your profile/preferences. A key cannot touch account-security surfaces —
minting or revoking API keys, ShareX config (.sxcu), account settings, and the admin panel
all require a browser session. (You cannot mint an API key with an API key.)
Rate limits
Write endpoints are rate-limited per IP and per user (and per key where relevant). The
budgets are generous for normal use — for example uploads and pastes allow 60 creations per
10 minutes. When you exceed a limit you get 429 with a Retry-After header (seconds):
{ "error": "Too many requests" }
Files
There are two ways to store a file. They exist because browsers and scripts have different constraints.
| Path | Size cap | Body | Use it when |
|---|---|---|---|
One-step POST /api/upload | 4 MB | multipart/form-data | Scripts, ShareX, CI — a single request. The bytes transit the serverless function, so Vercel's ~4.5 MB body limit caps it. |
| Direct-to-storage (3 steps) | 50 MB | JSON handshake + direct PUT | The web uploader, and clients that use the @vercel/blob client library. Bytes go straight to blob storage, bypassing the function body limit. |
For most scripting, use the one-step path — it is a single curl.
One-step upload — POST /api/upload
Multipart form with a file field. Optional expires_at overrides your account's default
retention for this one upload (see Expiry).
curl -X POST https://chute.leiritech.com/api/upload \
-H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
-F "file=@screenshot.png"
{
"url": "https://chute.leiritech.com/ps7zLbYNuif",
"deleteUrl": "https://chute.leiritech.com/api/uploads/2b8f…/delete?token=…",
"error": null
}
url— the public short link. Open it and the file is served (or force-downloaded, for active content types like HTML/SVG).deleteUrl— a tokenised one-shot delete link (no auth needed; the token is the authorization). This is the ShareXDeletionURL.
With an explicit expiry:
curl -X POST https://chute.leiritech.com/api/upload \
-H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
-F "file=@report.pdf" \
-F "expires_at=2030-01-01T00:00:00Z"
Errors: 400 (no file field / bad expires_at), 413 (over 4 MB or over your storage
quota), 429 (rate limited), 502 (storage backend failed).
Direct-to-storage upload (up to 50 MB)
This is a three-step handshake so the bytes never pass through the serverless function:
- Mint a target —
POST /api/upload/target. This writes apendingrow and returns a short-lived client token for the blob store. - PUT the bytes directly to the blob store using that token.
- Confirm —
POST /api/upload/confirmwith the returnedpathnameandblobUrl. This verifies the real byte size, enforces the 50 MB cap and your quota, and flips the rowpending → active, returning the public link.
Steps 1 and 3 are ordinary JSON endpoints (session or API key). Step 2 speaks the Vercel
Blob client-upload protocol, so in practice you drive all three with the
@vercel/blob client rather than raw curl:
import { upload } from "@vercel/blob/client";
const blob = await upload(file.name, file, {
access: "public",
handleUploadUrl: "https://chute.leiritech.com/api/upload/target",
headers: { "X-Api-Key": "chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" },
clientPayload: JSON.stringify({ filename: file.name, size: file.size, contentType: file.type }),
});
// then POST { pathname: blob.pathname, blobUrl: blob.url } to /api/upload/confirm
Step 1 in isolation — minting a target returns a client token (and records a pending row, which is swept if you never confirm it):
curl -X POST https://chute.leiritech.com/api/upload/target \
-H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
-H "Content-Type: application/json" \
-d '{
"type": "blob.generate-client-token",
"payload": {
"pathname": "notes.txt",
"callbackUrl": "https://chute.leiritech.com/api/upload/target",
"clientPayload": "{\"filename\":\"notes.txt\",\"size\":12,\"contentType\":\"text/plain\"}",
"multipart": false
}
}'
{ "type": "blob.generate-client-token", "clientToken": "vercel_blob_client_…" }
Confirm (step 3), once the bytes are in the store. pathname and blobUrl are the values
returned by the blob PUT in step 2 (blob.pathname and blob.url):
curl -X POST https://chute.leiritech.com/api/upload/confirm \
-H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
-H "Content-Type: application/json" \
-d '{ "pathname": "'"$PATHNAME"'", "blobUrl": "'"$BLOB_URL"'" }'
{ "url": "https://chute.leiritech.com/abc123", "slug": "abc123" }
Confirm errors: 400 (missing pathname/blobUrl), 409 (object not found in the store, or
the pending row expired past its grace window), 413 (over 50 MB or over quota).
Text pastes
A paste is a code snippet or markdown document stored inline (no file). It gets the same short
link, expiry, quota, and folder machinery as a file. The public link renders the paste
server-side (syntax-highlighted code, or sanitized markdown); append /raw for the plain
bytes.
Create — POST /api/pastes
curl -X POST https://chute.leiritech.com/api/pastes \
-H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
-H "Content-Type: application/json" \
-d '{
"content": "print(\"hello\")",
"language": "python",
"title": "hello.py"
}'
{ "url": "https://chute.leiritech.com/k3n8Qp2", "slug": "k3n8Qp2" }
Body fields:
| Field | Required | Notes |
|---|---|---|
content | yes | The text. Non-empty, ≤ 1 MB of UTF-8. |
language | no | One of the allowed languages. Unknown → plaintext. |
title | no | Display title, ≤ 200 chars. |
expires_at | no | UTC ISO instant, or "never". Omitted → your default_text_retention. |
folder_id | no | File the paste into one of your folders. Must be a folder you own (else 404). |
Read the raw text — GET /:slug/raw
Public, no auth. Serves the paste body verbatim as text/plain. Append ?dl=1 to get it as
a download.
curl https://chute.leiritech.com/k3n8Qp2/raw
print("hello")
Paste errors: 400 (empty content / bad field), 413 (over 1 MB or over quota), 404
(unknown/expired slug, or an unowned folder_id).
Paste languages
plaintext, markdown, javascript, typescript, jsx, tsx, python, json, html,
css, sql, bash, yaml, rust, go. markdown is rendered (sanitized); everything else
is syntax-highlighted as code.
Folders
Flat, per-user groupings for your uploads and pastes.
List — GET /api/folders
curl -H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
https://chute.leiritech.com/api/folders
{
"items": [
{ "id": "9d2c…", "name": "Invoices", "created_at": "2026-08-19T10:00:00.000Z", "item_count": 3 }
]
}
Create — POST /api/folders
curl -X POST https://chute.leiritech.com/api/folders \
-H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
-H "Content-Type: application/json" \
-d '{ "name": "Invoices" }'
{ "folder": { "id": "9d2c…", "name": "Invoices", "created_at": "2026-08-19T10:00:00.000Z", "item_count": 0 } }
Name is required, trimmed, 1–100 chars. Returns 201.
Rename — PATCH /api/folders/:id
curl -X PATCH https://chute.leiritech.com/api/folders/9d2c… \
-H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
-H "Content-Type: application/json" \
-d '{ "name": "Receipts" }'
{ "folder": { "id": "9d2c…", "name": "Receipts", "created_at": "2026-08-19T10:00:00.000Z" } }
Delete — DELETE /api/folders/:id
Deleting a folder never deletes its uploads — they are simply un-filed (folder_id → null).
The response reports how many items were un-filed.
curl -X DELETE https://chute.leiritech.com/api/folders/9d2c… \
-H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb"
{ "unfiled_count": 3 }
Folder errors: 400 (empty/too-long name), 404 (unknown id, or a folder you do not own).
Workspaces
A workspace is a top-level partition of your library: its own folder tree, files, notes and
unfiled items. Every account owns at least one (a default is created at signup; existing
content was migrated into one named Personal). Tenancy stays the account — quota, API keys
and public links are workspace-invisible.
Scoping: the notes/library/folders lists are scoped to your ACTIVE workspace, carried by
the chute_ws cookie (set by the web app when you switch). API-key requests have no cookie
and always operate on the default workspace. An absent, stale or foreign cookie silently
falls back to the default — never an error, never a leak.
List — GET /api/workspaces
{
"items": [
{ "id": "1f0a…", "name": "Personal", "position": 0, "created_at": "2026-10-02T…", "folder_count": 6, "item_count": 144 }
]
}
Create — POST /api/workspaces
{ "name": "Work" } → 201 with the workspace. Names are 1–100 chars, unique per account
(case-insensitive; 409 on a duplicate). Creating switches nothing server-side — set the
chute_ws cookie to the new id to work inside it.
Rename — PATCH /api/workspaces/:id
{ "name": "New name" } → 200. Same name rules as create.
Delete — DELETE /api/workspaces/:id
Empty-only (409 when the workspace holds any folder or item) and never your last one
(409). There is no cascade anywhere: content must be moved or deleted first.
Reorder — POST /api/workspaces/reorder
{ "ids": ["<uuid>", …] } — the complete list in its new order; position = array index.
Atomic: an id you do not own rolls the whole reorder back (404).
Workspace errors: 400 (bad name), 404 (unknown/foreign id), 409 (duplicate name,
non-empty delete, last-workspace delete), 429 (creation rate limit).
Uploads management
List and manage the uploads (files and pastes) you already have.
List — GET /api/uploads
Cursor-paginated, newest first. pending rows are excluded. Optional limit (default 20, max
1000) and cursor.
curl -H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
"https://chute.leiritech.com/api/uploads?limit=50"
{
"items": [
{
"id": "2b8f…",
"slug": "ps7zLbYNuif",
"status": "active",
"kind": "file",
"original_filename": "screenshot.png",
"content_type": "image/png",
"size_bytes": 14821,
"expires_at": "2026-08-26T10:00:00.000Z",
"hit_count": 0,
"source": "api",
"created_at": "2026-08-19T10:00:00.000Z",
"folder_id": null
}
],
"nextCursor": null
}
Pass nextCursor back as ?cursor=… to page. POST is not allowed here (405).
Update — PATCH /api/uploads/:id
Change the expiry and/or move to a folder. The two are independent — sending only folder_id
never touches the expiry, and vice-versa.
Set an expiry:
curl -X PATCH https://chute.leiritech.com/api/uploads/2b8f… \
-H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
-H "Content-Type: application/json" \
-d '{ "expires_at": "2030-01-01T00:00:00Z" }'
Keep forever (null) and/or move into a folder:
curl -X PATCH https://chute.leiritech.com/api/uploads/2b8f… \
-H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
-H "Content-Type: application/json" \
-d '{ "expires_at": null, "folder_id": "9d2c…" }'
Returns the updated upload (same shape as a list item). Errors: 400 (nothing to update / bad
expires_at), 404 (unknown upload, or an unowned folder_id).
Delete — DELETE /api/uploads/:id
Deletes the object and the row. Idempotent — an unknown or already-deleted id also returns
204.
curl -X DELETE https://chute.leiritech.com/api/uploads/2b8f… \
-H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" -i
HTTP/2 204
502 if the storage backend fails to delete (the row is kept and retried automatically).
Upload links
An upload link is an anonymous, shareable file-request link: anyone with the link can drop a file into your account (up to configurable limits), without an account of their own.
List — GET /api/upload-links
curl -H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
https://chute.leiritech.com/api/upload-links
{
"items": [
{
"id": "7a1e…",
"token": "R4nD0mToken",
"label": "Send me your slides",
"status": "active",
"max_uploads": 10,
"upload_count": 0,
"max_file_bytes": null,
"created_at": "2026-08-19T10:00:00.000Z",
"expires_at": "2026-08-26T10:00:00.000Z",
"revoked_at": null
}
]
}
The public page for a link is https://chute.leiritech.com/u/<token>.
Create — POST /api/upload-links
All fields optional:
| Field | Default | Notes |
|---|---|---|
label | none | Owner note, ≤ 80 chars. |
expires_at | 7 days | UTC ISO instant in the future; null = never expires. |
max_uploads | 10 | 1–1000; null = unlimited. |
max_file_bytes | none | Per-file cap, clamped to 50 MB. |
folder_id | none | File anything dropped here into one of your folders. |
curl -X POST https://chute.leiritech.com/api/upload-links \
-H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
-H "Content-Type: application/json" \
-d '{ "label": "Send me your slides", "max_uploads": 5 }'
{ "link": { "id": "7a1e…", "token": "R4nD0mToken", "label": "Send me your slides", "status": "active", "max_uploads": 5, "upload_count": 0, "max_file_bytes": null, "created_at": "2026-08-19T10:00:00.000Z", "expires_at": "2026-08-26T10:00:00.000Z", "revoked_at": null } }
Returns 201. Errors: 400 (bad expires_at/max_uploads/max_file_bytes), 404
(unowned folder_id).
Revoke — DELETE /api/upload-links/:id
Terminal — a revoked link rejects the token immediately and cannot be un-revoked. Idempotent:
unknown, already-revoked, or someone else's id all return 204.
curl -X DELETE https://chute.leiritech.com/api/upload-links/7a1e… \
-H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" -i
HTTP/2 204
Profile
Your account plus the two preferences you can change.
Read — GET /api/profile
curl -H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
https://chute.leiritech.com/api/profile
{
"id": "1f0a…",
"email": "you@example.com",
"name": null,
"role": "user",
"status": "active",
"default_retention": "7d",
"default_text_retention": "7d",
"created_at": "2026-08-01T09:00:00.000Z"
}
Update preferences — PATCH /api/profile
default_retention applies to new file uploads; default_text_retention to new
pastes. Each is independently optional; at least one must be present. Neither ever rewrites
existing uploads. Allowed values: never, 1h, 1d, 7d, 30d.
curl -X PATCH https://chute.leiritech.com/api/profile \
-H "X-Api-Key: chute_Ax7Kd0f2Qe8sZ1nD3rP9uYb" \
-H "Content-Type: application/json" \
-d '{ "default_retention": "30d", "default_text_retention": "1d" }'
Returns the updated profile. Errors: 400 (nothing to update, or an invalid value).
Limits
| Limit | Value |
|---|---|
One-step API upload (/api/upload) | 4 MB per file |
| Direct-to-storage upload | 50 MB per file |
Text paste (/api/pastes) | 1 MB of UTF-8 |
| Folder name | 100 chars |
| Upload-link label | 80 chars |
| Paste title | 200 chars |
| Per-account storage quota | Applies to all uploads + pastes combined |
| Write rate limit | ~60 creations / 10 min (per IP and per user) |
Expiry values
Wherever a default retention is set (default_retention, default_text_retention), the
allowed values are:
| Value | Meaning |
|---|---|
never | Keep until you delete it |
1h | 1 hour |
1d | 1 day |
7d | 7 days (the shipped default) |
30d | 30 days |
Wherever a per-item expiry is set (expires_at on an upload, paste, or link), pass a UTC
ISO-8601 instant (e.g. 2030-01-01T00:00:00Z), or:
null— keep forever (on/api/uploads/:idand/api/upload-links)."never"— keep forever (on/api/uploadand/api/pastes, which take the value as text).
Omitting the field entirely means "use my account default" — which is not the same as
sending null.
Error codes
| Status | Meaning |
|---|---|
400 | Malformed body or an invalid field value |
401 | Missing or invalid API key |
404 | Resource not found — or a resource you do not own (no existence leak), or an unowned folder_id |
409 | Upload confirm conflict (object missing / pending row expired) |
413 | Too large — over a size cap or over your storage quota |
429 | Rate limited — see the Retry-After header |
502 | Storage backend failure (the operation is retried automatically) |
Errors are JSON: { "error": "human-readable message" }. Successful DELETEs return 204
with no body.