{
  "openapi": "3.1.0",
  "info": {
    "title": "Monchitro API",
    "version": "0.1.0",
    "description": "Proposed API contract. Endpoints remain planned until deployed and tested."
  },
  "servers": [
    {
      "url": "/api",
      "description": "Relative to the current Monchitro deployment origin"
    }
  ],
  "paths": {
    "/auth/register": {
      "post": {
        "summary": "Register using Supabase Auth",
        "responses": {
          "202": {
            "description": "Confirmation email requested"
          },
          "400": {
            "description": "Invalid input"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/books": {
      "get": {
        "summary": "List published books",
        "parameters": [
          {
            "name": "class",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "medium",
            "in": "query",
            "schema": {
              "enum": [
                "bn-BD",
                "en-US"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paged list of published book summaries"
          }
        }
      }
    },
    "/books/{bookId}": {
      "get": {
        "summary": "Get a book and visible chapters",
        "parameters": [
          {
            "name": "bookId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Book metadata and chapter list"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/chapters/{chapterId}": {
      "get": {
        "summary": "Get chapter metadata and page order",
        "responses": {
          "200": {
            "description": "Localized chapter metadata"
          }
        }
      }
    },
    "/pages/{pageId}": {
      "get": {
        "summary": "Get selectable localized page content",
        "responses": {
          "200": {
            "description": "Page text nodes and licensed assets"
          }
        }
      }
    },
    "/annotations": {
      "get": {
        "summary": "List current user annotations",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Owner-scoped annotations"
          },
          "401": {
            "description": "Authentication required"
          }
        }
      },
      "post": {
        "summary": "Create an owner-scoped annotation",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "pageId",
                  "kind"
                ],
                "properties": {
                  "pageId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "kind": {
                    "enum": [
                      "highlight",
                      "note",
                      "bookmark"
                    ]
                  },
                  "selectedText": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "color": {
                    "enum": [
                      "sunshine",
                      "mint",
                      "rose"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created annotation"
          },
          "400": {
            "description": "Invalid request"
          }
        }
      }
    },
    "/ai/explain": {
      "post": {
        "summary": "Request a rate-limited, server-side study explanation",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Localized coaching response"
          },
          "429": {
            "description": "Rate limit reached"
          }
        }
      }
    },
    "/questions/{chapterId}": {
      "get": {
        "summary": "List active questions without answer keys",
        "responses": {
          "200": {
            "description": "Question prompts and options"
          }
        }
      }
    },
    "/quiz/submit": {
      "post": {
        "summary": "Score a quiz attempt on the server",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Score and answer review"
          },
          "409": {
            "description": "Duplicate attempt"
          }
        }
      }
    },
    "/student/progress": {
      "get": {
        "summary": "Read current learner progress",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current user progress"
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/subscriptions": {
      "post": {
        "summary": "Create a pending subscription intent",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "202": {
            "description": "Pending provider intent"
          },
          "409": {
            "description": "Idempotency conflict"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Supabase JWT"
      }
    }
  }
}