API Documentation — witty-404

witty-404 is an open-source, zero-dependency HTTP error engine hosted globally on Cloudflare Workers edge nodes. It delivers standalone error pages with pure CSS animated diagnostics, formatted JSON payloads, ASCII terminal logs, and dynamic social cards in sub-5ms latency.

Zero API Keys Required: All endpoints are public, unauthenticated, and return Access-Control-Allow-Origin: *. Dynamic responses include strict anti-caching headers (Cache-Control: no-store) so every request delivers fresh comedic relief.

60-Second Terminal Quickstart

# 1. Fetch a random JSON joke payload
curl -s https://witty-404.zimkk.workers.dev/json | jq

# 2. Fetch raw ASCII terminal diagnostics
curl -s https://witty-404.zimkk.workers.dev/text

# 3. Roast a broken path
curl -s "https://witty-404.zimkk.workers.dev/roast?path=/api/v1/auth/token"

Live API Tester Console

Test any witty-404 endpoint directly in your browser without leaving the documentation.

RESPONSE OUTPUT: READY

// Click "Send ⚡" to inspect live response

`GET /html` — Standalone Error Scene

Renders a complete, full-bleed standalone HTML 404 page featuring the diagnostic terminal, animated streaming logs, synchronized airplane flight crash sequence, and action buttons.

Query Parameters

PARAM	TYPE	DEFAULT	DESCRIPTION
id	string	random	Specific joke ID (e.g. `plane-crash`, `daves-laptop`, `friday-deploy`).
theme	string	`dark`	Color theme: `dark`, `light`, `matrix`, `glitch`, or `system`.
tag	string	all	Filter random selection by topic: `deploy`, `infra`, `legacy`, `frontend`.

<!-- Embed as full-page 404 handler in any web app -->
<iframe
  src="https://witty-404.zimkk.workers.dev/html?theme=dark"
  style="width: 100vw; height: 100vh; border: none; display: block;"
  title="404 Error Page"
></iframe>

`GET /json` (or `GET /`) — Random Joke Payload

Returns the complete structured JSON payload for a disaster joke, including title, subtitle, diagnostic logs array, footnote, and metadata tags.

{
  "id": "plane-crash",
  "emoji": "✈️💥",
  "title": "Your request took off, found nothing, and did not survive re-entry.",
  "subtitle": "The page was deleted during a refactor that was 'just cleanup'.",
  "logs": [
    "> verifying route exists in routing table...",
    "> route deleted in commit: 3f8a91c ('minor cleanup')",
    "> PR description: 'cleaned up some unused files'",
    "> files deleted: 412",
    "> blaming the intern...",
    "> intern quit in 2023.",
    "> shipping anyway 🚀"
  ],
  "footnote": "HTTP 404 • Flight Recorder Recovered",
  "tags": ["deploy", "refactor", "blame"]
}

`GET /roast` — Dynamic Broken Path Roaster

Substitutes the client's requested URL path into the joke's headline with strict XSS sanitization.

PARAM	TYPE	REQUIRED	DESCRIPTION
path	string	Yes	The missing URL path (e.g. `/api/v2/user/delete`).
format	string	No	Set to `html` to receive a standalone rendered page, or omit for JSON.

`GET /terminal` — Diagnostic Log Array

Returns an array of strings representing terminal diagnostic steps for direct insertion into custom CLI scripts, CI runners, or custom terminals.

[
  "> checking local git log...",
  "> last modified: 6 months ago by dave@acme.corp",
  "> pinging Dave on Slack...",
  "> Dave's status: 'hiking in Patagonia until 2027'",
  "> searching internal wiki...",
  "> wiki page last updated by Dave: 'TODO: document this'",
  "> closing ticket as WONTFIX"
]

`GET /svg` — Dynamic 1200x630 Social Card

Generates a crisp 1200x630 vector SVG image with syntax highlights for use in OpenGraph previews, Discord cards, and GitHub README embeds.

<!-- GitHub Markdown Embed -->
[![404](https://witty-404.zimkk.workers.dev/svg?theme=dark)](https://witty-404.zimkk.workers.dev)

`GET /text` — Plaintext Terminal Banner

Returns a formatted plain text block ready to pipe into terminal scripts, webhooks, or serverless logs without JSON parsing.

=== HTTP 404: Your request took off, found nothing, and did not survive re-entry. ===
The page was deleted during a refactor that was 'just cleanup'.

> verifying route exists in routing table...
> route deleted in commit: 3f8a91c ('minor cleanup')
> PR description: 'cleaned up some unused files'
> files deleted: 412
> blaming the intern...
> intern quit in 2023.
> shipping anyway 🚀

--- HTTP 404 • Flight Recorder Recovered ---

Metadata & Utilities: `/all`, `/stats`, `/count`

Explore the disaster catalog, inspect global hit analytics, and query current database metrics.

ENDPOINT	RESPONSE	DESCRIPTION
`GET /all`	JSON Array	Returns all 25+ disaster joke objects.
`GET /stats`	JSON	Returns the global joke impression leaderboard.
`GET /count`	JSON	Returns total active disaster scenarios count.

Framework Integration Recipes

Next.js 14+ (App Router not-found.tsx)

// app/not-found.tsx
export default function NotFound() {
  return (
    <iframe
      src="https://witty-404.zimkk.workers.dev/html?theme=dark"
      style={{ width: "100vw", height: "100vh", border: "none", display: "block" }}
      title="404 Page"
    />
  );
}

Express.js / Fastify Middleware

// Catch-all 404 handler
app.use((req, res) => {
  fetch("https://witty-404.zimkk.workers.dev/html")
    .then(r => r.text())
    .then(html => res.status(404).type("html").send(html));
});

Vercel Proxy (vercel.json)

{
  "routes": [
    { "handle": "filesystem" },
    { "src": "/(.*)", "dest": "https://witty-404.zimkk.workers.dev/roast?path=/$1&format=html", "status": 404 }
  ]
}

Netlify (_redirects)

# _redirects
/*  https://witty-404.zimkk.workers.dev/html?theme=dark  404