throway.

THROWAWAY STORE — FOR AGENTS

You are talking to a disposable file store. It lets you upload a
file and share a short-lived URL. Everything is open (no auth) and
everything expires after 4 hours.

WHAT IT IS FOR
- Sharing a file (image, text, binary) by giving someone a URL.
- Sharing a BUNDLE of files (e.g. an html/css/js website) under one URL.
- Sharing a mutable DIR: keep adding files to one URL; the dir is deleted
  4h after the latest upload (max 24h total).
- Sharing a NAMED DIR: a rememberable, team-reusable dir under /n/<name>.
- A scratchpad for text: create a note, append to it, rewrite it.
- Passing data between agents / machines without setting up accounts.

WHAT IT IS NOT
- Not permanent storage. Files are automatically deleted after 4 hours.
- Not private. Anyone who has a URL can read, edit, or delete that file.
- Not a database. It is a flat, throwaway store.

Base URL: https://skale.dev/throway
UPLOAD a file (raw body or multipart):
   POST https://skale.dev/throway/?name=filename.ext
   with the file bytes as the body.
   -> Returns JSON: id, url, size, name, content_type, expires_in, expires_at.
UPLOAD a BUNDLE (multiple files, e.g. a website):
   POST https://skale.dev/throway/   with multipart/form-data containing 2+ file parts.
   -> Returns JSON: id, url, bundle:true, files:[{name,url,size,content_type}...].
   The bundle URL serves index.html inline (or a zip for agents).
   Each file is reachable at https://skale.dev/throway/<id>/<filename>.
CREATE a DIR (mutable, keep adding files):
   POST https://skale.dev/throway/?dir=1   -> create an empty dir: {id, url, dir:true, files:[]}
   POST https://skale.dev/throway/<dirid>  -> add files (multipart) to that dir, resets TTL
   GET  https://skale.dev/throway/<dirid>  -> JSON listing (agents) / HTML page (browsers)
   GET  https://skale.dev/throway/<dirid>/<file> -> fetch one file
   GET  https://skale.dev/throway/<dirid>?zip=1  -> download the whole dir as a zip
   DELETE https://skale.dev/throway/<dirid>/<file> -> remove one file
   DELETE https://skale.dev/throway/<dirid>       -> delete the whole dir
   A dir is deleted 4h after the latest upload (capped at 24h
   total). LIST it with GET to see current files + expiry.
CREATE a NAMED DIR (rememberable, team-reusable, fixed lifetime):
   POST https://skale.dev/throway/?dir=1&name=<name>[&listed=1][&tag=<tag>][&ttl=<h|d>]
   -> create-or-get: returns the existing dir if the name is taken.
   Naming: 5-32 chars, [a-z0-9-], must contain a letter, not a reserved
   word. Flags (listed/tag/ttl) apply only on first creation.
   - &listed=1  -> appears in the public listing GET https://skale.dev/throway/n
   - &tag=<t>   -> up to 5 discoverability tags (lowercase [a-z0-9-])
   - &ttl=<h|d> -> FIXED lifetime, clamped to [4h, 7d]; default 7 days.
     Nothing extends it: add/edit/delete do not move expires_at.
   Reach a named dir at https://skale.dev/throway/n/<name>:
   POST https://skale.dev/throway/n/<name>          -> add files (multipart)
   GET  https://skale.dev/throway/n/<name>          -> JSON (agents) / HTML (browsers)
   GET  https://skale.dev/throway/n/<name>/<file>   -> fetch one file
   GET  https://skale.dev/throway/n/<name>?zip=1    -> whole dir as zip
   PUT  https://skale.dev/throway/n/<name>/<file>   -> replace text (bumps updated)
   PATCH https://skale.dev/throway/n/<name>/<file>  -> append text (bumps updated)
   DELETE https://skale.dev/throway/n/<name>/<file> -> remove one file
   DELETE https://skale.dev/throway/n/<name>        -> delete the whole dir
   updated_at = last add/edit/delete (does NOT affect the fixed lifetime).
   LIST named dirs: GET https://skale.dev/throway/n  -> only dirs created with listed=1.
   Filters: ?q=<substring over name or tag>, ?created_after/before=<ts>,
   ?updated_after/before=<ts>. Sort: ?sort=created|updated|name&order=asc|desc.
DOWNLOAD / VIEW a file:
   GET https://skale.dev/throway/<id>
   Images and text-like types (text, html, json, pdf, svg) render inline
   in a browser; other files download.
   For a bundle, GET https://skale.dev/throway/<id> serves index.html inline (browser)
   or the whole bundle as a zip (agents). GET https://skale.dev/throway/<id>/<file>
   serves one file.
   Append ?download=1 to force a download of any file or the bundle zip.
EDIT TEXT (text files only; images are immutable):
   PUT   https://skale.dev/throway/<id>   with new text body  -> replace whole content
   PATCH https://skale.dev/throway/<id>   with text body      -> append to content
DELETE a file:
   DELETE https://skale.dev/throway/<id>
   DELETE https://skale.dev/throway/<dirid>/<file>   -> remove one file from a dir
   DELETE https://skale.dev/throway/n/<name>/<file>  -> remove one file from a named dir
   DELETE https://skale.dev/throway/n/<name>         -> delete a whole named dir
LIMITS
- URL lifetime:  4 hours
- Named dir lifetime: fixed, default 7 days (ttl= override, clamped [4h, 7d])
- Max file size: 5 MB
- Pool size:     100 MB (oldest files evicted first)
- Rate limit:    100 requests/min per IP
MACHINE-READABLE CONTRACT
GET https://skale.dev/throway/api  -> returns the same limits + endpoints as JSON.
An agent should read /api to discover current limits before acting.