{ "openapi": "3.1.0", "info": { "title": "Scorpy Makeup Academy — public API", "version": "1.0.0", "description": "MAKEUP ACADEMY\n\nEndpoints under `/api/v1/public` are unauthenticated. Everything else requires a Supabase access token in `Authorization: Bearer `. Site pages are separately available as Markdown via `Accept: text/markdown` (acceptmarkdown.com).", "contact": { "url": "https://scorpy.studioplatform.site/" } }, "servers": [ { "url": "https://scorpy.studioplatform.site", "description": "Public origin (proxies /api to the backend)" } ], "externalDocs": { "description": "Agent index", "url": "https://scorpy.studioplatform.site/llms.txt" }, "tags": [ { "name": "public", "description": "Unauthenticated tenant content" }, { "name": "checkout", "description": "Course purchase" }, { "name": "students", "description": "Enrolment and profile (authenticated)" }, { "name": "playback", "description": "Lesson video access (authenticated)" }, { "name": "auth", "description": "Password reset" }, { "name": "system", "description": "Liveness" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Supabase access token." } }, "schemas": { "Link": { "type": "object", "required": [ "label", "href" ], "properties": { "label": { "type": "string" }, "href": { "type": "string" } } }, "Media": { "type": "object", "required": [ "src", "alt", "shape" ], "properties": { "src": { "type": [ "string", "null" ] }, "alt": { "type": "string" }, "shape": { "type": "string", "enum": [ "portrait", "square", "wide", "arch", "tall" ] } } }, "Block": { "type": "object", "required": [ "id", "type", "props" ], "description": "One section of the published page. `type` selects the renderer; `props` is that renderer’s shape.", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "header", "hero", "about", "features", "gallery", "faq", "stats", "contact", "courses", "ctaBand", "testimonials", "benefits", "instagramStrip", "logos", "video", "intro", "promoBand", "community", "videoTestimonials", "whatsappProps", "services", "footer" ] }, "page": { "type": "string", "description": "Which site page the block belongs to. Absent = home." }, "props": { "type": "object", "additionalProperties": true } } }, "Landing": { "type": "object", "required": [ "tenant", "theme", "page" ], "properties": { "tenant": { "type": "object", "required": [ "slug", "name", "logoText" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "logoText": { "type": "string" }, "tagline": { "type": [ "string", "null" ] }, "plan": { "type": "string", "enum": [ "Basic Landing", "Premium Academy" ] } } }, "theme": { "type": "object", "additionalProperties": true }, "page": { "type": "object", "required": [ "seo", "blocks" ], "properties": { "seo": { "$ref": "#/components/schemas/Seo" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/Block" } } } }, "domains": { "type": "object", "properties": { "primary": { "type": "string" }, "canonicalOrigin": { "type": "string", "format": "uri" } } } } }, "Seo": { "type": "object", "required": [ "title", "description" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "language": { "type": "string", "description": "BCP-47 tag; default \"he\"." }, "ogImage": { "type": [ "string", "null" ], "format": "uri" }, "robotsIndex": { "type": "boolean" } } }, "Lesson": { "type": "object", "required": [ "id", "title", "type", "isPreview", "hasVideo" ], "description": "Carries no video URL by design — a playable URL comes from /api/v1/playback after an enrolment check.", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "video", "text", "quiz", "resource" ] }, "content": { "type": [ "string", "null" ] }, "isPreview": { "type": "boolean" }, "hasVideo": { "type": "boolean" } } }, "Chapter": { "type": "object", "required": [ "id", "title", "lessons" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "lessons": { "type": "array", "items": { "$ref": "#/components/schemas/Lesson" } } } }, "Course": { "type": "object", "required": [ "id", "title", "description", "priceCents", "currency", "chapters" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "priceCents": { "type": "integer", "minimum": 0 }, "discountPriceCents": { "type": [ "integer", "null" ], "minimum": 0 }, "discountStartsAt": { "type": [ "string", "null" ], "format": "date-time" }, "discountEndsAt": { "type": [ "string", "null" ], "format": "date-time" }, "currency": { "type": "string", "examples": [ "ILS" ] }, "thumbnailUrl": { "type": [ "string", "null" ], "format": "uri" }, "chapters": { "type": "array", "items": { "$ref": "#/components/schemas/Chapter" } } } }, "Error": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "message": { "type": [ "string", "array" ] }, "error": { "type": "string" } } } }, "responses": { "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/api/health": { "get": { "tags": [ "system" ], "summary": "Liveness probe", "operationId": "getHealth", "responses": { "200": { "description": "Service is up", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/public/landing": { "get": { "tags": [ "public" ], "summary": "Published page configuration for a tenant", "description": "The full published site: brand, theme and the ordered blocks the page renders. This is what the server-rendered HTML is built from.", "operationId": "getLanding", "parameters": [ { "name": "host", "in": "query", "required": false, "description": "Tenant hostname to resolve. Defaults to the host the request arrived on.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Published landing configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Landing" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/public/courses": { "get": { "tags": [ "public" ], "summary": "Published course catalog", "description": "Every published course with its chapter/lesson outline. Lesson video URLs are deliberately absent.", "operationId": "listCourses", "parameters": [ { "name": "host", "in": "query", "required": false, "description": "Tenant hostname to resolve. Defaults to the host the request arrived on.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Published courses", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Course" } } } } } } } }, "/api/v1/checkout/demo": { "post": { "tags": [ "checkout" ], "summary": "Purchase a course (demo flow)", "description": "Records the purchase and emails an access link. Rate limited to 5 requests per minute per IP. Returns 403 when DEMO_CHECKOUT is off.", "operationId": "demoCheckout", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "host", "courseId", "email" ], "properties": { "host": { "type": "string", "maxLength": 255 }, "courseId": { "type": "string", "minLength": 1, "maxLength": 100 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "termsVersion": { "type": "string", "maxLength": 40, "description": "Version of the terms the buyer accepted." } } } } } }, "responses": { "201": { "description": "Purchase recorded", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Demo checkout disabled on this server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Rate limited" } } } }, "/api/v1/students/me": { "get": { "tags": [ "students" ], "summary": "The signed-in student and their enrolments", "operationId": "getStudentMe", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "host", "in": "query", "required": false, "description": "Tenant hostname to resolve. Defaults to the host the request arrived on.", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Student profile and enrolments", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/students/enroll": { "post": { "tags": [ "students" ], "summary": "Enrol the signed-in student in a free course", "operationId": "enrollStudent", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "courseId" ], "properties": { "courseId": { "type": "string" }, "host": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } } } } } }, "responses": { "201": { "description": "Enrolment created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "courseId missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/playback/{courseId}/{lessonId}": { "get": { "tags": [ "playback" ], "summary": "Time-limited playback URL for one lesson", "description": "The only endpoint that returns a lesson video URL, and only after checking enrolment and the single-device seat.", "operationId": "getPlaybackUrl", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "courseId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "lessonId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "host", "in": "query", "required": false, "description": "Tenant hostname to resolve. Defaults to the host the request arrived on.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "x-session-id", "in": "header", "required": false, "description": "Device seat id issued by /api/v1/sessions/claim.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signed playback URL", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Another device holds the seat" }, "429": { "description": "Rate limited" } } } }, "/api/v1/auth/forgot-password": { "post": { "tags": [ "auth" ], "summary": "Send a password-reset email", "description": "Always answers 200/201 regardless of whether the address exists — the response must not reveal account existence.", "operationId": "forgotPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "host": { "type": "string" } } } } } }, "responses": { "201": { "description": "Accepted (whether or not the account exists)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } } } }