canonical: https://jentic.com/apis/readme.io/readme # Readme API Endpoints The ReadMe API publishes and maintains the content of a ReadMe developer hub: guide docs, changelog posts, custom pages, and uploaded API specifications. It creates, updates, searches, and deletes docs by slug within a docs version selected through the x-readme-version header, and reads a category with the docs nested inside it. Changelog entries carry a type such as added, fixed, or deprecated, and docs versions can be forked from an existing version and flagged as beta, stable, hidden, or deprecated. ## For AI agents Write and update ReadMe guide docs, changelog posts, and custom pages, upload or replace OpenAPI definitions, and manage docs versions for a ReadMe project. ## Scope Does not host the API itself, run API requests, or report page-view analytics. Use for publishing ReadMe docs, changelogs, custom pages, specifications, and versions only. ## Capabilities - Publish a guide doc into a category with a title and Markdown body, then revise it by slug - Search a project's docs for a phrase within a chosen docs version - Post changelog entries tagged as added, fixed, improved, deprecated, or removed - Upload a new OpenAPI or Swagger definition as multipart spec data, or replace an existing one by id - Fork a new docs version from an existing one and mark it beta, stable, hidden, or deprecated - Read a category and the docs nested inside it to audit structure before editing - Build standalone custom pages from Markdown or HTML for content outside the guides ## Use cases ### Agent-maintained developer docs through Jentic A coding agent that has just shipped a change can update the matching ReadMe guide without a human copying text into the dashboard. Through Jentic the agent searches for 'update a ReadMe doc', loads the update operation with its input schema, and sends the new Markdown body for the doc slug with the x-readme-version header set, while the project credential is injected at call time. The doc stays in its category and version, and the edit is a single scoped call. Example prompt: Call PUT `/docs/getting-started` with x-readme-version 'v1.0' and a body containing the revised Markdown, then GET `/docs/getting-started` to confirm the new content ### Release notes to the changelog When a release is tagged, a pipeline posts its notes to the ReadMe changelog so developers see what changed. The changelog create operation takes a required title and body plus a type such as added, fixed, improved, deprecated, or removed, and a hidden flag to stage a post before it goes live. Existing posts can be corrected or removed by their slug. Example prompt: Call POST /changelogs with title 'Webhook retries', type 'improved', hidden false, and a Markdown body describing the change ### Keep the API reference in sync with the spec Teams that generate their OpenAPI file in CI push it to ReadMe so the reference section matches the code. The API specification upload accepts the file as multipart spec data under the docs version given in x-readme-version, and the update operation replaces an existing specification by its id. Listing specifications first returns their ids so the pipeline updates the right one instead of creating a duplicate. Example prompt: Call GET /api-specification with x-readme-version 'v2.0' to find the spec id, then PUT `/api-specification/{id}` with the new openapi.json as the spec form field ### Docs versioning for a major release Before a breaking release, a docs team creates a new docs version forked from the current one so the old content stays available. The version create operation requires the new version and the from version to copy, and accepts codename plus is_stable, is_beta, is_hidden, and is_deprecated flags. Later the old version can be marked deprecated through the update operation. Example prompt: Call POST /version with version '2.0', from '1.0', is_beta true, and is_stable false, then GET /version to confirm it was created ## Key endpoints | Method | Path | Description | | --- | --- | --- | | PUT | `/docs/{slug}` | Update a doc | | POST | `/docs` | Create a doc | | POST | `/docs/search` | Search docs | | POST | `/changelogs` | Create a changelog post | | POST | `/api-specification` | Upload an API specification | | PUT | `/api-specification/{id}` | Replace an API specification | | POST | `/version` | Create a docs version | | GET | `/categories/{slug}/docs` | List docs in a category | ## Key resources - **Docs** — Guide pages created in a category, read, updated, searched, and deleted by slug within a docs version - **Changelogs** — Release-note posts with a type such as added or fixed, listed with pagination and edited by slug - **API Specification** — Uploaded OpenAPI or Swagger definitions listed, uploaded, replaced, and deleted by id - **Versions** — Docs versions forked from an existing version with stable, beta, hidden, and deprecated flags - **Custom Pages** — Standalone Markdown or HTML pages outside the guide structure - **Categories** — Category metadata and the docs nested within a category ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 42 / 100 - **Maturity:** Foundational - **Dimensions:** - Foundational Compliance: 99 / 100 - Developer Experience & Jentic Compatibility: 63 / 100 - AI-Readiness & Agent Experience: 55 / 100 - Agent Usability: 94 / 100 - Security: 10 / 100 - AI Discoverability: 100 / 100 - **View full report:** https://jentic.com/apis/readme.io/readme/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring ReadMe by hand means sending HTTP Basic credentials on every call, adding the x-readme-version header to the docs and specification operations, and building multipart uploads for spec files. Through Jentic you install once, import ReadMe from the API Directory, store the credential once, and your agent calls it. - **Permission scoping:** ReadMe puts the doc slug in the URL path (`/docs/{slug}`), and changelogs, custom pages, and versions follow the same pattern, so a rule can bound your agent to one page plus the operations you pick. You choose the operations it may call, so destructive ones like deleting a version or an API specification are not included unless you add them. - **Credential handling:** Your ReadMe credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'update a ReadMe doc' or 'upload an OpenAPI file to ReadMe', and Jentic returns the matching ReadMe operation with its input schema, including the x-readme-version header and required body fields. ## Related APIs - **Mintlify API** — Docs platform alternative to ReadMe for hosted developer documentation - **Beamer API** — Product changelog and announcement feed - **Postman API** — Collections, environments, and API definitions in Postman - **GitHub v3 REST API** — Repositories, releases, and files where the OpenAPI source lives ## FAQ ### What authentication does the ReadMe API use? Per its OpenAPI spec, the ReadMe API uses HTTP Basic authentication, declared under a security scheme named apiKey, and every operation in this spec requires it. Docs, category, and specification operations also require the x-readme-version header naming the docs version, such as v3.0. Through Jentic the credential is stored by your own instance and attached at call time, so the agent never handles it. ### Can I upload an OpenAPI file to ReadMe with this API? Yes. POST /api-specification uploads the definition as the multipart spec field under the docs version in x-readme-version, and PUT `/api-specification/{id}` replaces an existing one. Use GET /api-specification to find the id first. The older /swagger operations are marked deprecated in the spec, so use the api-specification operations instead. ### What are the rate limits for the ReadMe API? The OpenAPI spec does not specify rate limits. Check ReadMe's developer reference at https://docs.readme.com/ for current limits. ### Is there a ReadMe MCP server? You don't need an MCP server to give your agent ReadMe. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls the docs, changelog, and version operations on demand without loading extra tool definitions into its context. ### How do I publish a changelog post to ReadMe through Jentic? Search Jentic for 'post a ReadMe changelog entry', load the POST /changelogs operation, and run it with a title, a Markdown body, and a type such as added or fixed. Set hidden to true if you want to review it in the dashboard before it goes live. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Can I limit what my agent is allowed to do with the ReadMe API? Yes. As an example, write a rule that allows only GET and PUT on `/docs/getting-started`, so the agent can read and revise that one guide but cannot delete docs, remove versions, or replace your API specification, and every call it makes is logged.