Docs

This page is the operational manual. For positioning and identity, see /about. For the endpoint inventory, see /catalog.

How it works

One edge function handles every request to every host, dispatching by hostname:

• catastrophic.io → static Hugo assets (this site) and the /tools/ cluster
• chaos.catastrophic.io → the chaos endpoint dispatcher
• not.catastrophic.io → the well-formed-counterpart dispatcher, plus /infinite/ (a not.-only wildcard with no chaos counterpart)
• bots.catastrophic.io → the chaotic well-known-file dispatcher

State, where it exists, lives in three places: a per-edge Cache API for short-lived stickiness (e.g. /retry-mismatch, custom endpoint schemas), a key-value store for cross-edge state (usage gating, circuit-breaker counters, custom endpoint pointers), and Workers AI for a handful of opt-in non-deterministic modes. Everything else is deterministic.

There is no database, no R2, no Durable Objects, no auth, no per-client state beyond an IP-keyed rate-limit bucket and the temporary custom endpoint store.

The developer workflow

The intended flow is build against not., flip to chaos. or bots. to test adversity.

Before pointing your client at any endpoint, the /tools/ cluster on the hub shows you what your client looks like from the server side — IP, headers, connection metadata, HTTP version, TLS version and cipher, Accept-Language parsing, encoding negotiation. A useful baseline before the chaos starts.

Step one — develop against the well-formed counterpart:

curl -s https://not.catastrophic.io/json
# {"ok": true, "data": [...]}

Step two — flip the hostname. Same path:

curl -sD - https://chaos.catastrophic.io/json
# HTTP/2 200
# X-Chaos-Payload: json
# X-Chaos-Json-Mode: trailing-garbage
# ...
# {"ok": true, "data": [...]}<trailing garbage here>

Your client now sees a body that starts like the one it learned to parse and then becomes hostile. Inspect the X-Chaos-* headers to know which mode chose your fate.

Custom endpoints

The playground’s Custom tab lets you upload a JSON Schema (JSON, YAML, or TOML) and get a temporary endpoint pair keyed to your schema:

• not.catastrophic.io/custom/<guid> — valid examples generated from your schema
• chaos.catastrophic.io/custom/<guid> — the same schema with one targeted mutation per request: dropped required field, type shift, extra unknown field, enum violation, or format violation

The flip-hostname workflow then works against your own contract — same two URLs, same one-character hostname swap.

Custom endpoints are IP-pinned: only the IP that uploaded the schema can serve from them. They expire after ten minutes; expired or removed endpoints return 410 Gone. Re-upload via the playground to get a fresh pair.

Response headers follow the same X-Chaos-* pattern as built-in endpoints. X-Chaos-Custom-Expires-At gives the expiry timestamp; X-Chaos-Counterpart cross-links the two hosts as usual.

The agent workflow

Coding agents and MCP clients have a few extra surfaces:

• Markdown content negotiation. Send Accept: text/markdown on any hub or variant page that has a Markdown alternate. You get the page body as Markdown instead of HTML — friendlier to feed into a model. Pages without an alternate return HTML; check Content-Type on the response.
• Agent skills index. /.well-known/agent-skills on hub publishes a machine-readable index of the chaos modes and what each one does, conforming to the agent-skills RFC.
• MCP server card. /.well-known/mcp on the chaos host advertises an MCP-compatible card. (The card itself can also misbehave — that’s /.well-known/mcp?mode=....)
• /.well-known/chaos. A discovery document on the chaos host that describes the site and its modes. Supports ?ai=true for an LLM-generated variant.
• api-catalog (RFC 9727). /.well-known/api-catalog on hub lists the three OpenAPI specs.
• Content-Signal. Hub HTML responses carry Content-Signal headers per the agent-discovery spec, so crawler-aware agents can pick up the intended use signal.

If you’re wiring catastrophic.io into an agent toolchain, the discovery documents above are the right entry points — they describe the site the way the site wants to be described.

Response headers

Every chaos response carries headers describing what just happened. There are dozens of them, but they fall into a small set of patterns:

Pin assertions in your tests to these headers, not to body shapes you observed once.

OpenAPI specs

Three specs, one per chaos host. YAML is canonical; JSON is derived.

• openapi.yaml / openapi.json — chaos.catastrophic.io
• not-openapi.yaml / not-openapi.json — not.catastrophic.io
• bots-openapi.yaml / bots-openapi.json — bots.catastrophic.io

The OpenAPI specs are the closest thing to a contract this site offers. Endpoint behavior can change; the spec entry is what’s versioned.

Rate limits

Sixty requests per minute per IP, per host — chaos., not., and bots. each have an independent bucket. The /infinite endpoint on not. is held to a stricter ten requests per minute per IP in its own bucket, because /infinite is the only endpoint with truly unbounded URL cardinality and needs a tighter ceiling against URL-cycling abuse.

A request over the limit returns 429 Too Many Requests with a Retry-After header. Static Hugo pages on hub are exempt; only endpoint paths are rate-limited.

Limitations

• Workers AI daily budget. The handful of endpoints that use Workers AI share a single daily Neuron budget. When it’s exhausted, those endpoints fall back to deterministic content and set X-Chaos-Ai-Source: fallback. The fallback content is still on-mode for that endpoint; it just isn’t model-generated.
• No per-client state. Beyond the IP-keyed rate limit, nothing is remembered between requests. Endpoints that need short-lived state (e.g. /retry-mismatch for the second-attempt match) use the per-edge cache, which means state is per edge PoP — hitting two edges produces two independent state machines.
• No auth. There is no API key, no signed request, no per-user quota. Everything is per-IP.
• No SLA. The site can go down, change, or remove endpoints without notice.
• Use it on your own systems only. Don’t proxy other people’s traffic through it; don’t aim it at infrastructure you don’t own.