Skip to content

API Reference

Jump to bottom
Kritarth-Dandapat edited this page Jul 19, 2026 · 1 revision

API Reference

Base URL is your deployed Worker's URL (DK_PUBLISH_URL). Two endpoints, no others — any other method/path returns 405 Method Not Allowed.

POST /upload

Store a new HTML draft.

Auth: Authorization: Bearer <SECRET_API_KEY> — required, constant-time compared. Missing or wrong token → 401 Unauthorized.

Body (application/json):

{
  "html": "<!doctype html>...",
  "pin": "1234"
}
Field Type Required Notes
html string yes Must be non-empty after trim. Served back byte-for-byte, unsanitized.
pin string | null no If present, GET /d/:id requires a matching ?key= param.

Responses:

Status Body Meaning
200 { "url": "https://.../d/<id>" } Draft stored
400 { "error": "Field \"html\" is required." } Empty/missing html
400 { "error": "Invalid JSON payload." } Body didn't parse as JSON
401 Unauthorized (text) Missing/invalid bearer token

ID generation: crypto.randomUUID(), hyphens stripped, first 8 hex chars, retried up to 5 times on KV collision (throws if all 5 collide — practically never).

GET /d/:id

Fetch and render a stored draft.

Auth: none, unless the draft was uploaded with a pin — then ?key=<pin> must match (constant-time compare).

Responses:

Status Content-Type Body
200 text/html The stored draft HTML, verbatim
401 text/html Inline lock-screen page (PIN required/wrong)
404 text/html "Draft Not Found" page — unknown or missing ID
500 text/plain "Corrupt draft payload" — KV value failed to parse or missing html field

The lock screen is a small self-contained HTML page with a PIN input; on submit it redirects to the same URL with ?key=<pin> appended (client-side, via window.location.href).

Errors

Any uncaught exception in the top-level fetch handler returns a bare 500 Internal Server Error (text/plain), no body detail, no server-side logging currently wired up (tracked in Security).

Not implemented (yet)

  • No DELETE — drafts cannot currently be removed once published.
  • No listing/index endpoint — IDs are opaque and must be known.
  • No TTL — drafts persist indefinitely in KV.

See Security for the hardening work in progress covering these gaps.

Clone this wiki locally