ReadMe Cheat Sheet

Overview

ReadMe is a developer hub platform that transforms API specifications into interactive, customizable documentation. It provides an API explorer where developers can make real API calls directly from the docs, automatic code sample generation in multiple languages, and built-in search. ReadMe goes beyond static documentation by tracking API usage metrics, developer behavior, and error rates to help API providers improve their developer experience.

ReadMe supports OpenAPI (Swagger) 3.x and 2.0 specifications and can auto-sync with your spec hosted on GitHub or a URL. It includes a WYSIWYG editor for guides and tutorials, a changelog feature for communicating API updates, a discussion forum for developer support, and custom branding options. The platform also provides API key management and personalized documentation that shows each developer’s own keys in code samples.

Getting Started

Account Setup

1. Sign up at https://readme.com
2. Create a new project
3. Import your OpenAPI specification
4. Customize branding and appearance
5. Invite team members
6. Publish your documentation

Importing an API Specification

# Upload via API
curl -X POST "https://dash.readme.com/api/v1/api-specification" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "x-readme-version: 1.0.0" \
  -F "spec=@openapi.yaml"

# Sync from URL
curl -X POST "https://dash.readme.com/api/v1/api-specification" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api.example.com/openapi.yaml"}'

# Update existing specification
curl -X PUT "https://dash.readme.com/api/v1/api-specification/SPEC_ID" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "x-readme-version: 1.0.0" \
  -F "spec=@openapi.yaml"

CLI (rdme)

# Install the ReadMe CLI
npm install -g rdme

# Login
rdme login

# Upload OpenAPI spec
rdme openapi openapi.yaml --version=1.0.0

# Validate your spec
rdme openapi:validate openapi.yaml

# Sync guides from markdown files
rdme docs ./docs --version=1.0.0

# Create a new changelog entry
rdme changelogs ./changelogs

# Open your docs in browser
rdme open

Core Features

CLI Commands

Command	Description
rdme login	Authenticate with ReadMe
rdme logout	Remove stored credentials
rdme openapi	Upload or update an OpenAPI spec
rdme openapi:validate	Validate an OpenAPI spec
rdme docs	Sync markdown documentation
rdme docs:single	Upload a single doc page
rdme changelogs	Sync changelog entries
rdme guides	Manage guide pages
rdme categories	List doc categories
rdme versions	Manage API versions
rdme open	Open project in browser

OpenAPI Spec Extensions

# openapi.yaml with ReadMe extensions
openapi: "3.0.0"
info:
  title: My API
  version: "1.0.0"
  x-readme:
    explorer-enabled: true
    proxy-enabled: true
    samples-languages:
      - curl
      - node
      - python
      - ruby
      - java
      - php

paths:
  /users:
    get:
      summary: List Users
      x-readme:
        code-samples:
          - language: python
            code: |
              import requests
              response = requests.get('https://api.example.com/users',
                headers={'Authorization': 'Bearer YOUR_API_KEY'})
              print(response.json())
          - language: javascript
            code: |
              const response = await fetch('https://api.example.com/users', {
                headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
              });
              const data = await response.json();

Markdown Documentation

---
title: "Getting Started"
excerpt: "Learn how to authenticate and make your first API call."
category: "guides"
slug: "getting-started"
order: 1
hidden: false
---

# Getting Started

Welcome to our API! This guide walks you through authentication and your first request.

## Authentication

All API requests require a Bearer token in the Authorization header.

[block:api-header]
{
  "title": "Step 1: Get Your API Key"
}
[/block]

Navigate to **Settings > API Keys** to generate your key.

[block:callout]
{
  "type": "info",
  "title": "Rate Limits",
  "body": "Free plans are limited to 100 requests per minute."
}
[/block]

[block:code]
{
  "codes": [
    {
      "code": "curl -H \"Authorization: Bearer YOUR_KEY\" https://api.example.com/users",
      "language": "bash",
      "name": "cURL"
    },
    {
      "code": "fetch('https://api.example.com/users', {\n  headers: { 'Authorization': 'Bearer YOUR_KEY' }\n})",
      "language": "javascript",
      "name": "JavaScript"
    }
  ]
}
[/block]

Configuration

Project Settings

# Appearance:
- Logo and favicon upload
- Brand colors (primary, links, header)
- Custom CSS injection
- Custom domain (docs.yourdomain.com)
- Navigation style (sidebar or top nav)

# Authentication:
- API key authentication
- OAuth 2.0 support
- JWT (JSON Web Tokens)
- Personalized docs (show user's own keys)
- Login redirect URL

# SEO:
- Custom meta tags per page
- Sitemap generation
- robots.txt configuration
- Canonical URLs
- Open Graph metadata

Custom Domain

1. Go to Project Settings > Custom Domain
2. Enter your domain (e.g., docs.example.com)
3. Add DNS CNAME record:
   docs.example.com → YOUR_PROJECT.readme.io
4. Wait for DNS propagation
5. SSL certificate is provisioned automatically

Versioning

# Create a new version
rdme versions:create --version=2.0.0 --fork=1.0.0

# List versions
rdme versions

# Set a version as stable (default)
rdme versions:update --version=2.0.0 --main=true

# Mark version as deprecated
rdme versions:update --version=1.0.0 --deprecated=true

API Reference

ReadMe API

# Get project metadata
curl "https://dash.readme.com/api/v1" \
  -H "Authorization: Basic YOUR_API_KEY"

# List categories
curl "https://dash.readme.com/api/v1/categories?perPage=20&page=1" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "x-readme-version: 1.0.0"

# Get a doc page
curl "https://dash.readme.com/api/v1/docs/getting-started" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "x-readme-version: 1.0.0"

# Create a doc page
curl -X POST "https://dash.readme.com/api/v1/docs" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-readme-version: 1.0.0" \
  -d '{
    "title": "New Guide",
    "category": "CATEGORY_ID",
    "body": "# New Guide\n\nContent here.",
    "type": "basic",
    "hidden": false
  }'

# Update a doc page
curl -X PUT "https://dash.readme.com/api/v1/docs/new-guide" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-readme-version: 1.0.0" \
  -d '{"title": "Updated Guide", "body": "Updated content."}'

# Delete a doc page
curl -X DELETE "https://dash.readme.com/api/v1/docs/new-guide" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "x-readme-version: 1.0.0"

# Create changelog entry
curl -X POST "https://dash.readme.com/api/v1/changelogs" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Feature: Webhooks",
    "body": "We have added webhook support.",
    "type": "added",
    "hidden": false
  }'

Advanced Usage

CI/CD Integration

# GitHub Actions: sync docs on push
name: Sync API Docs
on:
  push:
    branches: [main]
    paths:
      - "openapi.yaml"
      - "docs/**"
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g rdme
      - name: Sync OpenAPI spec
        run: rdme openapi openapi.yaml --key=${{ secrets.README_API_KEY }} --version=1.0.0
      - name: Sync guide pages
        run: rdme docs ./docs --key=${{ secrets.README_API_KEY }} --version=1.0.0

Metrics and Analytics

# ReadMe Metrics SDK tracks real API calls:

# Node.js
npm install readmeio

# Express middleware
const readme = require('readmeio');
app.use(readme.metrics('YOUR_README_API_KEY', req => ({
  apiKey: req.headers['authorization'],
  label: req.user?.name,
  email: req.user?.email,
})));

# This sends request/response data to ReadMe for:
- API usage dashboards
- Error rate tracking
- Latency monitoring
- Per-endpoint analytics
- Developer-specific usage

Custom Pages and Landing

# Custom page types:
- API Reference: Auto-generated from OpenAPI spec
- Guides: Long-form tutorials and walkthroughs
- Changelog: Release notes and updates
- Recipes: Step-by-step integration guides
- Custom Pages: Freeform content pages

# Page blocks:
[block:callout] — Info, warning, success, danger callouts
[block:code] — Multi-language code tabs
[block:api-header] — Section headers
[block:image] — Images with captions
[block:embed] — Embedded content
[block:html] — Custom HTML
[block:parameters] — Parameter tables

Personalized Documentation

# ReadMe can show each developer their own credentials:

1. Enable "Personalized Docs" in project settings
2. Configure authentication method
3. Developers log in to the docs
4. Code samples auto-fill with their API keys
5. "Try It" requests use their actual credentials
6. Usage metrics are tied to their account

Troubleshooting

Issue	Solution
Spec upload fails	Validate with rdme openapi:validate; check for OpenAPI spec errors
API explorer not working	Enable CORS on your API; check proxy settings in ReadMe
Custom domain not resolving	Verify CNAME DNS record; wait for propagation (up to 48h)
Version not showing	Set version visibility to public; check hidden flag
Sync overwriting changes	Use rdme docs from source of truth; avoid editing in dashboard if syncing
Code samples missing	Add x-readme.code-samples in OpenAPI spec or configure language defaults
Metrics not appearing	Verify Metrics SDK is installed and API key is correct
Search not finding pages	Rebuild search index in project settings; ensure pages are not hidden
Authentication not working	Verify API key format (use Basic auth with base64-encoded key)