{
  "openapi": "3.1.0",
  "info": {
    "title": "llms-text API",
    "version": "1.0.0",
    "description": "Generate and retrieve llms.txt files for any website. Built by llms-text.com.",
    "contact": {
      "url": "https://www.llms-text.com"
    },
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://www.llms-text.com/api/v1",
      "description": "Production"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Optional. Bypasses rate limiting for authenticated callers."
      }
    },
    "schemas": {
      "GenerateResponse": {
        "type": "object",
        "properties": {
          "llmsTxt": {
            "type": "string",
            "description": "Generated llms.txt content"
          },
          "generationId": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Directus record ID of stored generation"
          },
          "domain": {
            "type": "string",
            "example": "michaelvereb.com"
          },
          "crawledPages": {
            "type": "integer",
            "example": 15
          }
        },
        "required": [
          "llmsTxt",
          "domain",
          "crawledPages"
        ]
      },
      "LookupResponse": {
        "type": "object",
        "properties": {
          "llmsTxt": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "generationId": {
            "type": "integer"
          }
        },
        "required": [
          "llmsTxt",
          "domain",
          "generationId"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable message"
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code",
            "example": "INVALID_URL"
          },
          "details": {
            "type": "object",
            "description": "Optional additional context"
          }
        },
        "required": [
          "error",
          "code"
        ]
      },
      "PingResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "ok"
          },
          "api": {
            "type": "string",
            "example": "llms-text"
          },
          "version": {
            "type": "string",
            "example": "v1"
          },
          "endpoints": {
            "type": "object"
          }
        }
      }
    }
  },
  "paths": {
    "/ping": {
      "get": {
        "operationId": "ping",
        "summary": "Health check",
        "description": "Returns API status and available endpoint list.",
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PingResponse"
                }
              }
            }
          }
        }
      }
    },
    "/generate": {
      "post": {
        "operationId": "generateLlmsTxt",
        "summary": "Generate llms.txt for a URL",
        "description": "Crawls the target website (up to 15 pages standard, 50 pages full), generates a structured llms.txt, and stores it in the llms-text database.",
        "security": [
          {
            "ApiKey": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://www.michaelvereb.com"
                  },
                  "fullVersion": {
                    "type": "boolean",
                    "default": false,
                    "description": "Crawl up to 50 pages and include llms-full.txt"
                  },
                  "sitemapUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Explicit sitemap URL to use instead of autodiscovery"
                  },
                  "excludePaths": {
                    "type": "string",
                    "description": "Comma-separated path fragments to exclude (e.g. \"/legal,/admin\")"
                  }
                }
              },
              "example": {
                "url": "https://www.michaelvereb.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generation successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing or unparseable body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "SSRF blocked — private IP target",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Invalid URL format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "Crawl failed (target site unreachable)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/generate/{domain}": {
      "get": {
        "operationId": "getGenerationByDomain",
        "summary": "Retrieve latest generation for a domain",
        "description": "Returns the most recently stored llms.txt for the given domain. Use `?format=text` to get raw plain text suitable for direct serving.",
        "security": [
          {
            "ApiKey": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "description": "Domain name (with or without www.)",
            "schema": {
              "type": "string",
              "example": "michaelvereb.com"
            }
          },
          {
            "name": "format",
            "in": "query",
            "description": "Set to `text` to return raw text/plain instead of JSON",
            "schema": {
              "type": "string",
              "enum": [
                "text"
              ]
            }
          },
          {
            "name": "refresh",
            "in": "query",
            "description": "Set to `1` to trigger a fresh crawl before returning (requires X-API-Key)",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Generation found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LookupResponse"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                },
                "description": "public, s-maxage=3600, stale-while-revalidate=600"
              }
            }
          },
          "404": {
            "description": "No generation found for this domain",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "Refresh crawl failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}