{
  "openapi": "3.1.0",
  "info": {
    "title": "llms-txt.io API",
    "version": "1.0.0",
    "description": "Generate and validate llms.txt / llms-full.txt files programmatically. Every /api/v1 request requires an API key created in your account (Account → API keys).",
    "contact": {
      "url": "https://llms-txt.io/contact"
    }
  },
  "servers": [
    {
      "url": "https://llms-txt.io"
    }
  ],
  "security": [
    {
      "apiKeyHeader": []
    },
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Generate",
      "description": "Create llms.txt / llms-full.txt from a URL."
    },
    {
      "name": "Validate",
      "description": "Lint an llms.txt by URL or raw content."
    }
  ],
  "paths": {
    "/api/v1/generate": {
      "post": {
        "tags": [
          "Generate"
        ],
        "operationId": "generate",
        "summary": "Generate llms.txt / llms-full.txt for a site",
        "description": "Crawls the given URL and returns the generated file(s). llms-full.txt requires the Starter plan or above; free keys receive llms.txt only.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerateRequest"
              },
              "example": {
                "url": "https://example.com",
                "fileType": "both"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The generated file(s).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid `url` / `fileType`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Plan does not permit the requested file type, or the target site blocked access.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly generate allowance or per-minute rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Generation failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/validate": {
      "post": {
        "tags": [
          "Validate"
        ],
        "operationId": "validate",
        "summary": "Validate an llms.txt by URL or raw content",
        "description": "Provide either `url` (fetch + lint the served file) or `content` (lint raw text, e.g. in CI before publishing).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateRequest"
              },
              "example": {
                "url": "https://example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The validation result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Neither `url` nor `content` provided, or `content` is not a string.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "`content` exceeds the 500 KB validation limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Monthly validate allowance or per-minute rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your API key, e.g. llmstxt_sk_live_…"
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "The same API key passed as `Authorization: Bearer <key>`."
      }
    },
    "schemas": {
      "GenerateRequest": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Public website URL to generate from."
          },
          "fileType": {
            "type": "string",
            "enum": [
              "llms",
              "llms-full",
              "both"
            ],
            "default": "both"
          },
          "instructions": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional guidance for the agent-instructions section."
          }
        }
      },
      "GenerateResponse": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "fileType": {
            "type": "string",
            "enum": [
              "llms",
              "llms-full",
              "both"
            ]
          },
          "llmsTxt": {
            "type": [
              "string",
              "null"
            ]
          },
          "llmsFullTxt": {
            "type": [
              "string",
              "null"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "Any plan-gating or pipeline note (e.g. llms-full downgraded on a free key)."
          },
          "llmEnhanced": {
            "type": "boolean"
          },
          "fullPagesIncluded": {
            "type": [
              "integer",
              "null"
            ]
          },
          "fullPagesAvailable": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "ValidateRequest": {
        "type": "object",
        "description": "Provide exactly one of `url` or `content`.",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "URL whose served llms.txt to fetch and lint."
          },
          "content": {
            "type": "string",
            "description": "Raw llms.txt text to lint (max 500 KB)."
          },
          "checkLinks": {
            "type": "boolean",
            "default": true,
            "description": "Sample and probe in-file links for liveness."
          }
        }
      },
      "ValidateResponse": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "url",
              "content"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ]
          },
          "targetUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "score": {
            "type": "integer",
            "description": "Structure-tier score (0–100)."
          },
          "readinessScore": {
            "type": "integer",
            "description": "Agent-readiness score (0–100)."
          },
          "status": {
            "type": "string",
            "enum": [
              "pass",
              "warning",
              "fail"
            ]
          },
          "health": {
            "type": "string",
            "enum": [
              "live",
              "degraded",
              "dead"
            ]
          },
          "checks": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "tier": {
                  "type": "string",
                  "enum": [
                    "structure",
                    "readiness"
                  ]
                },
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "pass",
                    "warning",
                    "fail"
                  ]
                },
                "message": {
                  "type": "string"
                }
              }
            }
          },
          "usesInstructionsPattern": {
            "type": "boolean"
          },
          "hasLlmsFull": {
            "type": "boolean"
          },
          "contentLength": {
            "type": "integer"
          },
          "linkStats": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "sampled": {
                "type": "integer"
              },
              "dead": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "integer"
          },
          "message": {
            "type": "string"
          }
        },
        "example": {
          "statusCode": 401,
          "message": "Invalid or revoked API key."
        }
      }
    }
  }
}