{
  "openapi": "3.0.3",
  "info": {
    "title": "AskLoop Public API",
    "version": "1.0.0",
    "description": "API for public questions, answers, analytics, and notification subscriptions."
  },
  "servers": [
    { "url": "/api" }
  ],
  "paths": {
    "/questions": {
      "get": {
        "summary": "Get public questions and answers for a user/subdomain",
        "parameters": [
          {
            "name": "handle",
            "in": "query",
            "description": "User subdomain or handle (optional, defaults to current host)",
            "required": false,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated questions and answers",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/QuestionsResponse" }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Submit a new question for a user/subdomain",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PostQuestionRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Question submitted",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PostQuestionResponse" }
              }
            }
          }
        }
      }
    },
    "/analytics/question-view": {
      "post": {
        "summary": "Log a question view (analytics)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AnalyticsRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Analytics logged",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      },
      "options": {
        "summary": "CORS preflight",
        "responses": {
          "204": { "description": "CORS headers set" }
        }
      }
    },
    "/notifications/subscribe": {
      "post": {
        "summary": "Subscribe to notifications",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SubscribeRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription confirmation sent",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SubscribeResponse" }
              }
            }
          }
        }
      }
    },
    "/notifications/unsubscribe": {
      "post": {
        "summary": "Unsubscribe from notifications",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UnsubscribeRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unsubscribed",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/UnsubscribeResponse" }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/notifications/check": {
      "get": {
        "summary": "Check all subscriptions for an email",
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "description": "Email address to check subscriptions for",
            "required": true,
            "schema": { "type": "string", "format": "email" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of subscriptions",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CheckSubscriptionsResponse" }
              }
            }
          }
        }
      }
    },
    "/api/public-qa-export.json": {
      "get": {
        "summary": "Export all public Q&A",
        "description": "Returns a JSON export of all public questions and answers.",
        "responses": {
          "200": {
            "description": "A list of public Q&A",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuestionAnswer" }
                }
              }
            }
          }
        }
      }
    },
    "/faq": {
      "get": {
        "summary": "Get top 10 FAQ questions",
        "description": "Returns the top 10 most frequently asked questions.",
        "responses": {
          "200": {
            "description": "A list of top 10 FAQ questions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/FAQ" }
                }
              }
            }
          }
        }
      }
    },
    "/prompt-samples": {
      "get": {
        "summary": "Get prompt samples",
        "description": "Returns a list of prompt samples for AI integrations.",
        "responses": {
          "200": {
            "description": "A list of prompt samples",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/PromptSample" }
                }
              }
            }
          }
        }
      }
    },
    "/users/{handle}/questions": {
      "get": {
        "summary": "Get public Q&A for a user",
        "description": "Returns all public questions and answers for a given user handle (creator).",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "description": "The user's handle or username",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of public Q&A for the user",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/QuestionAnswer" }
                }
              }
            }
          },
          "404": {
            "description": "User not found"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "QuestionsResponse": {
        "type": "object",
        "properties": {
          "profile": { "$ref": "#/components/schemas/Profile" },
          "questions": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/QuestionWithAnswer" }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "current_page": { "type": "integer" },
              "last_page": { "type": "integer" },
              "per_page": { "type": "integer" },
              "total": { "type": "integer" },
              "next_page_url": { "type": ["string", "null"] },
              "prev_page_url": { "type": ["string", "null"] }
            }
          }
        }
      },
      "Profile": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "qa_title": { "type": ["string", "null"] },
          "avatar": { "type": ["string", "null"] },
          "show_avatar": { "type": "boolean" },
          "bio": { "type": ["string", "null"] },
          "show_bio": { "type": "boolean" },
          "age": { "type": ["integer", "null"] },
          "show_age": { "type": "boolean" },
          "social_links": { "type": "array", "items": { "type": "string" } },
          "question_limit": { "type": ["integer", "null"] }
        }
      },
      "QuestionWithAnswer": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "content": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "answer": { "$ref": "#/components/schemas/AnswerOrNull" }
        }
      },
      "AnswerOrNull": {
        "oneOf": [
          { "$ref": "#/components/schemas/Answer" },
          { "type": "null" }
        ]
      },
      "Answer": {
        "type": "object",
        "properties": {
          "content": { "type": "string" },
          "published_at": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "PostQuestionRequest": {
        "type": "object",
        "required": ["content", "handle"],
        "properties": {
          "content": { "type": "string", "maxLength": 1000 },
          "is_anonymous": { "type": "boolean" },
          "handle": { "type": "string" },
          "email": { "type": ["string", "null"], "format": "email" }
        }
      },
      "PostQuestionResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "question_id": { "type": "integer" }
        }
      },
      "AnalyticsRequest": {
        "type": "object",
        "required": ["type"],
        "properties": {
          "user_id": { "type": "integer" },
          "question_id": { "type": "integer" },
          "question_ids": {
            "type": "array",
            "items": { "type": "integer" }
          },
          "type": { "type": "string" },
          "utm_source": { "type": "string" },
          "utm_medium": { "type": "string" },
          "utm_campaign": { "type": "string" },
          "utm_term": { "type": "string" },
          "utm_content": { "type": "string" }
        }
      },
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "message": { "type": "string" }
        }
      },
      "SubscribeRequest": {
        "type": "object",
        "required": ["email", "type"],
        "properties": {
          "email": { "type": "string", "format": "email" },
          "type": { "type": "string", "enum": ["profile", "leaderboard"] },
          "reference_id": { "type": ["string", "null"] }
        }
      },
      "SubscribeResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "message": { "type": "string" }
        }
      },
      "UnsubscribeRequest": {
        "type": "object",
        "properties": {
          "email": { "type": "string", "format": "email" },
          "type": { "type": "string", "enum": ["profile", "leaderboard"] },
          "reference_id": { "type": ["string", "null"] },
          "unsubscribe_token": { "type": ["string", "null"] }
        }
      },
      "UnsubscribeResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" }
        }
      },
      "CheckSubscriptionsResponse": {
        "type": "object",
        "properties": {
          "subscriptions": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/NotificationSubscription" }
          }
        }
      },
      "NotificationSubscription": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "email": { "type": "string", "format": "email" },
          "type": { "type": "string", "enum": ["profile", "leaderboard"] },
          "reference_id": { "type": ["string", "null"] },
          "unsubscribe_token": { "type": "string" },
          "confirmed_at": { "type": ["string", "null"], "format": "date-time" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "QuestionAnswer": {
        "type": "object",
        "properties": {
          "question": { "type": "string" },
          "answer": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "answered_at": { "type": "string", "format": "date-time" }
        }
      },
      "FAQ": {
        "type": "object",
        "properties": {
          "question": { "type": "string" },
          "answer": { "type": "string" }
        }
      },
      "PromptSample": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "prompt": { "type": "string" }
        }
      }
    }
  }
}