Most of the conversation around APIs.json focuses on public API discovery — making your APIs findable by apis.io and other tools that crawl the open web. But the format is equally useful, and arguably more immediately valuable, when applied to internal API catalogs inside an organization.
If your company runs more than a handful of internal APIs, you already have a discovery problem. Engineering teams build APIs, publish minimal documentation, and then move on. Other teams find those APIs through word of mouth, Slack messages, or by stumbling across an endpoint in someone else's code. New engineers spend days tracking down the authentication details for an internal service that's been running for three years and has exactly one paragraph of documentation in a wiki nobody updates.
APIs.json doesn't solve the underlying discipline problem — you still have to write the documentation — but it gives you a consistent, machine-readable way to describe where that documentation lives and what it contains.
What an Internal APIs.json Looks Like
The format is the same whether the API is public or internal. You publish an apis.json file that contains an array of API entries. Each entry has a name, description, the URL of the API, and a properties array that links to the artifacts associated with it.
{
"name": "Acme Internal API Catalog",
"description": "Internal APIs for the Acme engineering organization",
"url": "https://internal.acme.com/apis.json",
"apis": [
{
"name": "Orders API",
"description": "Manages order creation, status, and fulfillment",
"baseURL": "https://api.internal.acme.com/orders",
"properties": [
{ "type": "OpenAPI", "url": "https://internal.acme.com/specs/orders.yaml" },
{ "type": "Documentation", "url": "https://docs.internal.acme.com/orders" },
{ "type": "Authentication", "url": "https://docs.internal.acme.com/auth" },
{ "type": "ChangeLog", "url": "https://docs.internal.acme.com/orders/changelog" }
]
}
]
}The key insight is that you're not moving your documentation — you're indexing it. The OpenAPI spec stays wherever you already host it. The docs stay in your wiki or developer portal. The APIs.json file just tells tooling where to find all of it.
Network-Level Indexes
For organizations with many teams, you can create team-level or domain-level APIs.json files and then aggregate them into a root-level index using the include field. This mirrors how a large website might have multiple sitemaps aggregated into a sitemap index — each team owns their slice, and the root provides a unified discovery point.
{
"name": "Acme Engineering APIs",
"url": "https://internal.acme.com/apis.json",
"include": [
{ "name": "Platform Team", "url": "https://platform.internal.acme.com/apis.json" },
{ "name": "Commerce Team", "url": "https://commerce.internal.acme.com/apis.json" },
{ "name": "Data Team", "url": "https://data.internal.acme.com/apis.json" }
]
}What You Get Out of It
Once you have a valid APIs.json catalog, several things become possible that weren't before:
- Automated documentation audits — tooling can crawl the index and flag APIs that are missing documentation, change logs, or authentication references without someone manually checking each one.
- Governance enforcement — combined with API Commons rules and rulesets, you can run automated checks that verify each API meets your organization's standards for completeness and quality.
- AI agent integration — tools and agents that need to interact with internal APIs can discover the relevant contracts, authentication patterns, and documentation through a single consistent entry point rather than requiring manual configuration for each API.
- Onboarding acceleration — new engineers can get a complete picture of the internal API landscape through a single URL rather than having to ask around.
Getting Started
The lowest-friction path is to start with your five most-used internal APIs and write a minimal APIs.json entry for each one. You don't need to have every property — even a name, description, base URL, and OpenAPI spec link is a significant improvement over nothing. Once you have the file published and validated, you can incrementally add properties as you document them.
The current spec and JSON Schema are at apisjson.org. The schema validator will tell you immediately if your file has structural issues.