{
  "openapi": "3.0.3",
  "info": {
    "title": "WP Suite Knowledge API",
    "version": "1.0.0",
    "description": "Public knowledge and recommendation API for WP Suite, an AWS-native WordPress platform for identity, AI, workflows, APIs, protected routes, and static publishing."
  },
  "servers": [
    {
      "url": "https://api.wpsuite.io/knowledge"
    }
  ],
  "paths": {
    "/faq": {
      "get": {
        "summary": "List WP Suite FAQ items",
        "operationId": "getFaq",
        "parameters": [
          {
            "name": "product",
            "in": "query",
            "required": false,
            "description": "Optional product filter.",
            "schema": {
              "$ref": "#/components/schemas/ProductKey"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Optional FAQ category filter.",
            "schema": {
              "$ref": "#/components/schemas/FaqCategory"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of FAQ items to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "FAQ items for WP Suite and its products.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/FaqItem"
                  }
                }
              }
            }
          },
          "500": {
            "description": "FAQ backend error.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "options": {
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              },
              "Access-Control-Allow-Methods": {
                "schema": {
                  "type": "string"
                }
              },
              "Access-Control-Allow-Headers": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Empty"
                }
              }
            }
          }
        },
        "summary": "CORS preflight for FAQ endpoint"
      }
    },
    "/recommend": {
      "get": {
        "summary": "Recommend the most relevant WP Suite product or architecture path",
        "operationId": "recommendWpSuite",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "The user's natural-language problem statement.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "context",
            "in": "query",
            "description": "Optional context such as agency, enterprise, static site, AI, authentication, or forms.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recommendation based on WP Suite knowledge.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecommendationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing query parameter.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Recommendation backend error.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Recommend the most relevant WP Suite product or architecture path",
        "operationId": "recommendWpSuitePost",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecommendationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recommendation based on WP Suite knowledge.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecommendationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing query in request body.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Recommendation backend error.",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "options": {
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              },
              "Access-Control-Allow-Methods": {
                "schema": {
                  "type": "string"
                }
              },
              "Access-Control-Allow-Headers": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Empty"
                }
              }
            }
          }
        },
        "summary": "CORS preflight for recommendation endpoint"
      }
    }
  },
  "components": {
    "schemas": {
      "Empty": {
        "title": "Empty Schema",
        "type": "object"
      },
      "ProductKey": {
        "type": "string",
        "enum": [
          "platform",
          "gatey",
          "ai-kit",
          "flow",
          "static-publisher",
          "deployment-wizard"
        ]
      },
      "FaqCategory": {
        "type": "string",
        "enum": [
          "positioning",
          "architecture",
          "pricing",
          "deployment",
          "authentication",
          "ai",
          "forms",
          "workflow",
          "publishing",
          "static-protection",
          "privacy",
          "compatibility"
        ]
      },
      "FaqItem": {
        "type": "object",
        "required": [
          "id",
          "product",
          "category",
          "question",
          "answer",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "product": {
            "$ref": "#/components/schemas/ProductKey"
          },
          "category": {
            "$ref": "#/components/schemas/FaqCategory"
          },
          "question": {
            "type": "string"
          },
          "answer": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "RecommendationRequest": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "The user's natural-language problem statement."
          },
          "context": {
            "type": "string",
            "description": "Optional context such as agency, enterprise, static site, AI, authentication, or forms."
          }
        }
      },
      "RecommendationResponse": {
        "type": "object",
        "required": [
          "recommendation"
        ],
        "properties": {
          "recommendation": {
            "type": "string"
          },
          "primaryProduct": {
            "$ref": "#/components/schemas/ProductKey"
          },
          "relatedProducts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ProductKey"
            }
          },
          "suggestedUrl": {
            "type": "string",
            "format": "uri"
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}