Cloudflare Reworks API Reference Docs Around OpenAPI

Cloudflare has launched a revised version of its API reference documentation, moving from a custom schema format to the industry-standard OpenAPI specification. The update touches both the content layer and the underlying infrastructure, with the goal of making the API docs more consistent, faster, and easier to integrate into a developer’s workflow.

Why the Docs Needed a Reset

APIs are interfaces for computers, which means they require strict formatting and precise parameters. Documentation is the bridge between that rigidity and a developer who is trying to automate a task such as purging cached content after a site update. If the docs are incomplete or slow, that bridge collapses at the worst possible moment — in the middle of a complex debugging session.

Until now, that was a common experience for Cloudflare API users. The company sees roughly 126 million visits to its API documentation each month, yet the content lived on api.cloudflare.com, a domain that also serves as the API access point. That placement caused performance issues, including long page-load times and poor mobile rendering.

From a maintainer’s perspective, the documentation was difficult to keep current. Internal teams lacked a standardized way to describe their APIs, so the schema files behind each product drifted in structure. The answer, according to Cloudflare, was to adopt the OpenAPI specification and rebuild the site with tooling that works with that framework.

What Has Changed for Developers

The new site at developers.cloudflare.com/api groups endpoints by product and alphabetizes the list to cut down on the “choose your own adventure” feeling of the old navigation. Among the other changes:

  • Mobile support: The docs now render on phones, which Cloudflare says reflects how developers often research APIs before writing code.
  • Fast page search: A keyboard shortcut lets you jump directly to page search, rather than hunting through menus.
  • Authentication guidance: Every endpoint now includes authentication details inline, with links to the broader developer docs on getting started.
  • Examples for every endpoint: Each endpoint includes sample code and explicitly shows which parameters are required, eliminating guesswork about argument structure.

Cloudflare also leaned on internal developers and community moderators from Discord and the Cloudflare Community to test the site before launch. Their feedback helped refine usability and catch bugs ahead of the public deployment.

Inside the Build: Schema and Stack

Cloudflare’s earlier API docs were generated from JSON hyper-schema files. Those files described the APIs, but they were proprietary and didn’t connect well with third-party tools. Engineering teams began migrating to the OpenAPI specification, and the new reference site completes that pivot.

OpenAPI defines how to describe API endpoints, meaning all of Cloudflare’s products now share a consistent schema structure that aligns with a broader industry convention. That unlocks a wider ecosystem of generators, validators, and documentation tools that could not parse the old homegrown format.

On the front end, Cloudflare chose Stoplight Elements, an open-source React framework, for its layout and customization options. Stoplight is used to render code samples across languages including JavaScript, Java, Python, cURL, HTTPie, and wget.

The React app builds and runs on Cloudflare Pages with Pages functions. The function layer optimizes the OpenAPI schema file before it is served to Stoplight’s UI and caches it on Cloudflare’s edge network to cut down on request latency.

Because the schema lives in a GitHub file, teams can update API definitions, and the documentation pulls the new content dynamically. No manual deployment of the site is needed when an endpoint changes. The workflow both automates doc updates and gives Cloudflare another chance to exercise its own Pages and Workers products.

Roadmap: Search, Try-It-Out, Deeper Integration

None of these features are end goals in themselves. Cloudflare plans to add search that spans developer docs, API references, and support content in one query. Mobile layouts will be refined further, and a “try it out” panel is planned to let developers send live test requests directly from the browser without leaving the page.

Longer term, the company aims to tighten the connection between the API reference, how-to guides in the developer docs, and the Cloudflare dashboard. The OpenAPI schema files are also candidates for reuse across client libraries, Terraform provider work, API gateway configuration, and internal tooling such as Trakal.

The main friction left for the engineering teams now is wherever the schema files do not yet follow the standard. For those teams not fully migrated to OpenAPI, this launch represents cleaner headroom to finish the transition.

Cloudflare is asking for direct feedback on the new docs site via a feedback form, specifically on how the new layout suits daily workflows.