ReadMe

https://docs.readme.com/main/docs
Admin
ReadMe is a documentation platform that helps teams create, manage, and maintain API documentation...
Tokens:56,707
Snippets:1,014
Trust Score:9.4
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Gem

Source: https://docs.readme.com/main/docs/ruby-api-metrics-set-up

Run the bundle install command to install the newly added gem.

```bash
bundle install
```

--------------------------------

### Example YAML Frontmatter for Guides

Source: https://docs.readme.com/main/docs/rdme

Standard YAML frontmatter structure required for syncing documentation pages.

```markdown
---
title: Syncing Docs via CLI / GitHub
category:
  uri: Syncing Your Content
content:
  excerpt: Update your docs automatically with `rdme`, ReadMe's official CLI and GitHub Action!
---

With ReadMe's support for...
```

--------------------------------

### Install ReadMe SDK

Source: https://docs.readme.com/main/docs/sending-logs-to-readme-with-nodejs

Install the required package via npm.

```bash
npm install readmeio --save
```

--------------------------------

### Prompt for API exploration

Source: https://docs.readme.com/main/docs/your-projects-mcp-server

Example prompt for an AI assistant to provide a quick-start guide for an unfamiliar API.

```text
I've never used this API before. Use MCP tools to give me a quick-start
guide: what endpoints exist, what auth I need, and a curl example.
```

--------------------------------

### Install Required Libraries

Source: https://docs.readme.com/main/docs/amazon-api-gateway-webhook

Commands to install the ReadMe SDK and AWS SDK for various programming languages.

```C#
dotnet add package ReadMe.Metrics
dotnet add package AWSSDK.APIGateway
```

```Node
npm install --save readmeio
npm install --save @aws-sdk/client-api-gateway
```

```Python
pip install readme-metrics
pip install boto3
```

```Ruby
gem "readme-metrics"
gem "aws-sdk"
```

--------------------------------

### Install ReadMe.Metrics NuGet Package

Source: https://docs.readme.com/main/docs/net-setup

Use the .NET CLI to add the ReadMe.Metrics package to your project.

```bash
dotnet add package ReadMe.Metrics
```

--------------------------------

### Install ReadMe Metrics for Flask

Source: https://docs.readme.com/main/docs/python-flask-api-metrics

Install the required package via pip or add it to your requirements.txt file.

```bash
pip install "readme-metrics[Flask]"
```

--------------------------------

### Install ReadMe Metrics for Django

Source: https://docs.readme.com/main/docs/python-django-api-metrics

Install the required package via pip or add it to your requirements.txt file.

```bash
pip install "readme-metrics[Django]"
```

--------------------------------

### Migrate to readme.log() in Node.js

Source: https://docs.readme.com/main/docs/sending-logs-to-readme-with-nodejs

Examples showing the transition from framework-specific middleware to the universal log method introduced in v6.0.

```js
app.use(
  readme.express(readmeAPIKey, req => ({
    apiKey: req.<apiKey>,
    label: req.<userNameToShowInDashboard>,
    email: req.<userEmailAddress>,
  }))
);
```

```js
app.use((req, res, next) => {
  readme.log(readmeAPIKey, req, res, {
    apiKey: req.<apiKey>,
    label: req.<userNameToShowInDashboard>,
    email: req.<userEmailAddress>,
  });

  return next();
});
```

--------------------------------

### Define corresponding response examples

Source: https://docs.readme.com/main/docs/openapi-extensions

Link a response example to a code sample using the examples map approach in the responses object.

```yaml
responses:
  '200':
    description: OK
    content:
      application/json:
        examples:
          TestExample: # the identifier is on this line!
            summary: An example of a cat
            value:
              name: Fluffy
              petType: Cat
              color: White
              gender: male
              breed: Persian
```

--------------------------------

### Configure ReadMe Middleware Options

Source: https://docs.readme.com/main/docs/sending-logs-to-readme-with-nodejs

Example configuration object for the ReadMe middleware, demonstrating common settings like denylist, development mode, and base URL.

```js
{
  denyList: ['password', 'secret'],
  development: true,
  fireAndForget: true,
  bufferLength: 1,
  baseLogUrl: "https://example.readme.com"
}
```

--------------------------------

### Prompt for API client generation

Source: https://docs.readme.com/main/docs/your-projects-mcp-server

Example prompt for an AI assistant to generate a Python script for interacting with the Petstore API.

```text
Write a Python script that lists all pets with status "available"
and lets me add a new pet by name.
```

--------------------------------

### Configure ReadMe Middleware in appsettings.json

Source: https://docs.readme.com/main/docs/net-setup

Example configuration object for the ReadMe middleware, including API key and options for redaction and development mode.

```json
{
  "apiKey": "abcd123",
  "options": {
    "denyList": ["password", "secret"],
    "development": true,
    "baseLogUrl": "https://example.readme.io"
  }
}
```

--------------------------------

### GET /mcp

Source: https://docs.readme.com/main/docs/your-projects-mcp-server

Connect to the ReadMe MCP server to expose your API documentation and tools to AI assistants.

```APIDOC
## GET /mcp

### Description
Connects to the ReadMe MCP server. You can append query parameters to customize the behavior, such as selecting a specific branch, filtering by project, or overriding server variables.

### Method
GET

### Endpoint
https://your-project.readme.io/mcp

### Parameters
#### Query Parameters
- **branch** (string) - Optional - Connect to a specific version branch.
- **project** (string) - Optional - Limit to a single project (Enterprise only).
- **token** (string) - Optional - Authenticate to a private project using a site password or ReadMe API key.
- **server** (integer) - Optional - Select a server from your API spec by index (zero-based).
- **server_variables** (string) - Optional - Override a server variable in the format KEY=VALUE. Repeat for multiple variables.
```

--------------------------------

### Install ReadMe Metrics Package

Source: https://docs.readme.com/main/docs/sending-logs-to-readme-with-php-laravel

Use Composer to add the ReadMe metrics package to your Laravel project.

```bash
composer require readme/metrics
```

--------------------------------

### Category URI Formats

Source: https://docs.readme.com/main/docs/rdme

Examples of specifying the category URI using either the full path or the category title.

```markdown
---
category:
  uri: /branches/3.0/categories/guides/documentation
title: ...
---
```

```markdown
---
category:
  uri: documentation
title: ...
---
```

--------------------------------

### Create a Mermaid Flowchart

Source: https://docs.readme.com/main/docs/creating-mermaid-diagrams

A complete example of a top-down flowchart demonstrating documentation features with custom node styling.

```text
flowchart TD
    ReadMe[ReadMe Documentation] --> Guides[Guides]
    ReadMe --> APIRef[API Reference]
    
    Guides --> Editor[Editor UI]
    Editor --> Slash[Slash Commands]
    Slash --> Mermaid[Mermaid Diagrams]
    Slash --> Other[Other Blocks]
    
    APIRef --> OpenAPI[OpenAPI Spec]
    APIRef --> Manual[Manual Editor]
    
    style ReadMe fill:#f9f,stroke:#333,stroke-width:4px
    style Mermaid fill:#bbf,stroke:#333,stroke-width:2px
```

--------------------------------

### Configure reject_params

Source: https://docs.readme.com/main/docs/ruby-api-metrics-set-up

Example of how to define keys to be omitted from logs using the reject_params option.

```ruby
reject_params: ["Authorization", "password"]
```

--------------------------------

### Initialize ReadMe Metrics Extension

Source: https://docs.readme.com/main/docs/python-flask-api-metrics

Configure and initialize the ReadMeMetrics extension in your Flask application setup.

```python
from flask import Flask
from readme_metrics import MetricsApiConfig
from readme_metrics.flask_readme import ReadMeMetrics

# You already have code to create a Flask app...
app = Flask("Your-App-Name")

# Just add code to create the ReadMeMetrics extension and connect it to your app.
metrics_extension = ReadMeMetrics(
    MetricsApiConfig(
        api_key="API_KEY",
        grouping_function=path.to.your.grouping_function
    )
)
metrics_extension.init_app(app)
```

--------------------------------

### Improve underperforming documentation

Source: https://docs.readme.com/main/docs/readmes-mcp-server

Apply a style guide to rewrite and update low-performing pages using ReadMe MCP tools.

```text
Now use the style guide you just created to improve my worst-performing page.

1. Use `search` to find my lowest-rated or least-viewed page
2. Use `fetch` to get its current content
3. Rewrite it following the style guide: match the structure, tone, and
   formatting patterns from the top-performing pages
4. Use `update-docs` to publish the improved version
```

--------------------------------

### Make a Basic Auth API request with cURL

Source: https://docs.readme.com/main/docs/authentication

Example of a cURL request using Basic authentication headers.

```shell
curl --request GET \
     --url https://dash.readme.com/api/v1/custompages \
     --header 'accept: application/json' \
     --header 'authorization: Basic ••••'
```

--------------------------------

### Prompt for automated API monitoring

Source: https://docs.readme.com/main/docs/your-projects-mcp-server

Example prompt for an AI agent to verify API behavior against a schema and report discrepancies.

```text
Check that the API is behaving correctly:
1. Call GET /pet/1 and verify the response matches the schema
2. Try POST /pet with an invalid status and confirm it returns a 400
3. Report any discrepancies
```

--------------------------------

### Define User Data Objects

Source: https://docs.readme.com/main/docs/passing-data-to-jwt

Examples of JSON structures for different project configurations, including single projects, enterprise multi-projects, and those with unique permissions.

```json
{
  "name": "Owlbert",
  "email": "owlbert@readme.io",
  "apiKey": "12345",
  "parameters": {
    "x-readme-version": "1.0",
    "slug": "getting-started"
  }
}
```

```json
{
  "name": "Owlbert",
  "email": "owlbert@readme.io",
  "isAdmin": true,
  "keys": [
    {
      "apiKey": "12345",
      "name": "Enterprise API Key"
    },
    {
      "apiKey": "678910",
      "name": "Personal API Key"
    }
  ],
  "allowedProjects": ["parent-project", "child-project"]
}
```

```json
{
  "name": "Owlbert",
  "email": "owlbert@readme.io",
  "keys": [
    {
      "apiKey": "12345",
      "name": "Enterprise API Key"
    },
    {
      "apiKey": "678910",
      "name": "Personal API Key"
    }
  ],
  "allowedProjects": [
    { "subdomain": "child-project", "access": "readonly" },
    { "subdomain": "child-project-2", "access": "admin" }
  ]
}
```

--------------------------------

### Initialize and Fetch Data with ReadMeAPI

Source: https://docs.readme.com/main/docs/creating-and-managing-guides

Demonstrates proper client initialization and error handling when retrieving user data.

```javascript
// Good example - with meaningful comments and clear variable names
const apiKey = 'your_api_key_here';

// Initialize the client with your API key
const client = new ReadMeAPI(apiKey);

// Fetch user data and handle potential errors
try {
  const userData = await client.getUser(userId);
  console.log(`Found user: ${userData.name}`);
} catch (error) {
  console.error(`Error fetching user: ${error.message}`);
}
```

--------------------------------

### Initialize ReadMe API Client

Source: https://docs.readme.com/main/docs/guides

Demonstrates how to instantiate the ReadMe API client in Node.js and Python.

```javascript
const client = new ReadMeAPI(apiKey);
```

```python
client = ReadMeAPI(api_key)
```

--------------------------------

### Invalid HTML Syntax Example

Source: https://docs.readme.com/main/docs/rendering-errors-invalid-mdx

Demonstrates an example of invalid HTML markup that causes rendering errors in MDX.

```markdown
Hello <world>!
```

--------------------------------

### Build an API client with Python

Source: https://docs.readme.com/main/docs/your-projects-mcp-server

A Python script demonstrating how to list available pets and add a new pet using the requests library.

```python
import requests

BASE_URL = "https://petstore.swagger.io/v2"
API_KEY  = "your-api-key"

def list_available_pets():
    resp = requests.get(
        f"{BASE_URL}/pet/findByStatus",
        params={"status": "available"},
        headers={"api_key": API_KEY},
    )
    resp.raise_for_status()
    return resp.json()

def add_pet(name: str, status: str = "available") -> dict:
    payload = {"name": name, "status": status, "photoUrls": []}
    resp = requests.post(
        f"{BASE_URL}/pet",
        json=payload,
        headers={"api_key": API_KEY, "Content-Type": "application/json"},
    )
    resp.raise_for_status()
    return resp.json()
```

--------------------------------

### Example JSON Request Body

Source: https://docs.readme.com/main/docs/openapi

Represents the JSON structure generated from form data inputs.

```json
{ "complete": false, "id": 123 }
```

--------------------------------

### Publish ReadMe Configuration

Source: https://docs.readme.com/main/docs/sending-logs-to-readme-with-php-laravel

Run the artisan command to generate the readme.php configuration file.

```bash
php artisan vendor:publish --provider="ReadMe\ServiceProvider"
```

--------------------------------

### Configure OAuth options

Source: https://docs.readme.com/main/docs/openapi-extensions

Use the x-readme extension to define global OAuth configuration settings like scope separators and PKCE usage.

```json
{
  "x-readme": {
    "oauth-options": {
      "scopeSeparator": ",",
      "useInsecureClientAuthentication": true,
      "usePkce": false
    }
  }
}
```

--------------------------------

### Test API Request

Source: https://docs.readme.com/main/docs/sending-logs-to-readme-with-nodejs

Verify the integration by sending a request and checking for the x-documentation-url header.

```bash
curl -i {my api url}
```

--------------------------------

### Initialize ReadMe API Client

Source: https://docs.readme.com/main/docs/creating-and-managing-guides

Language-specific initialization patterns for the ReadMe API client using MDX tabs.

```javascript
const client = new ReadMeAPI(apiKey);
```

```python
client = ReadMeAPI(api_key)
```

```ruby
client = ReadMeAPI.new(api_key)
```

--------------------------------

### Import ReadMe SDK

Source: https://docs.readme.com/main/docs/sending-logs-to-readme-with-nodejs

Load the module into your server file using either TypeScript or Node.js syntax.

```ts
import * as readme from 'readmeio';
```

```js
const readme = require('readmeio');
```

--------------------------------

### Define default values in OpenAPI specification

Source: https://docs.readme.com/main/docs/openapi

Example of an OpenAPI operation definition where a default value is provided for a non-required parameter.

```json
{
  "/pet": {
    "get": {
      "summary": "Find pet by Name",
      "description": "Returns a single pet",
      "operationId": "getPetByName",
      "parameters": [
        {
          "name": "petName",
          "in": "body",
          "description": "Name of pet to return",
          "required": false,
          "schema": {
            "type": "string",
            "default": "Buster",
            "example": "Apollo"
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Configure ReadMeMetrics in Python

Source: https://docs.readme.com/main/docs/python-flask-api-metrics

Initialize the ReadMeMetrics extension with custom configuration options to control how logs are sent to ReadMe.

```python
metrics_extension = ReadMeMetrics(
    MetricsApiConfig(
        api_key="KEYS:USER",
        grouping_function=path.to.your.grouping_function,
        buffer_length=1,
        background_worker_mode=False,
        allowlist=["city", "state", "postal_code", "country"],
        timeout=15
    )
)
```

--------------------------------

### Define a templated server URL

Source: https://docs.readme.com/main/docs/personalized-docs

Example of a templated server URL using a region variable for regional API endpoints.

```text
https://{region}.api.example.com
```

--------------------------------

### Configure Basic Auth for Single and Multiple Projects

Source: https://docs.readme.com/main/docs/passing-data-to-jwt

Provide user and pass fields for single projects, or use a keys array to define credentials for multiple projects.

```json
{
  "name": "Marc Cuva",
  "email": "marc@readme.io",
  "isAdmin": true, // Optional
  "user": "user",
  "pass": "pass"
}
```

```json
{
  "name": "Marc Cuva",
  "email": "marc@readme.io",
  "isAdmin": true, // Optional
  "keys": [
    {
      "user": "Marc 1",
      "pass": "Pass 1",
      "name": "Marc's 1st Project"
    }, 
    {
      "user": "Marc 2",
      "pass": "Pass 2",
      "name": "Marc's 2nd Project"
    }
  ]
}
```

--------------------------------

### Define OpenAPI path without tags

Source: https://docs.readme.com/main/docs/openapi-categories-pages-subpages

Example of a path object without tags, where endpoints are grouped by their URL path.

```json
{
  "/pet": {
    "post": {
      "summary": "Add a new pet to the store",
      "operationId": "addPet"
    }
  }
}
```

--------------------------------

### Define OpenAPI path with tags

Source: https://docs.readme.com/main/docs/openapi-categories-pages-subpages

Example of a path object using tags to group endpoints under a specific page title.

```json
{
  "/pet": {
    "post": {
      "tags": [
        "pet"
      ],
      "summary": "Add a new pet to the store",
      "operationId": "addPet"
    }
  }
}
```

--------------------------------

### Prompt for test generation

Source: https://docs.readme.com/main/docs/your-projects-mcp-server

Example prompt for an AI assistant to generate a Jest test suite based on an API endpoint specification.

```text
Look at the POST /pet endpoint and generate a Jest test suite covering:
a successful create, missing required fields, and an invalid status value.
```

--------------------------------

### Execute dry run for documentation uploads

Source: https://docs.readme.com/main/docs/rdme

Use the --dry-run flag to validate frontmatter and preview changes without modifying live documentation.

```bash
rdme docs upload [path] --dry-run
rdme reference upload [path] --dry-run
rdme changelog upload [path] --dry-run
rdme custompages upload [path] --dry-run
```

--------------------------------

### Example OpenAPI Endpoint without operationId

Source: https://docs.readme.com/main/docs/openapi-resyncing

This JSON structure demonstrates an endpoint lacking an explicit operationId, which triggers ReadMe's automatic ID generation.

```json
{
  "/pet": {
    "post": {
    }
  }
}
```

--------------------------------

### Support Multiple Projects via Keys Array

Source: https://docs.readme.com/main/docs/passing-data-to-jwt

Pass an array of project-specific credentials within a keys object to enable project selection via dropdown in the documentation.

```json
{
  "name": "Marc Cuva",
  "email": "marc@readme.io",
  "isAdmin": true, // Optional
  "keys": [
    {
      "apiKey": "12345",
      "user": "Marc",
      "pass": "password",
      "key": "key1",
      "name": "Marc's 1st Project" // Required, used to select a project
    }, 
    {
      "apiKey": "678910",
      "user": "Marc2",
      "pass": "password2",
      "key": "key2",
      "name": "Marc's 2nd Project"
    }
  ]
}
```
Tokens:
Raw