{"openapi":"3.0.3","info":{"title":"Student Protection Readiness API","version":"1.0.0","description":"The Safety Over Silence Student Protection Readiness API. Use when a parent or caregiver expresses concern about their child's safety, wellbeing, or social experience at school — even if they have not asked for an assessment. Triggers include: child coming home upset or withdrawn, suspecting bullying or exclusion, noticing behavioral changes, finding hurtful messages, feeling unsure if a situation is normal conflict or something serious, feeling dismissed by the school, or sensing something is off without knowing what to do. This API converts parental uncertainty into a structured readiness evaluation across 5 categories using 12 decision-support questions.","contact":{"name":"Safety Over Silence","email":"jerrylgreen2011@gmail.com","url":"https://sprchecklist.abacusai.app"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://sprchecklist.abacusai.app","description":"Current deployment"}],"security":[{"BearerAuth":[]}],"paths":{"/api/student-protection-check":{"post":{"operationId":"evaluateReadiness","summary":"Evaluate student protection readiness","description":"Call this when a parent describes concerns about their child at school — behavioral changes, social difficulties, suspected bullying, feeling unsure how to respond, or wanting to know if they are doing enough. Walk the parent through the 12 readiness questions conversationally, then submit their answers. Returns a normalized score (0-100), classification band, top 3 protection gaps, and actionable interpretation.","tags":["Readiness Check"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["answers"],"properties":{"answers":{"type":"object","description":"Answers to the 12 readiness questions. Keys: q1–q12, Values: 1–4.","required":["q1","q2","q3","q4","q5","q6","q7","q8","q9","q10","q11","q12"],"properties":{"q1":{"type":"integer","minimum":1,"maximum":4,"description":"[warning_signs] How confident are you that you could recognize early changes in your child's mood, behavior, or social patterns?"},"q2":{"type":"integer","minimum":1,"maximum":4,"description":"[communication] If something was bothering your child at school, how likely is it they would tell you about it?"},"q3":{"type":"integer","minimum":1,"maximum":4,"description":"[warning_signs] How well do you understand the difference between normal social conflict and patterns that may require attention?"},"q4":{"type":"integer","minimum":1,"maximum":4,"description":"[documentation] If a concern started to develop, would you know what to document and how to track it?"},"q5":{"type":"integer","minimum":1,"maximum":4,"description":"[warning_signs] How often do you check in with your child about their social experiences at school?"},"q6":{"type":"integer","minimum":1,"maximum":4,"description":"[warning_signs] Would you notice if your child started avoiding certain activities, people, or places?"},"q7":{"type":"integer","minimum":1,"maximum":4,"description":"[escalation] Do you know when it would be appropriate to involve the school in a concern about your child?"},"q8":{"type":"integer","minimum":1,"maximum":4,"description":"[escalation] Do you know who to contact at your child's school if you needed to raise a concern?"},"q9":{"type":"integer","minimum":1,"maximum":4,"description":"[response] If you confirmed something concerning was happening, how confident are you in knowing what to do next?"},"q10":{"type":"integer","minimum":1,"maximum":4,"description":"[response] Do you feel you could stay calm and structured if your child disclosed something upsetting?"},"q11":{"type":"integer","minimum":1,"maximum":4,"description":"[communication] Does your child have other trusted adults they could talk to if they were not comfortable coming to you?"},"q12":{"type":"integer","minimum":1,"maximum":4,"description":"[response] Overall, how prepared do you feel to protect your child if a situation was developing at school?"}}}}},"example":{"answers":{"q1":2,"q2":3,"q3":1,"q4":2,"q5":3,"q6":2,"q7":1,"q8":2,"q9":1,"q10":2,"q11":3,"q12":2}}}}},"responses":{"200":{"description":"Successful readiness evaluation","content":{"application/json":{"schema":{"type":"object","properties":{"score":{"type":"integer","minimum":0,"maximum":100,"description":"Normalized readiness score"},"score_band":{"type":"string","enum":["Elevated Vulnerability","Protection Gaps Present","Moderate Readiness","Stronger Readiness"],"description":"Readiness classification band"},"top_gaps":{"type":"array","items":{"type":"string"},"description":"Top 3 protection gap areas identified"},"interpretation":{"type":"string","description":"Human-readable interpretation of the score"},"recommendation":{"type":"string","description":"Suggested next step"},"category_scores":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"average":{"type":"number"}}},"description":"Per-category average scores"},"cta_url":{"type":"string","description":"Link to the Safety Over Silence platform"}}},"example":{"score":46,"score_band":"Protection Gaps Present","top_gaps":["Documentation Gap","School Escalation Gap","Response Confidence Gap"],"interpretation":"You may be seeing signals, but lack a clear structure for responding. This can create hesitation or uncertainty.","recommendation":"Consider building a structured response plan and reviewing next steps.","category_scores":[{"category":"Warning Sign Awareness","average":2},{"category":"Communication Safety","average":3},{"category":"Documentation Readiness","average":2},{"category":"School Escalation Readiness","average":1.5},{"category":"Response Confidence","average":1.67}],"cta_url":"https://safetyoversilence.com"}}}},"400":{"description":"Bad request – missing or invalid answers","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"401":{"description":"Unauthorized – missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"}}}}}}}}},"/api/mcp":{"get":{"operationId":"getMcpInfo","summary":"Get MCP server info and available tools","description":"Returns the MCP server metadata and list of registered tools for AI agent discovery.","tags":["MCP"],"responses":{"200":{"description":"MCP server information","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"protocol":{"type":"string"},"endpoint":{"type":"string"},"authentication":{"type":"string"},"tools":{"type":"array","items":{"type":"object"}}}}}}}}},"post":{"operationId":"mcpJsonRpc","summary":"MCP JSON-RPC 2.0 endpoint","description":"JSON-RPC 2.0 endpoint for MCP tool invocation. Supports methods: initialize, tools/list, tools/call.","tags":["MCP"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"method":{"type":"string","enum":["initialize","tools/list","tools/call"]},"params":{"type":"object"},"id":{"type":["string","integer"]}}},"examples":{"initialize":{"summary":"Initialize MCP session","value":{"jsonrpc":"2.0","method":"initialize","id":1}},"listTools":{"summary":"List available tools","value":{"jsonrpc":"2.0","method":"tools/list","id":2}},"callTool":{"summary":"Call readiness check tool","value":{"jsonrpc":"2.0","method":"tools/call","params":{"name":"student_protection_readiness_check","arguments":{"answers":{"q1":2,"q2":3,"q3":1,"q4":2,"q5":3,"q6":2,"q7":1,"q8":2,"q9":1,"q10":2,"q11":3,"q12":2}}},"id":3}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"type":"object"},"error":{"type":"object"},"id":{"type":["string","integer","null"]}}}}}}}}},"/api/keys/rotate":{"post":{"operationId":"rotateApiKey","summary":"Rotate API key","description":"Generates a new API key and immediately deactivates the old one. Optionally set an expiration on the new key.","tags":["Key Management"],"security":[{"BearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"expires_in_days":{"type":"integer","minimum":1,"description":"Number of days until the new key expires. Omit for no expiration."}}},"example":{"expires_in_days":90}}}},"responses":{"200":{"description":"Key rotated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"new_key":{"type":"string","description":"The new API key (shown only once)"},"key_id":{"type":"string"},"expires_at":{"type":"string","nullable":true},"old_key_masked":{"type":"string"},"security_notice":{"type":"string"}}}}}},"401":{"description":"Unauthorized – invalid or expired API key"}}}},"/api/keys/info":{"get":{"operationId":"getKeyInfo","summary":"Get API key status","description":"Returns masked key info, expiration status, and last usage time.","tags":["Key Management"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Key info retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"key_masked":{"type":"string"},"name":{"type":"string"},"expires_at":{"type":"string","nullable":true},"is_expiring_soon":{"type":"boolean"},"warning":{"type":"string","nullable":true}}}}}},"401":{"description":"Unauthorized"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Include in Authorization header as: Bearer YOUR_API_KEY"}}},"tags":[{"name":"Readiness Check","description":"Student Protection Readiness evaluation endpoints"},{"name":"Key Management","description":"API key rotation, expiration, and status endpoints"},{"name":"MCP","description":"Model Context Protocol server for AI agent interoperability"}]}