Launch an API for Free: The First Call, the Docs and the Public APIs List

What are you actually launching when you launch an API?

You are launching a promise written in documentation. The service may be excellent, but the person weighing it up sees only a reference, an example and a response. That makes the docs site the landing page and the first request the conversion. Everything else on a launch checklist, the logo, the tagline, the thumbnail, matters less than whether a stranger can copy a snippet and see JSON come back.

It also means an API launch fails quietly. Nobody complains that the sign-up flow was clumsy; they close the tab. So run the first-call test yourself, on a machine with no saved credentials, before you tell anyone.

Can a stranger make a call in sixty seconds?

How you issue access decides the answer, and each choice has a price in friction. The table lays out the common options and the rule of thumb for each.

A sandbox does not have to be the real service. A fixed dataset that behaves like the real responses lets someone evaluate the shape of your API without a credential, and that is the part they want to see. The Show HN guidelines make the same point: they say people give more feedback when a project can be tried without sign-ups or emails.

What should the reference contain?

Publish a machine-readable description alongside the human pages. The OpenAPI Specification defines a standard, language-agnostic interface description for HTTP APIs, so that people and tools can understand a service without reading its source (as its own text puts it). A file in that format feeds interactive reference pages, client generators and test tools, and developers notice when it is missing.

• A runnable example for each endpoint, with a real response body beside it, not a placeholder.
• Every error, in a table: the status code, what caused it and the fix. Most support email comes from the errors you did not document.
• Limits written down: requests per minute, payload size, and what happens at the edge, such as a retry hint.
• A versioning statement, even if it only says “v1 will not break without notice”.
• A status page or at least a changelog with dates, since you cannot show years of uptime and should not pretend to.

What does the public-apis list accept?

The public-apis repository on GitHub is a community-maintained list of free APIs, and its contributing file (read 13 November 2026) is blunt. It says the list is not a marketing tool, that pull requests identified as marketing will not be accepted, and that an API needs full free access, or at least a free tier, and must not depend on buying a device or service. Its own example of a rejection is an API for controlling a smart outlet that works only after you buy the outlet.

Entries use a fixed table row: a name linking to the documentation, a description, the auth type, whether HTTPS is supported and whether CORS is. The rules also say not to put the domain extension in the name, not to end the name with “API”, to have proper documentation, to squash your commits and to target the master branch. Opening a pull request triggers a build that checks the validity of the links in the project.

What does a 30-day plan look like?

1. Days 1 to 7: write the first-call path, the sandbox or key flow, and one worked example. Test it on two people who have not seen it.
2. Days 8 to 14: publish the OpenAPI file, the error table and the limits. Add one client snippet in the two languages your audience uses.
3. Days 15 to 21: invite ten developers from a community you already belong to to build something small. Fix every place they paused.
4. Days 22 to 26: open a public-apis pull request if you qualify, and prepare a Show HN that links the docs, not a sign-up page.
5. Days 27 to 30: announce, answer comments, and read which endpoint people called first.

Where should an API be announced?

Start with the communities of the people who will call it, with a worked example of one problem solved in a few lines. A Show HN post suits an API when it links the docs and the sandbox; the guidelines say landing pages and sign-up pages are off topic, so link the thing a person can use. The Show HN playbook has the details.

Launch the API free on this board to get a public page with a followed link to your docs: no account, one verified email, no queue. Builders who want to wrap an API often browse the API project ideas, and the developer tool ideas show what is requested. For other venues, see where to launch APIs; the developer tool playbook covers the wider picture.

What do you measure?

Count three things from your own logs: the share of new keys that make a successful call within a day, the first endpoint each new developer calls, and the most frequent error response. The first tells you whether access is too hard, the second which part of the docs to put on top, and the third which error needs a better message. Keep the numbers beside the date of each change, as in the launch metrics checklist.