{"openapi":"3.1.0","info":{"title":"MIDA Core API","version":"0.2.0","description":"Universal, child-safe, English and Simplified Chinese educational intelligence backend by Sky Education.","x-mida-supported-languages":["en","zh-CN"]},"servers":[{"url":"/api/v1","description":"Current deployment"}],"tags":[{"name":"System","description":"Health and capability discovery"},{"name":"Intelligence","description":"Adaptive child-safe explanation pipeline"},{"name":"Learners","description":"Consent-aware learner profiles"},{"name":"Administration","description":"Tenant and application provisioning"}],"paths":{"/health":{"get":{"tags":["System"],"summary":"Check MIDA Core health","responses":{"200":{"description":"Service is available"}}}},"/capabilities":{"get":{"tags":["System"],"summary":"Discover active capabilities","responses":{"200":{"description":"Capability manifest"}}}},"/chat":{"post":{"tags":["Intelligence"],"summary":"Generate an age-adaptive, safety-checked explanation","security":[{"ApiKey":[]},{}],"parameters":[{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/ClientId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}},"responses":{"200":{"description":"Structured MIDA response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/learners":{"post":{"tags":["Learners"],"summary":"Create or update a tenant-scoped learner","security":[{"ApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/ClientId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LearnerUpsert"}}}},"responses":{"200":{"description":"Learner profile"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/learners/{learnerId}":{"get":{"tags":["Learners"],"summary":"Read a tenant-scoped learner profile","security":[{"ApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/ClientId"},{"name":"learnerId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Learner profile"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Learner not found"}}},"delete":{"tags":["Learners"],"summary":"Delete a learner and all dependent records","security":[{"ApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/ClientId"},{"name":"learnerId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-mida-confirm-delete","in":"header","required":true,"schema":{"type":"string"},"description":"Must exactly match learnerId."}],"responses":{"204":{"description":"Learner and dependent records deleted"},"404":{"description":"Learner not found"}}}},"/learners/{learnerId}/consents":{"post":{"tags":["Learners"],"summary":"Record educational-history consent or withdrawal","security":[{"ApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/ClientId"},{"name":"learnerId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentInput"}}}},"responses":{"201":{"description":"Consent record created"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/learners/{learnerId}/memories":{"get":{"tags":["Learners"],"summary":"List consented educational memory","security":[{"ApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/ClientId"},{"name":"learnerId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Educational memories"},"403":{"description":"Active consent required"}}},"post":{"tags":["Learners"],"summary":"Add consented educational memory","security":[{"ApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/TenantId"},{"$ref":"#/components/parameters/ClientId"},{"name":"learnerId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryInput"}}}},"responses":{"201":{"description":"Educational memory created"},"403":{"description":"Active consent required"}}}},"/admin/bootstrap":{"post":{"tags":["Administration"],"summary":"Provision a tenant and first application client","security":[{"AdminKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tenantName","clientName"],"properties":{"tenantName":{"type":"string","maxLength":120},"clientName":{"type":"string","maxLength":120}}}}}},"responses":{"201":{"description":"Tenant and client identifiers"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/clients/{clientId}/revoke":{"post":{"tags":["Administration"],"summary":"Revoke an application client credential","security":[{"AdminKey":[]}],"parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Application client revoked"},"404":{"description":"Application client not found"}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-mida-api-key"},"AdminKey":{"type":"apiKey","in":"header","name":"x-mida-admin-key"}},"parameters":{"TenantId":{"name":"x-mida-tenant-id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},"ClientId":{"name":"x-mida-client-id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}}},"responses":{"BadRequest":{"description":"Request validation failed"},"Unauthorized":{"description":"Missing or invalid MIDA API key"}},"schemas":{"ConversationMessage":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","maxLength":4000}}},"ChatRequest":{"type":"object","required":["message","learner","requestedDepth","history","consent"],"properties":{"message":{"type":"string","minLength":1,"maxLength":1000},"learner":{"type":"object","required":["age","language"],"properties":{"age":{"type":"integer","minimum":4,"maximum":18},"language":{"type":"string","examples":["en","zh-CN"]},"displayName":{"type":"string","maxLength":80}}},"requestedDepth":{"type":"string","enum":["simple","balanced","deep"]},"history":{"type":"array","maxItems":12,"items":{"$ref":"#/components/schemas/ConversationMessage"}},"consent":{"type":"object","required":["persistEducationalHistory"],"properties":{"persistEducationalHistory":{"type":"boolean","default":false}}},"learnerId":{"type":"string","format":"uuid"},"sessionId":{"type":"string","format":"uuid"}}},"ChatResponse":{"type":"object","required":["answer","traceId","safety","pedagogy","provider","memory","apiVersion","policyVersion"],"properties":{"answer":{"type":"string"},"traceId":{"type":"string","format":"uuid"},"safety":{"type":"object","properties":{"decision":{"type":"string","enum":["allow","support","redirect","block"]},"category":{"type":"string"},"riskLevel":{"type":"string","enum":["none","low","high","critical"]}}},"pedagogy":{"type":"object","properties":{"ageBand":{"type":"string","enum":["early","middle","teen"]},"depth":{"type":"string","enum":["simple","balanced","deep"]},"strategy":{"type":"string"},"sentenceTarget":{"type":"integer"}}},"provider":{"type":"object","properties":{"name":{"type":"string"},"mode":{"type":"string","enum":["demo","connected"]}}},"memory":{"type":"object","properties":{"persisted":{"type":"boolean"},"reason":{"type":"string"}}},"apiVersion":{"type":"string","const":"v1"},"policyVersion":{"type":"string","const":"child-safety-2026-08-20"}}},"LearnerUpsert":{"type":"object","required":["externalRef","age","language"],"properties":{"externalRef":{"type":"string","maxLength":120},"displayName":{"type":"string","maxLength":80},"age":{"type":"integer","minimum":4,"maximum":18},"language":{"type":"string","examples":["en","zh-CN"]}}},"ConsentInput":{"type":"object","required":["guardianRef","scope","status"],"properties":{"guardianRef":{"type":"string","maxLength":120},"scope":{"type":"string","const":"educational_history"},"status":{"type":"string","enum":["granted","withdrawn"]},"expiresAt":{"type":"string","format":"date-time"}}},"MemoryInput":{"type":"object","required":["kind","subject","content"],"properties":{"kind":{"type":"string","enum":["mastery","misconception","preference","interest","goal"]},"subject":{"type":"string","maxLength":120},"content":{"type":"string","maxLength":1000},"confidence":{"type":"integer","minimum":0,"maximum":100,"default":50},"expiresAt":{"type":"string","format":"date-time"}}}}}}