Should API documentation be public or private?
When API docs should be public, when they should be gated, and how many teams split them: a public reference with private partner guides.
By Gusenga Thierry ·
The short answer
Usually public, with exceptions. Public API docs let developers evaluate and integrate without talking to you, and hiding them adds no security. Keep them private when the API serves named partners only, when the docs reveal commercial terms or internal systems, or when the API is not stable yet. Many teams split them: public reference, gated partner guides.
The short answer
Public by default, because the people most likely to read your API reference are developers deciding whether to use you, and a sign-in wall stops them before they start. Gate the parts that are genuinely private: the commercial detail, the internal procedures and the endpoints only partners may call.
When public makes sense
- You want integrations. Developers judge an API by its docs before they write to sales. Public docs are also what search engines and AI assistants can read and recommend.
- The API is the product. Payment, messaging and logistics APIs are chosen on how quickly a developer can make a first call.
- The endpoints are already discoverable. A mobile or web app that calls the API reveals it to anyone who opens the network tab.
When private makes sense
- The readers are a known group: carriers, resellers or a single client under contract.
- The docs carry commercial terms: rate cards, service levels, contacts, pricing per partner.
- They describe internal systems: runbooks, admin endpoints, how the infrastructure is put together.
- The API is not stable yet, and you would rather not support people who found it early.
The split most teams end up with
| Content | Audience | Access |
|---|---|---|
| API reference, quickstart, authentication, errors, changelog | Any developer | Public |
| Onboarding, integration specs, service levels, contacts | Named partners | Gated, by name |
| Runbooks, internal endpoints, support procedures | Your own staff | Gated, by team or repository |
The same split works whatever tool publishes the docs: two or three sites, or one site with sections behind different rules.
How to set up the split
- Keep each audience's docs in its own folder, for example
docs/developers,docs/partnersanddocs/operations. - Keep the public OpenAPI file free of partner-only endpoints.
- Publish each folder with its own access rule.
- Put examples against a sandbox server, never production.
- Review the public folder before each release for internal hostnames and real identifiers.
Doing it with DocuGate
DocuGate publishes folders of markdown from a GitHub repository as spaces, each with one access mode: Public, Repo access (whoever can open the repository on GitHub) or Allowlist (named GitHub logins or email addresses). Several spaces can read different folders of one repository. If the repository holds an OpenAPI file, the space gains an API reference with a page per endpoint, examples in curl, JavaScript and Python, and a console that sends calls from the reader's browser. That reference is on every plan and as gated as the rest of the space.
The logistics industry setup creates this three-space split for you. API keys for your developers are part of Enterprise, from $29/mo, and need the space on your own domain, which is still being built.
Questions people also ask
Does hiding API docs make the API more secure?
No. Anyone who can reach the API can discover its endpoints, so security has to come from authentication and authorisation on the API itself. Private docs reduce noise and protect commercial detail; they do not protect the API.
What should never go in API docs, public or private?
Real keys, tokens, passwords and customer data. Use placeholders in examples, and a sandbox server for anything a reader can run.
Can one OpenAPI file serve both public and private docs?
Yes, if you publish it to a public space and keep partner-only guides in a separate, gated space. Endpoints that only partners may call are often better in a second spec file, so the public reference does not list them.
Do developers need an account to read public API docs?
They should not. Asking for a sign-in before someone can read the reference loses the people still deciding whether to integrate. Ask for an account at the point they need a key.
Read next
- How to share API documentation with clients: Ways to give clients and partners your API docs without making them public or handing over repository access, and what each costs you in upkeep.
- How do I share docs from a private repo without giving repo access?: Ways to let clients, partners or staff read the documentation in a private GitHub repository without adding them to the repository.
- A ReadMe alternative for private API docs: DocuGate and ReadMe compared on price, private docs and API reference, as of October 2026, including when ReadMe is the better choice.
- Developers, partners and operations from one repository: How we set up documentation for three audiences from one repository in DocuGate's logistics setup, with a different access rule for each.
Get started with DocuGate, free.