Documentation

Everything you need to know about making terrible decisions programmatically.

Getting Started

Using StupidAPIs is simple. Pick an API, make a request, receive questionable wisdom. No setup required. No SDK needed. No regrets guaranteed (regrets not guaranteed).

curl "https://api.stupidapis.com/magic-8-ball/ask?question=Should+I+read+the+docs"

That's it. You're now a StupidAPIs developer. Update your LinkedIn.

Base URL

All API endpoints are available at:

https://api.stupidapis.com

Each API has its own path prefix. For example, the Magic 8 Ball lives at /magic-8-ball/.

Authentication

None required. We trust you. This is our first mistake.

We don't need your API key, your OAuth token, or your firstborn child. Just make requests. We believe in you, even if our APIs don't.

Rate Limits

Rate limits depend on whether an API has an LLM behind it. Please don't be weird about it.

Type	Limit
LLM-powered APIs	5 req/min per IP
Deterministic APIs	Unlimited (please still don't be weird)

When rate limited, you'll receive a 429 Too Many Requests with X-RateLimit-Remaining and X-RateLimit-Reset headers.

LLM-Powered vs. Deterministic

Some APIs use Claude Haiku for response generation. Others are pure deterministic chaos. Here's the breakdown:

Uses Haiku: Emoji Oracle, Startup Oracle, Buzzword Density (roast mode), Passive Aggression, Could Have Been Email, Jargon Translator, Tarot Draw, Mercury Number, Chaos Index (interpretation), Scream Void, The Committee (minutes), Yesterday's Number (tasting notes)

Pure deterministic: Magic 8-Ball, Ship on Friday, Schrödinger's Boolean, Send That Email, Take the Meeting, Always Seven, ISS Number, Phoenix Number, Temperature Random

The LLM-powered APIs produce different responses each time. The deterministic APIs produce the same response to the same inputs. Both are equally unhelpful.

Request Format

All APIs accept both GET and POST requests.

• GET: Parameters as query strings
• POST: Parameters as JSON body with Content-Type: application/json

All responses are JSON. Always. Even the errors. Especially the errors.

MCP (Model Context Protocol)

Every API is also available as an MCP tool for AI assistants. The MCP endpoint lives at:

POST https://api.stupidapis.com/mcp          # All tools
POST https://api.stupidapis.com/{slug}/mcp   # Single API pack

This means you can give your AI assistant the ability to make terrible decisions on your behalf. Delegation at its finest.

Error Codes

Code	Meaning	What We Say
200	Success	Your request worked. The advice, however, may not.
400	Bad Request	You sent us something we can't parse. Impressive, given how low our standards are.
404	Not Found	That API doesn't exist. Yet. We're always working on new bad ideas.
429	Rate Limited	Slow down. Whatever you're doing, it can wait. Especially if it's consulting the Emoji Oracle.
500	Server Error	We broke something. This is the most honest our APIs have ever been.
418	I'm a Teapot	You asked Schrödinger's Boolean to reopen a collapsed wavefunction. Physics said no.

SDKs

We don't have any. Use curl like a person.

If you want a wrapper library, you're welcome to write one. We recommend naming it something like stupid-sdk and publishing it to npm with zero tests. That's on brand.

FAQ

Is this real?

The APIs are real. The advice is not. The infrastructure costs are, unfortunately, very real.

Can I use this in production?

You can. Should you? Consult our "Should I Ship on Friday" API. (The answer is no, but the API will tell you that.)

Is there a free tier?

Yes. It's called the Cheap Bastard plan. 5 LLM requests per minute, unlimited deterministic APIs, zero dollars. See Pricing for the tiers where we pretend to be a real business.

How do I report a bug?

Open a GitHub issue. Describe what you expected and what you got. We'll fix it if it's actually broken. If our API gave you bad advice, that's a feature.

Can I contribute a Stupid API?

Absolutely. Check the GitHub repo for contribution guidelines. The only requirement is that your API must be genuinely, confidently, unrepentantly stupid.

What Is This?

StupidAPIs is a collection of deliberately absurd REST APIs that do things no reasonable person would ask a computer to do. Each API is fully functional, well-documented, and completely unhelpful.

Every API is also available as an MCP server (for AI tool use) and an OpenClaw skill. Because if you're going to build something stupid, you should build it for every platform.

This project exists because the world has enough serious APIs. What it needs is more APIs that tell you not to deploy on Friday, interpret your life through emoji, and evaluate your startup ideas with brutal honesty.

We're not sorry.