{
  "openapi": "3.1.0",
  "info": {
    "title": "SEOmade Directory API",
    "version": "1.0.0",
    "description": "Search SEOmade's ranked catalog of startup, SaaS and AI directories. An API key is required: create one at https://seomade.app/developers."
  },
  "servers": [
    {
      "url": "https://seomade.app/api/v1"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization: Bearer sm_live_... (X-API-Key also works)"
      }
    }
  },
  "paths": {
    "/directories": {
      "get": {
        "operationId": "listDirectories",
        "summary": "Search and filter the ranked catalog",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Text search over name, host, category and summary",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Category name, or part of one",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "link_type",
            "in": "query",
            "description": "dofollow or nofollow",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pricing",
            "in": "query",
            "description": "free, paid or freemium, as listed",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "quality_tier",
            "in": "query",
            "description": "Editorial tier",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "saas_fit",
            "in": "query",
            "description": "How well the directory fits SaaS products",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "goal",
            "in": "query",
            "description": "Primary goal the directory serves",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "collection",
            "in": "query",
            "description": "A curated set",
            "schema": {
              "type": "string",
              "enum": [
                "good",
                "top",
                "saas"
              ]
            }
          },
          {
            "name": "min_dr",
            "in": "query",
            "description": "Lowest Domain Rating to include",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "max_dr",
            "in": "query",
            "description": "Highest Domain Rating to include",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "dofollow",
            "in": "query",
            "description": "true for dofollow only, false for the rest",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "free",
            "in": "query",
            "description": "true for free only, false for the rest",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "curated",
            "in": "query",
            "description": "true for hand-reviewed entries only",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort field. Defaults to rank",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "order",
            "in": "query",
            "description": "Sort direction",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size. Default 25, capped by your plan",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Rows to skip",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of directories"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Daily quota used up"
          }
        }
      }
    },
    "/directories/{slug}": {
      "get": {
        "operationId": "getDirectory",
        "summary": "One directory by slug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The directory record"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "404": {
            "description": "No directory with that slug"
          }
        }
      }
    },
    "/meta": {
      "get": {
        "operationId": "getMeta",
        "summary": "Catalog stats, categories and your plan limits",
        "responses": {
          "200": {
            "description": "Catalog metadata"
          },
          "401": {
            "description": "Missing or invalid API key"
          }
        }
      }
    }
  }
}
