{
  "openapi": "3.1.0",
  "info": {
    "title": "Newlege Public API",
    "version": "1.0.0",
    "description": "Programmatic access to a Newlege academy — students, courses, enrollments, transactions. Built for backends, automations (Zapier / Make / n8n) and AI agents (Claude, ChatGPT, Gemini).",
    "contact": { "name": "Newlege Support", "email": "support@newlege.co.il", "url": "https://newlege.co.il/api-docs/" },
    "license": { "name": "Proprietary" }
  },
  "servers": [{ "url": "https://cuabhknytckerifjaple.supabase.co/functions/v1/public-api/v1", "description": "Production" }],
  "security": [{ "bearerAuth": [] }],
  "tags": [
    { "name": "Identity" },
    { "name": "Students" },
    { "name": "Courses" },
    { "name": "Enrollments" },
    { "name": "Transactions" }
  ],
  "paths": {
    "/me": {
      "get": {
        "tags": ["Identity"],
        "summary": "Get the academy + scopes for the current API key",
        "operationId": "getMe",
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/students": {
      "get": {
        "tags": ["Students"],
        "summary": "List students in the academy",
        "operationId": "listStudents",
        "security": [{ "bearerAuth": ["students:read"] }],
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudentListResponse" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/students/{id}": {
      "get": {
        "tags": ["Students"],
        "summary": "Get a single student",
        "operationId": "getStudent",
        "security": [{ "bearerAuth": ["students:read"] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StudentResponse" } } }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/courses": {
      "get": {
        "tags": ["Courses"],
        "summary": "List courses",
        "operationId": "listCourses",
        "security": [{ "bearerAuth": ["courses:read"] }],
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseListResponse" } } }
          }
        }
      }
    },
    "/courses/{id}": {
      "get": {
        "tags": ["Courses"],
        "summary": "Get a single course",
        "operationId": "getCourse",
        "security": [{ "bearerAuth": ["courses:read"] }],
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseResponse" } } }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/enrollments": {
      "get": {
        "tags": ["Enrollments"],
        "summary": "List enrollments",
        "operationId": "listEnrollments",
        "security": [{ "bearerAuth": ["enrollments:read"] }],
        "parameters": [
          { "name": "course_id", "in": "query", "schema": { "type": "string" } },
          { "name": "student_id", "in": "query", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentListResponse" } } }
          }
        }
      },
      "post": {
        "tags": ["Enrollments"],
        "summary": "Enroll a student in a course",
        "operationId": "createEnrollment",
        "security": [{ "bearerAuth": ["enrollments:write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["student_id", "course_id"],
                "properties": {
                  "student_id": { "type": "string", "description": "UUID of the student in this academy" },
                  "course_id":  { "type": "string", "description": "UUID of the course in this academy" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentResponse" } } }
          },
          "400": { "$ref": "#/components/responses/ValidationError" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/transactions": {
      "get": {
        "tags": ["Transactions"],
        "summary": "List billing transactions",
        "operationId": "listTransactions",
        "security": [{ "bearerAuth": ["transactions:read"] }],
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionListResponse" } } }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "nl_live_*",
        "description": "API key generated in Settings → Integrations → Public API. Format: `nl_live_` followed by 32 chars."
      }
    },
    "parameters": {
      "Limit":  { "name": "limit",  "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } },
      "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from a previous response's pagination.next_cursor" }
    },
    "schemas": {
      "Pagination": {
        "type": "object",
        "properties": {
          "has_more":    { "type": "boolean" },
          "next_cursor": { "type": ["string", "null"] }
        }
      },
      "Me": {
        "type": "object",
        "properties": {
          "academy_id":   { "type": "string", "format": "uuid" },
          "academy_name": { "type": "string" },
          "academy_slug": { "type": "string" },
          "plan":         { "type": "string", "enum": ["free", "basic", "premium", "enterprise"] },
          "scopes":       { "type": "array", "items": { "type": "string" } }
        }
      },
      "MeResponse": {
        "type": "object",
        "properties": { "data": { "$ref": "#/components/schemas/Me" }, "request_id": { "type": "string" } }
      },
      "Student": {
        "type": "object",
        "properties": {
          "id":         { "type": "string", "format": "uuid" },
          "email":      { "type": "string", "format": "email" },
          "full_name":  { "type": "string" },
          "phone":      { "type": ["string", "null"] },
          "status":     { "type": "string", "enum": ["active", "suspended"] },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "StudentResponse": {
        "type": "object",
        "properties": { "data": { "$ref": "#/components/schemas/Student" }, "request_id": { "type": "string" } }
      },
      "StudentListResponse": {
        "type": "object",
        "properties": {
          "data":       { "type": "array", "items": { "$ref": "#/components/schemas/Student" } },
          "pagination": { "$ref": "#/components/schemas/Pagination" },
          "request_id": { "type": "string" }
        }
      },
      "Course": {
        "type": "object",
        "properties": {
          "id":           { "type": "string", "format": "uuid" },
          "title":        { "type": "string" },
          "slug":         { "type": "string" },
          "is_published": { "type": "boolean" },
          "created_at":   { "type": "string", "format": "date-time" }
        }
      },
      "CourseResponse":     { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Course" }, "request_id": { "type": "string" } } },
      "CourseListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Course" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } },
      "Enrollment": {
        "type": "object",
        "properties": {
          "id":         { "type": "string", "format": "uuid" },
          "student_id": { "type": "string", "format": "uuid" },
          "course_id":  { "type": "string", "format": "uuid" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "EnrollmentResponse":     { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Enrollment" }, "request_id": { "type": "string" } } },
      "EnrollmentListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Enrollment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } },
      "Transaction": {
        "type": "object",
        "properties": {
          "id":         { "type": "string" },
          "amount":     { "type": "number" },
          "currency":   { "type": "string", "example": "ILS" },
          "status":     { "type": "string", "enum": ["paid", "refunded", "failed"] },
          "student_id": { "type": ["string", "null"] },
          "course_id":  { "type": ["string", "null"] },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "TransactionListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "request_id": { "type": "string" } } },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code":    { "type": "string", "enum": ["unauthorized", "forbidden_scope", "not_found", "validation_error", "rate_limited", "internal"] },
              "message": { "type": "string" }
            }
          },
          "request_id": { "type": "string" }
        }
      }
    },
    "responses": {
      "Unauthorized":    { "description": "Missing, invalid, expired, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Forbidden":       { "description": "Key lacks the scope required by this endpoint",  "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound":        { "description": "Resource does not exist in this academy",        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "ValidationError": { "description": "Request body or query parameters are invalid",   "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited":     { "description": "Exceeded the per-minute limit for this key",     "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}