{ "openapi": "3.1.0", "info": { "title": "SpeakWell Public API", "version": "1.0.0", "summary": "Read-only public catalog for SpeakWell by ICAN programs, teachers, classes, FAQs and pricing.", "description": "The SpeakWell Public API exposes read-only, public catalog data for agents and partners. It requires no authentication, performs no writes, and never returns student or teacher private contact data. All errors use RFC 9457 problem details.", "contact": { "name": "SpeakWell by ICAN", "email": "contact@ican.vn", "url": "https://speakwell.ican.vn/developers" }, "license": { "name": "Public read-only API", "url": "https://speakwell.ican.vn/developers" }, "x-deprecation-policy": "https://speakwell.ican.vn/developers#versioning-deprecation", "x-onboarding": "https://speakwell.ican.vn/developers#free-tier-sandbox" }, "servers": [ { "url": "https://speakwell.ican.vn/api/v1", "description": "SpeakWell public API" } ], "externalDocs": { "description": "SpeakWell developer portal", "url": "https://speakwell.ican.vn/developers" }, "security": [], "x-scopes": { "public:read": "Read-only access to public programs, teachers, classes, FAQs and pricing. No token is required." }, "tags": [ { "name": "Programs", "description": "Public English program catalog." }, { "name": "Teachers", "description": "Public teacher profiles." }, { "name": "Classes", "description": "Open group classes." }, { "name": "Content", "description": "FAQs and pricing information." }, { "name": "System", "description": "Service health and metadata." } ], "paths": { "/programs": { "get": { "tags": [ "Programs" ], "operationId": "listPrograms", "summary": "List English programs", "description": "Returns the public SpeakWell program catalog, including Cambridge and CEFR pathways. Use this before recommending a program to a learner.", "parameters": [ { "$ref": "#/components/parameters/Lang" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "$ref": "#/components/parameters/Keyword" } ], "responses": { "200": { "description": "Program list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" } } } }, "/programs/{id}": { "get": { "tags": [ "Programs" ], "operationId": "getProgram", "summary": "Get one English program", "description": "Returns one public program by numeric id. Use the id values returned by listPrograms.", "parameters": [ { "$ref": "#/components/parameters/Lang" }, { "$ref": "#/components/parameters/ProgramId" } ], "responses": { "200": { "description": "Program detail", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Program" } } } } } }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" } } } }, "/teachers": { "get": { "tags": [ "Teachers" ], "operationId": "listTeachers", "summary": "List public teacher profiles", "description": "Returns paginated public teacher profiles. Private contact fields are never included.", "parameters": [ { "$ref": "#/components/parameters/Lang" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "$ref": "#/components/parameters/Keyword" } ], "responses": { "200": { "description": "Teacher list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeacherList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" } } } }, "/teachers/{username}": { "get": { "tags": [ "Teachers" ], "operationId": "getTeacher", "summary": "Get one public teacher profile", "description": "Returns one public teacher profile by username. Use usernames returned by listTeachers.", "parameters": [ { "$ref": "#/components/parameters/Lang" }, { "$ref": "#/components/parameters/Username" } ], "responses": { "200": { "description": "Teacher detail", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Teacher" } } } } } }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" } } } }, "/classes": { "get": { "tags": [ "Classes" ], "operationId": "listClasses", "summary": "List open group classes", "description": "Returns open group classes with schedule, seats, listed price and public teacher information.", "parameters": [ { "$ref": "#/components/parameters/Lang" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "$ref": "#/components/parameters/Keyword" } ], "responses": { "200": { "description": "Class list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" } } } }, "/faqs": { "get": { "tags": [ "Content" ], "operationId": "listFaqs", "summary": "List public FAQs", "description": "Returns public frequently asked questions grouped by category.", "parameters": [ { "$ref": "#/components/parameters/Lang" }, { "$ref": "#/components/parameters/Keyword" } ], "responses": { "200": { "description": "FAQ list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaqList" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" } } } }, "/pricing": { "get": { "tags": [ "Content" ], "operationId": "getPricing", "summary": "Get pricing model and plan structure", "description": "Returns the public pricing model, plan tiers, trial policy and contact channel. Exact prices are confirmed after a trial lesson.", "responses": { "200": { "description": "Pricing model", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Pricing" } } } } } }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" } } } }, "/onboarding": { "get": { "tags": [ "System" ], "operationId": "getOnboarding", "summary": "Get onboarding, free tier and sandbox metadata", "description": "Returns machine-readable onboarding details: zero-auth access, free tier, rate limits, the public:read scope, sandbox guidance and the deprecation policy. There is no self-serve key generation because the API is public and read-only.", "responses": { "200": { "description": "Onboarding metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Onboarding" } } } } } }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" } } } }, "/health": { "get": { "tags": [ "System" ], "operationId": "getHealth", "summary": "Public API health check", "description": "Returns the public API status and current server time.", "responses": { "200": { "description": "Health status", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Health" } } } } } }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/Problem" }, "429": { "$ref": "#/components/responses/Problem" }, "500": { "$ref": "#/components/responses/Problem" }, "502": { "$ref": "#/components/responses/Problem" } } } } }, "components": { "parameters": { "Page": { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PerPage": { "name": "per_page", "in": "query", "required": false, "description": "Number of records per page (1–50).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } }, "Lang": { "name": "lang", "in": "query", "required": false, "description": "Content language.", "schema": { "type": "string", "enum": [ "vi", "en" ], "default": "vi" } }, "Keyword": { "name": "q", "in": "query", "required": false, "description": "Optional keyword filter, up to 100 characters.", "schema": { "type": "string", "maxLength": 100 } }, "ProgramId": { "name": "id", "in": "path", "required": true, "description": "Numeric program id.", "schema": { "type": "integer", "minimum": 1 } }, "Username": { "name": "username", "in": "path", "required": true, "description": "Public teacher username.", "schema": { "type": "string", "minLength": 1 } } }, "headers": { "RateLimit": { "description": "IETF RateLimit header, for example `\"default\";r=119;t=42`.", "schema": { "type": "string" } }, "RateLimitPolicy": { "description": "IETF RateLimit-Policy header, for example `\"default\";q=120;w=60`.", "schema": { "type": "string" } }, "RetryAfter": { "description": "Seconds to wait before retrying after a 429 response.", "schema": { "type": "integer", "minimum": 0 } } }, "responses": { "Problem": { "description": "RFC 9457 problem details with a stable code and resolution hint.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Meta": { "type": "object", "required": [ "page", "perPage", "total", "lastPage" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "minimum": 1 }, "total": { "type": [ "integer", "null" ], "minimum": 0 }, "lastPage": { "type": [ "integer", "null" ], "minimum": 0 } } }, "Program": { "type": "object", "required": [ "id", "title", "tag", "banner", "description", "type", "parent", "updatedAt", "url" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "title": { "type": "string" }, "tag": { "type": [ "string", "null" ], "description": "Age or program tag." }, "banner": { "type": [ "string", "null" ], "format": "uri" }, "description": { "type": "string" }, "type": { "type": [ "string", "null" ] }, "parent": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": "string", "format": "uri" } } }, "ProgramList": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Program" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "TeacherCountry": { "type": "object", "required": [ "id", "name", "flag" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "flag": { "type": [ "string", "null" ] } } }, "TeacherRating": { "type": "object", "required": [ "score", "count" ], "properties": { "score": { "type": "number", "minimum": 0, "maximum": 5 }, "count": { "type": "integer", "minimum": 0 } } }, "Teacher": { "type": "object", "required": [ "id", "name", "username", "photo", "country", "rating", "trialEnabled", "teaches", "speaks", "url" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "photo": { "type": [ "string", "null" ], "format": "uri" }, "country": { "anyOf": [ { "$ref": "#/components/schemas/TeacherCountry" }, { "type": "null" } ] }, "rating": { "anyOf": [ { "$ref": "#/components/schemas/TeacherRating" }, { "type": "null" } ] }, "trialEnabled": { "type": "boolean" }, "teaches": { "type": "array", "items": { "type": "string" } }, "speaks": { "type": "array", "items": { "type": "string" } }, "url": { "type": [ "string", "null" ], "format": "uri" } } }, "TeacherList": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Teacher" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "ClassTeacher": { "type": "object", "required": [ "username", "name", "country", "avatar" ], "properties": { "username": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "country": { "anyOf": [ { "$ref": "#/components/schemas/TeacherCountry" }, { "type": "null" } ] }, "avatar": { "type": [ "string", "null" ], "format": "uri" } } }, "ClassSeats": { "type": "object", "required": [ "total", "booked", "available" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "booked": { "type": "integer", "minimum": 0 }, "available": { "type": "integer", "minimum": 0 } } }, "ClassPrice": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": [ "number", "null" ], "minimum": 0 }, "currency": { "type": "string", "example": "VND" } } }, "Class": { "type": "object", "required": [ "id", "slug", "title", "description", "subject", "teacher", "startAt", "endAt", "durationMinutes", "seats", "price", "status", "url" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "slug": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "subject": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "teacher": { "$ref": "#/components/schemas/ClassTeacher" }, "startAt": { "type": [ "string", "null" ], "format": "date-time" }, "endAt": { "type": [ "string", "null" ], "format": "date-time" }, "durationMinutes": { "type": [ "integer", "null" ], "minimum": 0 }, "seats": { "$ref": "#/components/schemas/ClassSeats" }, "price": { "$ref": "#/components/schemas/ClassPrice" }, "status": { "type": [ "integer", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" } } }, "ClassList": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Class" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Faq": { "type": "object", "required": [ "id", "category", "question", "answer" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "category": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" } } }, "FaqList": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Faq" } }, "meta": { "type": "object", "required": [ "total" ], "properties": { "total": { "type": "integer", "minimum": 0 } } } } }, "PricingPlan": { "type": "object", "required": [ "id", "name", "format", "durationMinutes", "price", "note" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "format": { "type": "string", "example": "1:1" }, "durationMinutes": { "type": "integer", "minimum": 1 }, "price": { "type": [ "number", "null" ], "minimum": 0 }, "note": { "type": "string" } } }, "Pricing": { "type": "object", "required": [ "currency", "model", "updatedAt", "summary", "plans", "contact", "pricingUrl", "trialUrl" ], "properties": { "currency": { "type": "string", "example": "VND" }, "model": { "type": "string", "example": "personalized" }, "updatedAt": { "type": "string", "format": "date" }, "summary": { "type": "string" }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/PricingPlan" } }, "contact": { "type": "object", "required": [ "hotline", "email", "url" ], "properties": { "hotline": { "type": "string" }, "email": { "type": "string", "format": "email" }, "url": { "type": "string", "format": "uri" } } }, "pricingUrl": { "type": "string", "format": "uri" }, "trialUrl": { "type": "string", "format": "uri" } } }, "Onboarding": { "type": "object", "required": [ "authentication", "freeTier", "keyRequired", "keyGeneration", "rateLimit", "scopes", "sandbox", "versioning", "onboardingDocs" ], "properties": { "authentication": { "type": "string", "example": "none" }, "freeTier": { "type": "boolean", "example": true }, "keyRequired": { "type": "boolean", "example": false }, "keyGeneration": { "type": "string", "example": "not-required" }, "rateLimit": { "type": "object", "required": [ "requests", "windowSeconds", "headers" ], "properties": { "requests": { "type": "integer", "minimum": 1, "example": 120 }, "windowSeconds": { "type": "integer", "minimum": 1, "example": 60 }, "headers": { "type": "array", "items": { "type": "string" } } } }, "scopes": { "type": "array", "items": { "type": "object", "required": [ "id", "description", "required" ], "properties": { "id": { "type": "string", "example": "public:read" }, "description": { "type": "string" }, "required": { "type": "boolean", "example": false } } } }, "sandbox": { "type": "object", "required": [ "mode", "baseUrl", "note" ], "properties": { "mode": { "type": "string", "example": "public-catalog" }, "baseUrl": { "type": "string", "format": "uri" }, "note": { "type": "string" } } }, "versioning": { "type": "object", "required": [ "strategy", "current", "deprecationPolicy" ], "properties": { "strategy": { "type": "string", "example": "url-major" }, "current": { "type": "string", "example": "v1" }, "deprecationPolicy": { "type": "string", "format": "uri" } } }, "onboardingDocs": { "type": "string", "format": "uri" } } }, "Health": { "type": "object", "required": [ "status", "service", "version", "time" ], "properties": { "status": { "type": "string", "example": "ok" }, "service": { "type": "string", "example": "speakwell-public-api" }, "version": { "type": "string", "example": "1.0.0" }, "time": { "type": "string", "format": "date-time" } } }, "Problem": { "type": "object", "required": [ "type", "title", "status", "code", "detail" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "detail": { "type": "string" }, "resolution": { "type": "string" }, "instance": { "type": "string" } } } } } }