openapi-directory-first

OpenAPI Directory First

Overview

Always check the APIs-guru/openapi-directory for authoritative, machine-readable API specs before relying on training data or web searches. This directory contains 2500+ public API definitions in OpenAPI format, auto-updated weekly from original sources.

Core rule: Training data goes stale. OpenAPI specs are the source of truth.

When to Use

• Writing code that calls any public REST API
• Looking up endpoint parameters, auth, request/response schemas
• Debugging API integration issues (wrong params, unexpected responses)
• Generating API client code or types
• Answering questions about how a public API works

When NOT to Use

• Internal/private APIs (not in the directory)
• GraphQL APIs (directory is REST/OpenAPI only)
• When you already have the project's own OpenAPI spec locally

The Workflow

digraph api_lookup {
  "Need API info" -> "Check openapi-directory";
  "Check openapi-directory" -> "Found?";
  "Found" -> "Use the spec";
  "Not found" -> "Fallback: doc site or context7";
  "Use the spec" -> "Still need examples?";
  "Still need examples?" -> "Yes: search web" [label="yes"];
  "Still need examples?" -> "Done" [label="no"];
}

How to Look Up

Step 1: Find the API

Search the directory for the provider domain:

# List available APIs for a provider
curl -s "https://api.github.com/repos/APIs-guru/openapi-directory/contents/APIs/{provider.com}" | python3 -c "
import json,sys
data=json.load(sys.stdin)
for item in data:
    print(f'{item[\"name\"]}')"

Common provider domains: stripe.com, github.com, spotify.com, amazonaws.com, googleapis.com, microsoft.com, twilio.com, slack.com, shopify.com, paypal.com, sendgrid.com, notion.com, figma.com

Step 2: Pick the latest version

Providers often have multiple API versions. Use the most recent dated folder.

Step 3: Fetch the spec

https://raw.githubusercontent.com/APIs-guru/openapi-directory/main/APIs/{provider.com}/{version}/openapi.yaml