{
  "openapi": "3.2.1",
  "info": {
    "title": "FastSEOHub Fast AI API",
    "version": "1.0.0",
    "summary": "Evidence-based SEO, AEO and AI optimization API",
    "description": "Versioned FastSEOHub API for AI assistance, website audits, evidence-based SEO analysis and content rewriting. Authenticate with either Authorization: Bearer or X-API-Key. Rate limit: 60 requests per minute per API key. Audits analyze public HTTP(S) pages and do not guarantee search rankings or AI citations.",
    "contact": {
      "name": "Fast AI — FastSEOHub",
      "url": "https://fastseohub.com"
    }
  },
  "servers": [
    {
      "url": "https://fastseohub.com/api/v1",
      "description": "Production API"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyHeader": []
    }
  ],
  "tags": [
    {
      "name": "AI",
      "description": "AI assistance"
    },
    {
      "name": "Audits",
      "description": "Website audits"
    },
    {
      "name": "Analyses",
      "description": "SEO analysis"
    },
    {
      "name": "Rewrites",
      "description": "Content rewriting"
    }
  ],
  "paths": {
    "/ai": {
      "post": {
        "tags": [
          "AI"
        ],
        "operationId": "createAIResponse",
        "summary": "Ask FastSEOHub AI",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AIRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/audits": {
      "post": {
        "tags": [
          "Audits"
        ],
        "operationId": "createAudit",
        "summary": "Run a website audit",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/analyses": {
      "post": {
        "tags": [
          "Analyses"
        ],
        "operationId": "createAnalysis",
        "summary": "Analyze SEO evidence or a URL",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnalysisRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/rewrites": {
      "post": {
        "tags": [
          "Rewrites"
        ],
        "operationId": "createRewrite",
        "summary": "Rewrite content",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RewriteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "FastSEOHub API key"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Alternative to Authorization: Bearer authentication."
      }
    },
    "schemas": {
      "AIRequest": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "minLength": 1
          },
          "context": {
            "type": "object",
            "additionalProperties": true
          },
          "history": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "role": {
                  "type": "string",
                  "enum": [
                    "user",
                    "assistant"
                  ]
                },
                "content": {
                  "type": "string"
                }
              },
              "required": [
                "role",
                "content"
              ]
            }
          }
        },
        "additionalProperties": false
      },
      "AuditRequest": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "pattern": "^https?://"
          },
          "websiteId": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "AnalysisRequest": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "pattern": "^https?://"
          },
          "features": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "additionalProperties": false,
        "anyOf": [
          {
            "required": [
              "url"
            ]
          },
          {
            "required": [
              "features"
            ]
          }
        ],
        "description": "Provide a public URL or SEOFeatures object. If both are supplied, URL-derived evidence takes precedence."
      },
      "RewriteRequest": {
        "type": "object",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "minLength": 1
          },
          "language": {
            "type": "string"
          },
          "goal": {
            "type": "string"
          },
          "keyword": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "limit": {
            "type": "integer"
          },
          "window": {
            "type": "string"
          },
          "resetAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "additionalProperties": true
      },
      "Success": {
        "type": "object",
        "required": [
          "ok",
          "result"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "result": {
            "type": "object",
            "additionalProperties": true,
            "description": "Operation-specific result; fields vary by endpoint."
          }
        },
        "additionalProperties": true
      }
    },
    "responses": {
      "Success": {
        "description": "Successful operation; response body contains ok=true and a result object.",
        "headers": {
          "X-RateLimit-Limit": {
            "schema": {
              "type": "integer"
            },
            "description": "Maximum requests allowed per minute."
          },
          "X-RateLimit-Remaining": {
            "schema": {
              "type": "integer"
            },
            "description": "Requests remaining in the current minute."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Success"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Invalid JSON or invalid request fields.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServerError": {
        "description": "Server-side failure. Internal implementation details should not be returned.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}