{
  "openapi": "3.1.0",
  "info": {
    "title": "API Map Data API",
    "version": "2.0.0",
    "description": "Machine-readable REST API for the API Map directory. Returns structured data about 50+ REST APIs including base URLs, authentication, endpoints, pricing, and rate limits.",
    "contact": {
      "url": "https://apimap.dev"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://apimap.dev",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/apis.json": {
      "get": {
        "operationId": "getAllAPIs",
        "summary": "Get all APIs",
        "description": "Returns the full dataset of all indexed APIs with metadata.",
        "responses": {
          "200": {
            "description": "Full API dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FullDataset"
                }
              }
            }
          }
        }
      }
    },
    "/api/categories/{categoryId}.json": {
      "get": {
        "operationId": "getAPIsByCategory",
        "summary": "Get APIs by category",
        "description": "Returns only the APIs in a specific category. Much smaller payload than the full dataset.",
        "parameters": [
          {
            "name": "categoryId",
            "in": "path",
            "required": true,
            "description": "Category ID",
            "schema": {
              "type": "string",
              "enum": [
                "ai",
                "payments",
                "maps",
                "weather",
                "social",
                "communication",
                "search",
                "storage",
                "auth",
                "entertainment",
                "finance",
                "developer",
                "ecommerce",
                "security"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "APIs for the requested category",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoryDataset"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "APIEntry": {
        "type": "object",
        "required": [
          "id",
          "name",
          "provider",
          "category",
          "baseUrl",
          "authType"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique slug",
            "example": "openai"
          },
          "name": {
            "type": "string",
            "example": "OpenAI API"
          },
          "provider": {
            "type": "string",
            "example": "OpenAI"
          },
          "category": {
            "type": "string",
            "enum": [
              "ai",
              "payments",
              "maps",
              "weather",
              "social",
              "communication",
              "search",
              "storage",
              "auth",
              "entertainment",
              "finance",
              "developer",
              "ecommerce",
              "security"
            ]
          },
          "description": {
            "type": "string",
            "description": "One-sentence summary"
          },
          "longDescription": {
            "type": "string"
          },
          "color": {
            "type": "string",
            "description": "Brand hex color",
            "example": "#10a37f"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "authType": {
            "type": "string",
            "enum": [
              "bearer",
              "api-key",
              "oauth2",
              "basic",
              "hmac"
            ]
          },
          "authDescription": {
            "type": "string"
          },
          "authExample": {
            "type": "string",
            "example": "Authorization: Bearer sk-proj-..."
          },
          "baseUrl": {
            "type": "string",
            "format": "uri"
          },
          "docsUrl": {
            "type": "string",
            "format": "uri"
          },
          "hasFreeTier": {
            "type": "boolean"
          },
          "pricing": {
            "type": "object",
            "properties": {
              "model": {
                "type": "string",
                "enum": [
                  "free",
                  "freemium",
                  "subscription",
                  "pay-as-you-go",
                  "enterprise"
                ]
              },
              "startingCentsPerMonth": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Starting monthly price in US cents. 0=free, null=enterprise/unknown"
              },
              "freeQuota": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "amount": {
                    "type": [
                      "number",
                      "null"
                    ]
                  },
                  "unit": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "period": {
                    "type": "string"
                  },
                  "note": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              },
              "tiers": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "monthlyCents": {
                      "type": "integer"
                    },
                    "included": {
                      "type": "string"
                    }
                  }
                }
              },
              "unitCost": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "amountCents": {
                    "type": "integer"
                  },
                  "per": {
                    "type": "integer"
                  },
                  "unit": {
                    "type": "string"
                  }
                }
              },
              "details": {
                "type": "string"
              }
            }
          },
          "rateLimit": {
            "type": "string",
            "example": "60 requests/min"
          },
          "endpoints": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "method": {
                  "type": "string",
                  "enum": [
                    "GET",
                    "POST",
                    "PUT",
                    "PATCH",
                    "DELETE"
                  ]
                },
                "path": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          },
          "sampleRequest": {
            "type": "string",
            "description": "Ready-to-run curl command"
          },
          "sampleResponse": {
            "type": "string",
            "description": "Example JSON response"
          }
        }
      },
      "Meta": {
        "type": "object",
        "properties": {
          "version": {
            "type": "string"
          },
          "generated": {
            "type": "string",
            "format": "date-time"
          },
          "totalAPIs": {
            "type": "integer"
          },
          "source": {
            "type": "string",
            "format": "uri"
          },
          "license": {
            "type": "string"
          }
        }
      },
      "FullDataset": {
        "type": "object",
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/Meta"
          },
          "apis": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/APIEntry"
            }
          }
        }
      },
      "CategoryDataset": {
        "type": "object",
        "properties": {
          "meta": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Meta"
              },
              {
                "type": "object",
                "properties": {
                  "category": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string"
                  },
                  "count": {
                    "type": "integer"
                  }
                }
              }
            ]
          },
          "apis": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/APIEntry"
            }
          }
        }
      }
    }
  }
}