{
  "openapi": "3.1.0",
  "info": {
    "title": "SeliQt API",
    "version": "1.0.0",
    "description": "SeliQt API — AI-powered maths tutoring for Australian selective entry exam preparation. All endpoints are Supabase Edge Functions. Authentication via Supabase JWT Bearer token.",
    "contact": {
      "name": "SeliQt Support",
      "email": "support@seliqt.com",
      "url": "https://www.seliqt.com"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://[YOUR_SUPABASE_PROJECT_REF].supabase.co",
      "description": "Production — replace [YOUR_SUPABASE_PROJECT_REF] with your Supabase project reference"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/functions/v1/call-gemini": {
      "post": {
        "operationId": "callGemini",
        "summary": "Generate questions or evaluate student answers via Gemini AI",
        "description": "Proxies a request to Google Gemini. Used for: (1) generating adaptive maths questions aligned to the Australian Curriculum, (2) evaluating handwritten student answers from a canvas image, (3) generating personalised feedback with deviation point analysis.\n\n**Security notes:** The `systemInstruction` field is ignored — a server-side safety instruction is always applied. Only allowlisted models are accepted. Guest-tier users are limited to 3 calls/day enforced server-side; paid subscribers have no daily cap.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeminiRequest"
              },
              "examples": {
                "generateQuestion": {
                  "summary": "Generate a Year 6 algebra question at Growth tier",
                  "value": {
                    "model": "gemini-2.0-flash",
                    "contents": [
                      {
                        "role": "user",
                        "parts": [{ "text": "Generate a Year 6 algebra question at Growth difficulty." }]
                      }
                    ],
                    "generationConfig": {
                      "responseMimeType": "application/json"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Gemini response text",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeminiResponse"
                }
              }
            }
          },
          "400": { "description": "Model not in allowlist" },
          "401": { "description": "Unauthorized — missing or invalid Bearer token" },
          "429": { "description": "Daily quota exceeded (guest tier). Subscribe to remove limit." },
          "500": { "description": "Gemini API error or server error" }
        }
      }
    },
    "/functions/v1/create-checkout-session": {
      "post": {
        "operationId": "createCheckoutSession",
        "summary": "Create a Stripe subscription checkout session",
        "description": "Initiates a Stripe Checkout session for the authenticated user. Returns a URL to redirect the user to complete payment. Supports Foundation ($9.99/mo), Core ($14.99/mo), Accelerate ($24.99/mo), and Family ($39.99/mo) plans.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckoutRequest"
              },
              "examples": {
                "coreMonthly": {
                  "summary": "Subscribe to Core plan",
                  "value": {
                    "priceId": "price_xxx",
                    "successUrl": "https://www.seliqt.com/#/dashboard",
                    "cancelUrl": "https://www.seliqt.com/#/pricing"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stripe checkout URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckoutResponse"
                }
              }
            }
          },
          "401": { "description": "Unauthorized — user must be logged in" },
          "400": { "description": "Invalid price ID or missing required fields" }
        }
      }
    },
    "/functions/v1/create-portal-link": {
      "post": {
        "operationId": "createPortalLink",
        "summary": "Open Stripe billing portal for subscription management",
        "description": "Returns a URL to the Stripe Customer Portal where the authenticated subscriber can upgrade, downgrade, or cancel their subscription.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PortalRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stripe portal URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortalResponse"
                }
              }
            }
          },
          "401": { "description": "Unauthorized — user must be logged in" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Supabase JWT. Obtain via POST /auth/v1/token with email/password, or Google/Apple OAuth."
      }
    },
    "schemas": {
      "GeminiRequest": {
        "type": "object",
        "required": ["model", "contents"],
        "properties": {
          "model": {
            "type": "string",
            "description": "Gemini model identifier. Must be one of the allowlisted models. Defaults to gemini-2.5-flash.",
            "enum": ["gemini-2.5-flash", "gemini-2.0-flash", "gemini-2.0-flash-thinking-exp-01-21"],
            "default": "gemini-2.5-flash"
          },
          "contents": {
            "type": "array",
            "description": "Conversation turns in Gemini Content format",
            "items": {
              "type": "object",
              "properties": {
                "role": { "type": "string", "enum": ["user", "model"] },
                "parts": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "text": { "type": "string" },
                      "inlineData": {
                        "type": "object",
                        "description": "Base64-encoded image for handwriting evaluation",
                        "properties": {
                          "mimeType": { "type": "string", "example": "image/png" },
                          "data": { "type": "string", "description": "Base64-encoded image data" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "generationConfig": {
            "type": "object",
            "description": "Optional Gemini generation configuration",
            "properties": {
              "responseMimeType": { "type": "string", "example": "application/json" },
              "temperature": { "type": "number" },
              "maxOutputTokens": { "type": "integer" }
            }
          },
          "systemInstruction": {
            "type": "object",
            "description": "Ignored. A fixed server-side safety instruction is always applied and cannot be overridden by callers.",
            "deprecated": true
          }
        }
      },
      "GeminiResponse": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "nullable": true,
            "description": "Generated text from Gemini. May be JSON-encoded when generationConfig.responseMimeType is application/json."
          }
        }
      },
      "CheckoutRequest": {
        "type": "object",
        "required": ["priceId"],
        "properties": {
          "priceId": {
            "type": "string",
            "description": "Stripe Price ID for the chosen plan. Obtain from the SeliQt dashboard or environment configuration.",
            "example": "price_xxx"
          },
          "successUrl": {
            "type": "string",
            "description": "URL to redirect after successful payment",
            "example": "https://www.seliqt.com/#/dashboard"
          },
          "cancelUrl": {
            "type": "string",
            "description": "URL to redirect if checkout is cancelled",
            "example": "https://www.seliqt.com/#/pricing"
          }
        }
      },
      "CheckoutResponse": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Stripe Checkout URL. Redirect the user here to complete payment."
          },
          "sessionId": {
            "type": "string",
            "description": "Stripe Checkout Session ID for tracking"
          }
        }
      },
      "PortalRequest": {
        "type": "object",
        "properties": {
          "returnUrl": {
            "type": "string",
            "description": "URL to return to after leaving the portal",
            "example": "https://www.seliqt.com/#/profile"
          }
        }
      },
      "PortalResponse": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Stripe Customer Portal URL. Redirect the user here to manage their subscription."
          }
        }
      }
    }
  }
}