Readme API Endpoints
Browse all Readme APIs42
AI ReadinessFoundational (D-)42/100
Community OpenAPI document · agent-readyMarketingContent Managementbasic31 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For 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.
Use for: Publish release notes to the ReadMe changelog, Update the body of the getting-started doc in ReadMe, Search the ReadMe docs for pages that mention webhooks, I want to upload our new OpenAPI file to ReadMe
Not supported: 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.
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.
Install Jentic One Beta
Connect the API Endpoints to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the API Endpoints, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Freadme.io%2Freadme" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Freadme.io%2Freadme" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with API Endpoints API.
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
Patterns agents use API Endpoints API for, with concrete tasks.
★ 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.
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.
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.
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.
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
31 endpoints — the readme api publishes and maintains the content of a readme developer hub: guide docs, changelog posts, custom pages, and uploaded api specifications.
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
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
Jentic AI Readiness Score
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.
A
API Endpoints
- Foundational (D-)42/100
99
Foundational Compliance63
Developer Experience & Jentic Compatibility55
AI-Readiness & Agent Experience94
Agent Usability10
Security100
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.0
Show dimension breakdown
99
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: A+Signals: 4
98%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
100%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
100%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
63
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: B-Signals: 4
7%
Example Density
How richly the API is illustrated with examples.
100%
Example Validity
Percentage of examples that conform to their schemas.
45%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
55
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: CSignals: 4
70%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
100%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
50%
Summary Coverage
Coverage of summaries across operations/tags/info.
94
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A+Signals: 1
94%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
10
Security
Trust, risk posture, and security compliance.
Grade: FSignals: 1
10%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
100
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: A+Signals: 1
100%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using API Endpoints API through Jentic.
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.
GET STARTED