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 DIR: a long-lived, nameable collection under /d/<key> that an
  agent can keep adding to / editing over days, with a lightweight edit
  history. Addressable by an opaque id or a memorable 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 their TTL.
- 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.

LIFETIME (optional):
   POST https://skale.dev/throway/?name=x.txt&ttl=24h
   -> default is 4h; &ttl=<h|d> extends a single file, clamped to
      [4h, 14d] (MAX 14 days).

SHARE NAME (optional):
   POST https://skale.dev/throway/?share=my-note
   -> store the upload under a chosen, memorable name (create-or-get, like a
      named dir) at /d/my-note, instead of a random hex id. Rules: 5-32 chars
      [a-z0-9-], >=1 letter, not a reserved word. Sliding lifetime (default
      7d, &ttl= clamped [4h,14d]).

DOWNLOAD ONCE (optional, single files only):
   POST https://skale.dev/throway/?once=1
   -> burn-after-reading: the file auto-deletes after the first download.
      A second GET returns 404. Not combinable with &share= (dirs).

TAGS on uploads/imports (filter+sort later):
   POST https://skale.dev/throway/?name=x.pdf&tag=papers&tag=2026
   -> up to 5 tags per file ([a-z0-9-], 1-24 chars); returned in the JSON.
   Update later:  POST https://skale.dev/throway/<id>?tag=a&untag=b
   Browse/filter: GET  https://skale.dev/throway/browse?tag=papers&q=&sort=created&order=desc
   (sort: created | name | size | expires)

IMPORT FROM A URL (server-side fetch):
   POST https://skale.dev/throway/?url=<encoded-url>[&name=<filename>]
   -> server downloads the document and stores it like a normal upload.
   Max 5MB; private/loopback hosts are blocked.

STORE A URL AS A DOCUMENT (link doc):
   POST https://skale.dev/throway/?url=<encoded-url>&link=1[&name=<name>]
   -> stores a tiny editable HTML redirect page for that URL.
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 (one unified concept, addressable by id or name):
   POST https://skale.dev/throway/?dir=1            -> unnamed dir, opaque hex id
   POST https://skale.dev/throway/?dir=1&name=<name>[&listed=1][&tag=<tag>][&ttl=<h|d>]
        -> named dir (create-or-get); flags apply only on first creation
   Naming: 5-32 chars, [a-z0-9-], must contain a letter, not a reserved word.
   - &listed=1 -> appears in the public listing GET https://skale.dev/throway/d
   - &tag=<t>  -> up to 5 discoverability tags (lowercase [a-z0-9-])
   - &ttl=<h|d> -> SLIDING lifetime, clamped to [4h, 14d] (MAX 14 days);
     default 7 days.
     Each add/edit/append/delete slides expires_at forward by ttl (capped at
     30 days total from creation). An active dir keeps living; an idle one
     dies ttl after its last activity.
   Reach a dir at https://skale.dev/throway/d/<key> (key = id or name):
   POST https://skale.dev/throway/d/<key>          -> add files (multipart)
   GET  https://skale.dev/throway/d/<key>          -> JSON (agents) / HTML (browsers)
   GET  https://skale.dev/throway/d/<key>/<file>   -> fetch one file
   GET  https://skale.dev/throway/d/<key>?zip=1    -> whole dir as zip
   PUT  https://skale.dev/throway/d/<key>/<file>   -> replace text (bumps updated)
   PATCH https://skale.dev/throway/d/<key>/<file>  -> append text (bumps updated)
   DELETE https://skale.dev/throway/d/<key>/<file> -> remove one file
   DELETE https://skale.dev/throway/d/<key>        -> delete the whole dir
   GET  https://skale.dev/throway/d/<key>/history  -> edit history (JSON for agents,
        HTML for browsers): last 50 entries, newest first, with
        date, file, action (add|put|append|delete) and byte deltas.
   updated_at = last add/edit/delete (slides expires_at forward).
   LIST dirs: GET https://skale.dev/throway/d  -> 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

Every upload/listing response includes an "editable" boolean per file, so an
agent can tell at a glance whether PUT/PATCH will work: true for text/* and
application/json, false for images and other binaries. A bundle or dir object
itself is editable:false; only its text/* or application/json files are.
DELETE a file:
   DELETE https://skale.dev/throway/<id>
   DELETE https://skale.dev/throway/d/<key>/<file>  -> remove one file from a dir
   DELETE https://skale.dev/throway/d/<key>         -> delete a whole dir
LIMITS
- URL lifetime:  4 hours by default; single files can be extended
  via &ttl=<h|d> when uploading, clamped to [4h, 14d] (MAX 14 days)
- Dir lifetime: sliding, default 7 days, MAX 14 days via ttl= (clamped
  [4h, 14d]);
  each add/edit/delete slides expires_at forward, capped at 30 days total
- Max file size: 5 MB
- Pool size:     100 MB (oldest files evicted first)
- Rate limit:    100 requests/min per IP
- Dir history:   last 50 entries kept per dir

PERSISTENCE — how long something lives, per type (also in each response's
"persistence" block):
- single file:  4h by default (extendable_by:none; &ttl= up to 14d
                set at upload time; &share= stores it under a chosen name
                with a sliding 7d default lifetime instead; &once=1 = burn-
                after-reading, auto-deletes after the first download)
- dir:          sliding lifetime (default 7d), extendable by activity
                (extendable_by:activity), capped at 30 days total
- bundle:       fixed 4h snapshot, not extendable (extendable_by:none)
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.