{
  "action": "sync",
  "apiKey": "${README_API_KEY}",
  "specPath": "./api/openapi.yaml",
  "version": "1.0"
}

# ReadMe CLI configuration
version: "1.0"
api:
  definition: ./api/openapi.yaml
  name: My API

changelogs:
  directory: ./changelogs

docs:
  directory: ./docs

categories:
  - slug: getting-started
    title: Getting Started
  - slug: api-reference
    title: API Reference
  - slug: guides
    title: Guides

# Login to ReadMe
rdme login

# Sync OpenAPI spec
rdme openapi ./api/openapi.yaml --version=1.0

# Sync with specific ID
rdme openapi ./api/openapi.yaml --id=abc123

# Validate before syncing
rdme openapi:validate ./api/openapi.yaml

# .github/workflows/docs.yml
name: Sync API Docs

on:
  push:
    branches: [main]
    paths:
      - 'api/openapi.yaml'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Sync to ReadMe
        uses: readmeio/rdme@v8
        with:
          rdme: openapi ./api/openapi.yaml --key=${{ secrets.README_API_KEY }} --version=1.0

# Create new version
rdme versions:create 2.0 --fork=1.0

# Update version
rdme versions:update 2.0 --main=true

# List versions
rdme versions

{
  "version": "2.0",
  "from": "1.0",
  "codename": "Major Release",
  "is_stable": true,
  "is_beta": false,
  "is_hidden": false,
  "is_deprecated": false
}

# Create documentation page
rdme docs ./docs --version=1.0

# Create single page
rdme docs:single ./docs/getting-started.md --version=1.0

---
title: Getting Started
slug: getting-started
category: 6123abc456def789
order: 1
hidden: false
---

# Getting Started

Welcome to our API documentation.

## Prerequisites

- API Key (get one from [dashboard](https://app.example.com))
- Node.js 18+ or Python 3.9+

## Installation

[block:code]
{
  "codes": [
    {
      "code": "npm install @example/sdk",
      "language": "bash",
      "name": "npm"
    },
    {
      "code": "pip install example-sdk",
      "language": "bash",
      "name": "pip"
    }
  ]
}
[/block]

---
title: Version 2.0 Release
type: added
hidden: false
createdAt: 2026-01-24
---

## New Features

### OAuth 2.0 Support
We now support OAuth 2.0 authentication in addition to API keys.

### Batch Operations
New batch endpoints for processing multiple items in a single request.

## Improvements

- Improved rate limiting with better error messages
- Enhanced webhook reliability

## Bug Fixes

- Fixed pagination issue in list endpoints
- Resolved timezone handling in date filters

# Sync all changelogs
rdme changelogs ./changelogs

# Sync single changelog
rdme changelogs:single ./changelogs/2.0-release.md

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
  x-readme:
    explorer-enabled: true
    proxy-enabled: true
    samples-enabled: true
    samples-languages:
      - curl
      - node
      - python
      - ruby

servers:
  - url: https://api.example.com/v1
    description: Production
    x-readme:
      explorer-default: true

paths:
  /users:
    get:
      x-readme:
        code-samples:
          - language: javascript
            name: Node.js
            code: |
              const response = await fetch('https://api.example.com/v1/users', {
                headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
              });
        explorer-enabled: true

# Get API metrics via API
curl -X GET 'https://dash.readme.com/api/v1/api-metrics' \
  -H 'Authorization: Basic YOUR_API_KEY' \
  -H 'Content-Type: application/json'

{
  "data": [
    {
      "endpoint": "GET /users",
      "requests": 15234,
      "success_rate": 99.2,
      "avg_latency": 145,
      "error_breakdown": {
        "400": 52,
        "401": 23,
        "500": 3
      }
    }
  ],
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  }
}

{
  "url": "https://api.example.com/readme-webhook",
  "events": [
    "doc.created",
    "doc.updated",
    "changelog.created",
    "api_spec.uploaded"
  ],
  "secret": "your-webhook-secret"
}

app.post('/readme-webhook', (req, res) => {
  const signature = req.headers['x-readme-signature'];

  // Verify signature
  if (!verifySignature(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const { event, doc, project } = req.body;

  switch (event) {
    case 'doc.updated':
      console.log(`Doc updated: ${doc.title}`);
      break;
    case 'api_spec.uploaded':
      console.log('API spec updated');
      break;
  }

  res.status(200).send('OK');
});

[block:code]
{
  "codes": [
    {
      "code": "const client = new Client({ apiKey: 'YOUR_KEY' });\nconst users = await client.users.list();",
      "language": "javascript",
      "name": "JavaScript"
    },
    {
      "code": "client = Client(api_key='YOUR_KEY')\nusers = client.users.list()",
      "language": "python",
      "name": "Python"
    }
  ]
}
[/block]

[block:callout]
{
  "type": "info",
  "title": "Rate Limiting",
  "body": "This endpoint is limited to 100 requests per minute."
}
[/block]

[block:callout]
{
  "type": "warning",
  "title": "Deprecation Notice",
  "body": "This endpoint will be removed in version 3.0."
}
[/block]

{
  "devDependencies": {
    "rdme": "^9.0.0"
  }
}

# Install CLI
npm install -g rdme

# Login
rdme login

# Sync OpenAPI spec
rdme openapi ./api/openapi.yaml --version=1.0

# Sync docs
rdme docs ./docs --version=1.0

# Create version
rdme versions:create 2.0 --fork=1.0

# Sync changelogs
rdme changelogs ./changelogs