{"openapi": "3.1.0", "info": {"title": "Stetson Academy Grok Connector", "version": "1.1.0", "description": "Live school data for Grok Chat (MCP) and Grok Bots (REST). Public routes need no token. Family/staff routes are scoped and FERPA-aware."}, "servers": [{"url": "https://www.stetsonacademy.com/api/grok"}], "tags": [{"name": "discovery", "description": "Instructions, catalog, health"}, {"name": "public", "description": "School facts with no student PII"}, {"name": "authorized", "description": "Scoped student/family/staff data"}, {"name": "mcp", "description": "Model Context Protocol"}], "paths": {"/": {"get": {"tags": ["discovery"], "summary": "Connector discovery card", "operationId": "getDiscovery", "responses": {"200": {"description": "Discovery JSON"}}}}, "/instructions": {"get": {"tags": ["discovery"], "summary": "Usage instructions for Grok Chat and Grok Bots", "operationId": "getInstructions", "parameters": [{"name": "format", "in": "query", "schema": {"type": "string", "enum": ["json", "markdown"]}}], "responses": {"200": {"description": "Instructions"}}}}, "/catalog": {"get": {"tags": ["discovery"], "summary": "Datasets, formats, and scopes", "operationId": "getCatalog", "responses": {"200": {"description": "Catalog"}}}}, "/openapi.json": {"get": {"tags": ["discovery"], "summary": "This OpenAPI document", "operationId": "getOpenAPI", "responses": {"200": {"description": "OpenAPI 3.1"}}}}, "/health": {"get": {"tags": ["discovery"], "summary": "Liveness", "operationId": "getHealth", "responses": {"200": {"description": "ok"}}}}, "/mcp": {"post": {"tags": ["mcp"], "summary": "Streamable HTTP MCP JSON-RPC", "operationId": "postMcp", "security": [{"bearerAuth": []}, {}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object"}}}}, "responses": {"200": {"description": "JSON-RPC response"}}}}, "/v1/school": {"get": {"tags": ["public"], "summary": "School identity", "operationId": "getSchool", "parameters": [{"name": "format", "in": "query", "schema": {"type": "string", "enum": ["json", "markdown", "jsonld"]}}], "responses": {"200": {"description": "School"}}}}, "/v1/tuition": {"get": {"tags": ["public"], "summary": "Tuition and fees", "operationId": "getTuition", "parameters": [{"name": "format", "in": "query", "schema": {"type": "string", "enum": ["json", "markdown"]}}], "responses": {"200": {"description": "Tuition"}}}}, "/v1/calendar": {"get": {"tags": ["public"], "summary": "School calendar", "operationId": "getCalendar", "parameters": [{"name": "start", "in": "query", "schema": {"type": "string", "format": "date"}}, {"name": "end", "in": "query", "schema": {"type": "string", "format": "date"}}, {"name": "types", "in": "query", "schema": {"type": "string"}}, {"name": "format", "in": "query", "schema": {"type": "string", "enum": ["json", "markdown", "ics"]}}], "responses": {"200": {"description": "Events"}}}}, "/v1/programs": {"get": {"tags": ["public"], "summary": "Public programs", "operationId": "getPrograms", "parameters": [{"name": "limit", "in": "query", "schema": {"type": "integer"}}], "responses": {"200": {"description": "Programs"}}}}, "/v1/meals": {"get": {"tags": ["public"], "summary": "Meal menus", "operationId": "getMeals", "parameters": [{"name": "date", "in": "query", "schema": {"type": "string", "format": "date"}}, {"name": "orders", "in": "query", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Menus"}}}}, "/v1/search": {"get": {"tags": ["public"], "summary": "Unified public search", "operationId": "searchPublic", "parameters": [{"name": "q", "in": "query", "required": true, "schema": {"type": "string"}}, {"name": "limit", "in": "query", "schema": {"type": "integer"}}], "responses": {"200": {"description": "Hits"}}}}, "/v1/knowledge": {"get": {"tags": ["public"], "summary": "FAQ / knowledge search", "operationId": "searchKnowledge", "parameters": [{"name": "q", "in": "query", "schema": {"type": "string"}}], "responses": {"200": {"description": "Items"}}}}, "/v1/games": {"get": {"tags": ["public"], "summary": "Published grok.me games", "operationId": "getGames", "responses": {"200": {"description": "Games"}}}}, "/v1/students": {"get": {"tags": ["authorized"], "summary": "Authorized students", "operationId": "listStudents", "security": [{"bearerAuth": ["family", "staff"]}], "parameters": [{"name": "q", "in": "query", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "schema": {"type": "integer"}}, {"name": "format", "in": "query", "schema": {"type": "string", "enum": ["json", "csv"]}}], "responses": {"200": {"description": "Students"}, "401": {"description": "Auth required"}}}}, "/v1/students/{student_id}": {"get": {"tags": ["authorized"], "summary": "One authorized student", "operationId": "getStudent", "security": [{"bearerAuth": ["family", "staff"]}], "parameters": [{"name": "student_id", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Student"}, "403": {"description": "Not in allowlist"}}}}, "/v1/students/{student_id}/progress": {"get": {"tags": ["authorized"], "summary": "Learning progress for one authorized student", "operationId": "getStudentProgress", "security": [{"bearerAuth": ["progress", "family", "staff"]}], "parameters": [{"name": "student_id", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Progress"}}}}}, "components": {"securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer", "bearerFormat": "API key or OAuth access token", "description": "Authorization: Bearer sa_gc_live_\u2026 or gcat_\u2026 Never place tokens in the query string."}}}, "externalDocs": {"description": "MCP endpoint", "url": "https://www.stetsonacademy.com/api/grok/mcp"}}