ReadMe.io API Generation

This guide explains how to generate OpenPets-compatible tools from APIs hosted on ReadMe.io documentation platforms using the pets generate-readme CLI command.

Overview

Many popular APIs host their documentation on ReadMe.io (readme.com), which provides auto-generated API SDKs. The ReadMe generator uses the npx api install command to fetch OpenAPI specifications directly from the ReadMe registry, then delegates to the standard OpenAPI generator to create tools.

This approach is ideal for:

APIs with ReadMe.io-hosted documentation
Services that don't publicly expose their OpenAPI spec
Quick bootstrapping when you have the ReadMe registry ID

Quick Start

From Command Line

bash

cd pets/my-api

# Generate from ReadMe registry ID
pets generate-readme --registry "@luma-docs/v1.0#dem71tmjbssfr5"

# With verbose output
pets generate-readme --registry "@luma-docs/v1.0#dem71tmjbssfr5" -v

# Preview without writing files
pets generate-readme --registry "@luma-docs/v1.0#dem71tmjbssfr5" --dry-run

From package.json Config (Recommended)

Add a readmeSpec section to your pet's package.json:

json

{
  "name": "@openpets/my-api",
  "readmeSpec": {
    "registryId": "@luma-docs/v1.0#dem71tmjbssfr5",
    "baseUrl": "https://public-api.luma.com",
    "authType": "apiKey",
    "apiKeyHeader": "x-luma-api-key",
    "authEnvVar": "LUMA_API_KEY"
  }
}

Then run:

bash

cd pets/my-api
pets generate-readme

Finding the Registry ID

The registry ID is typically found in the API documentation's SDK section:

Go to the API reference page (e.g., https://docs.service.com/reference)
Look for "API SDK", "Client Libraries", or similar sections
Find the npx api install command - the argument is your registry ID

Registry ID format: @{org}-docs/{version}#{hash}

Examples:

@luma-docs/v1.0#dem71tmjbssfr5 (Luma Events API)
@readme-docs/v2.0#abc123xyz (ReadMe API)

Configuration Reference

package.json readmeSpec

Property	Type	Required	Description
`registryId`	string	Yes	ReadMe registry ID (e.g., "@luma-docs/v1.0#abc123")
`baseUrl`	string	No	Base URL for API calls
`altBaseUrl`	string	No	Alternative base URL for environment switching
`baseUrlEnvVar`	string	No	Environment variable to select base URL
`baseUrlEnvValue`	string	No	Value that triggers altBaseUrl
`authEnvVar`	string	No	Environment variable for auth token/key
`authSecretEnvVar`	string	No	Environment variable for auth secret
`authType`	string	No	Authentication type: `bearer`, `apiKey`, `basic`, or `none`
`apiKeyHeader`	string	No	Header name for API key auth
`include`	string[]	No	Only generate tools matching these patterns
`exclude`	string[]	No	Skip tools matching these patterns
`readOnlyPatterns`	string[]	No	Mark tools matching these patterns as read-only
`coreEndpoints`	object	No	Configure which tools are core vs loadEnv

CLI Options

bash

pets generate-readme [options]

Options:
  --registry <id>       ReadMe.io registry ID
  --output <file>       Output file name (default: openapi-client.ts)
  --temp-dir <path>     Temp directory for api install (default: /tmp/readme-api-temp)
  --keep-temp           Keep temp directory after generation
  -n, --dry-run         Preview without writing files
  -v, --verbose         Show detailed output

How It Works

Fetch spec: Runs npx api install {registryId} --lang ts in a temp directory
Extract spec: Copies the OpenAPI spec from .api/apis/{project}/openapi.json
Configure: Merges readmeSpec settings into openapiSpec in package.json
Generate: Delegates to pets generate-openapi for tool generation

Real-World Example: Luma

The pets/luma pet demonstrates ReadMe API generation:

Finding the Registry ID

Visit https://docs.lu.ma/reference/
Look for the SDK installation section
Find: npx api install "@luma-docs/v1.0#dem71tmjbssfr5"

package.json Configuration

json

{
  "name": "@openpets/luma",
  "readmeSpec": {
    "registryId": "@luma-docs/v1.0#dem71tmjbssfr5",
    "baseUrl": "https://public-api.luma.com",
    "authType": "apiKey",
    "apiKeyHeader": "x-luma-api-key",
    "authEnvVar": "LUMA_API_KEY",
    "coreEndpoints": {
      "tags": ["Events", "Calendars"],
      "paths": ["/v1/user/get-self", "/v1/event/get"]
    }
  }
}

Generation

bash

cd pets/luma
pets generate-readme -v

# Output:
# 🔧 Generating tools from ReadMe.io registry...
# ✅ Generated 42 tools (18 read-only, 24 write)
# 📁 Output: /path/to/pets/luma/openapi-client.ts
# 📄 OpenAPI spec: /path/to/pets/luma/openapi-spec.json
# 🔧 Tools generated: 42

Combining with openapiSpec

When you run pets generate-readme, it:

Downloads the OpenAPI spec from ReadMe
Saves it as openapi-spec.json in your pet directory
Merges your readmeSpec settings into openapiSpec in package.json
Generates tools using the standard OpenAPI generator

After generation, you can use pets generate-openapi directly for regeneration:

bash

# First time: use generate-readme to fetch the spec
pets generate-readme --registry "@luma-docs/v1.0#dem71tmjbssfr5"

# Future regenerations: use generate-openapi (faster, no network)
pets generate-openapi

Troubleshooting

"No registry ID provided"

Either:

Use --registry option: pets generate-readme --registry "@org/v1#hash"
Add readmeSpec.registryId to package.json

"api install failed"

Common causes:

Invalid registry ID - verify the ID from the API docs
Network issues - check your internet connection
npm/npx not available - ensure Node.js is installed

Try with verbose mode:

bash

pets generate-readme --registry "@org/v1#hash" -v --keep-temp

"No openapi.json found"

The API install may have succeeded but created a different structure. Check:

bash

ls -la /tmp/readme-api-temp/.api/apis/

Authentication issues after generation

The ReadMe generator creates the OpenAPI spec file, but you still need to:

Set up authentication in your .env file
Configure authEnvVar and authType in your config

When to Use ReadMe vs OpenAPI Generation

Scenario	Recommended Approach
API has direct OpenAPI spec URL	`pets generate-openapi --url`
API only on ReadMe.io	`pets generate-readme`
Already have openapi-spec.json	`pets generate-openapi`
First-time setup from ReadMe	`pets generate-readme`
Regenerating existing pet	`pets generate-openapi`

Supported ReadMe.io APIs

Any API documented on ReadMe.io with SDK generation enabled should work. Known working examples:

Luma (@luma-docs/v1.0#...) - Event management
ReadMe (@readme-docs/...) - Documentation API
Many others - check the API's reference docs for the registry ID

ReadMe.io API Generation ​

Overview ​

Quick Start ​

From Command Line ​

From package.json Config (Recommended) ​

Finding the Registry ID ​

Configuration Reference ​

package.json readmeSpec ​

CLI Options ​

How It Works ​

Real-World Example: Luma ​

Finding the Registry ID ​

package.json Configuration ​

Generation ​

Combining with openapiSpec ​

Troubleshooting ​

"No registry ID provided" ​

"api install failed" ​

"No openapi.json found" ​

Authentication issues after generation ​

When to Use ReadMe vs OpenAPI Generation ​

Supported ReadMe.io APIs ​

ReadMe.io API Generation

Overview

Quick Start

From Command Line

From package.json Config (Recommended)

Finding the Registry ID

Configuration Reference

package.json readmeSpec

CLI Options

How It Works

Real-World Example: Luma

Finding the Registry ID

package.json Configuration

Generation

Combining with openapiSpec

Troubleshooting

"No registry ID provided"

"api install failed"

"No openapi.json found"

Authentication issues after generation

When to Use ReadMe vs OpenAPI Generation

Supported ReadMe.io APIs