{
  "openapi": "3.1.0",
  "info": {
    "title": "LLMS.txt Explorer API",
    "description": "Search and retrieve llms.txt file metadata from the world's largest index of llms.txt files. Covers 50,000+ entries across 800+ domains, with quality scores, topic classifications, and change tracking.",
    "version": "1.0.0",
    "contact": {
      "name": "LLMS.txt Explorer",
      "url": "https://llms-text.ai"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://llms-text.ai",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/search-llms": {
      "get": {
        "operationId": "searchLlms",
        "summary": "Search llms.txt entries",
        "description": "Search the database of indexed llms.txt and llms-full.txt files by keyword. Searches across domain, URL, title, summary, topic rankings, and purpose rankings. Returns paginated results.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search query string (1-100 characters). Matches against domain, URL, title, summary, and metadata fields including topic and purpose rankings.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            },
            "example": "openai"
          },
          {
            "name": "fileType",
            "in": "query",
            "required": false,
            "description": "Filter results by file type.",
            "schema": {
              "type": "string",
              "enum": ["llms.txt", "llms-full.txt", "both"],
              "default": "both"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number for pagination.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of results per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingQuery": {
                    "value": {
                      "error": "Missing or empty search query parameter 'q'."
                    }
                  },
                  "invalidPage": {
                    "value": {
                      "error": "Invalid page parameter. Must be a positive integer."
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/search-llms-all": {
      "get": {
        "operationId": "getAllLlms",
        "summary": "Get all llms.txt records",
        "description": "Returns the complete dataset of all indexed llms.txt records grouped by domain. No parameters required. Response is cached for 5 minutes. Warning: response is large (~50K records).",
        "responses": {
          "200": {
            "description": "Complete dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AllRecordsResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LlmsEntry": {
        "type": "object",
        "description": "A single indexed llms.txt or llms-full.txt entry",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Full URL of the llms.txt or llms-full.txt file"
          },
          "domain": {
            "type": "string",
            "description": "Domain where the file was found"
          },
          "content_hash": {
            "type": "string",
            "description": "SHA hash of file content for change detection"
          },
          "last_checked_utc": {
            "type": "string",
            "format": "date-time",
            "description": "When the file was last crawled"
          },
          "title": {
            "type": "string",
            "description": "Title extracted from the file"
          },
          "summary": {
            "type": "string",
            "description": "Brief description of the file content"
          },
          "quality": {
            "type": "string",
            "enum": ["High", "Medium", "Low"],
            "description": "Quality grade based on llmstxt.org spec compliance"
          },
          "metadata": {
            "$ref": "#/components/schemas/EntryMetadata"
          },
          "first_added": {
            "type": "string",
            "format": "date-time",
            "description": "When this entry was first discovered"
          },
          "last_updated": {
            "type": "string",
            "format": "date-time",
            "description": "When the content last changed"
          },
          "previous_content_hash": {
            "type": "string",
            "description": "Previous content hash for change tracking"
          }
        },
        "required": ["url", "domain", "content_hash", "title", "metadata", "first_added", "last_updated"]
      },
      "EntryMetadata": {
        "type": "object",
        "description": "AI-generated classifications and metrics for an entry",
        "properties": {
          "source_domain": {
            "type": "string",
            "description": "Source domain of the entry"
          },
          "url_purpose_ranking": {
            "type": "array",
            "items": { "type": "string" },
            "description": "AI-classified purposes for this URL (e.g., 'Documentation', 'API Reference')"
          },
          "url_topic_ranking": {
            "type": "array",
            "items": {
              "type": "array",
              "prefixItems": [
                { "type": "string" },
                { "type": "number" }
              ],
              "items": false
            },
            "description": "AI-classified topics with relevance scores as [topic, score] pairs"
          },
          "domain_purpose_ranking": {
            "type": "array",
            "items": { "type": "string" },
            "description": "AI-classified purposes for the overall domain"
          },
          "domain_topic_ranking": {
            "type": "array",
            "items": {
              "type": "array",
              "prefixItems": [
                { "type": "string" },
                { "type": "number" }
              ],
              "items": false
            },
            "description": "AI-classified topics with relevance scores for the domain"
          },
          "url_token_count": {
            "type": "integer",
            "description": "Estimated token count of the file content"
          },
          "previous_url_token_count": {
            "type": "integer",
            "description": "Previous token count for tracking content size changes"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "totalResults": {
            "type": "integer",
            "description": "Total number of matching results"
          },
          "page": {
            "type": "integer",
            "description": "Current page number"
          },
          "limit": {
            "type": "integer",
            "description": "Results per page"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LlmsEntry"
            }
          }
        },
        "required": ["totalResults", "page", "limit", "results"]
      },
      "DomainGroupedEntry": {
        "type": "object",
        "description": "Records grouped by domain with both llms.txt and llms-full.txt data",
        "properties": {
          "domain": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "urls": {
            "type": "object",
            "properties": {
              "llms": { "type": "string", "format": "uri" },
              "llmsFull": { "type": "string", "format": "uri" }
            }
          },
          "title": {
            "type": "string"
          },
          "quality": {
            "type": "string",
            "enum": ["High", "Medium", "Low"]
          },
          "description": {
            "type": "string"
          },
          "metadata": {
            "$ref": "#/components/schemas/EntryMetadata"
          },
          "last_updated": {
            "type": "string",
            "format": "date-time"
          },
          "first_added": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AllRecordsResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "count": {
            "type": "integer",
            "description": "Number of domain groups returned"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DomainGroupedEntry"
            }
          }
        },
        "required": ["success", "count", "data"]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message describing what went wrong"
          }
        },
        "required": ["error"]
      }
    }
  }
}