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.

PathSize capBodyUse it when
One-step POST /api/upload4 MBmultipart/form-dataScripts, 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 MBJSON handshake + direct PUTThe 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 ShareX DeletionURL.

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:

  1. Mint a target — POST /api/upload/target. This writes a pending row and returns a short-lived client token for the blob store.
  2. PUT the bytes directly to the blob store using that token.
  3. Confirm — POST /api/upload/confirm with the returned pathname and blobUrl. This verifies the real byte size, enforces the 50 MB cap and your quota, and flips the row pending → 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:

FieldRequiredNotes
contentyesThe text. Non-empty, ≤ 1 MB of UTF-8.
languagenoOne of the allowed languages. Unknown → plaintext.
titlenoDisplay title, ≤ 200 chars.
expires_atnoUTC ISO instant, or "never". Omitted → your default_text_retention.
folder_idnoFile 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:

FieldDefaultNotes
labelnoneOwner note, ≤ 80 chars.
expires_at7 daysUTC ISO instant in the future; null = never expires.
max_uploads101–1000; null = unlimited.
max_file_bytesnonePer-file cap, clamped to 50 MB.
folder_idnoneFile 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

LimitValue
One-step API upload (/api/upload)4 MB per file
Direct-to-storage upload50 MB per file
Text paste (/api/pastes)1 MB of UTF-8
Folder name100 chars
Upload-link label80 chars
Paste title200 chars
Per-account storage quotaApplies 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:

ValueMeaning
neverKeep until you delete it
1h1 hour
1d1 day
7d7 days (the shipped default)
30d30 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/:id and /api/upload-links).
  • "never" — keep forever (on /api/upload and /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

StatusMeaning
400Malformed body or an invalid field value
401Missing or invalid API key
404Resource not found — or a resource you do not own (no existence leak), or an unowned folder_id
409Upload confirm conflict (object missing / pending row expired)
413Too large — over a size cap or over your storage quota
429Rate limited — see the Retry-After header
502Storage backend failure (the operation is retried automatically)

Errors are JSON: { "error": "human-readable message" }. Successful DELETEs return 204 with no body.